@shopify/flash-list

Q: Como instalo o FlashList no Expo SDK 57?

Fixa uma versão compatível para o seu SDK. Reconstrua o cliente de desenvolvimento se o autolinking mudar.

Q: Qual deve ser o estimatedItemSize?

Meça 5–10 linhas representativas - use a altura mediana. Inclua padding e separadores. Estimativas incorretas causam saltos na rolagem, não travamentos.

Q: O FlashList funciona com useInfiniteQuery?

Sim - onEndReached / onEndReachedThreshold igual ao FlatList. Veja Scroll Infinito & Paginação.

Q: Onde está o guia de comparação completo?

FlashList vs FlatList - trade-offs antes de migrar

Q: Devo usar memo em todas as linhas?

Sim para listas recicladas - combine memo na linha, renderItem estável e estado apenas de props.

Checklist de atualização de desempenho de lista para integração direta. FlashList recicla um pequeno conjunto de visualizações nativas - FlatList monta mais linhas fora da tela. Use este cookbook quando o profiling mostrar lentidão na rolagem em feeds; para trade-offs e ajuste, veja FlashList vs FlatList.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

npx expo install @shopify/flash-list

import { FlashList } from "@shopify/flash-list";
import { StyleSheet, Text, View } from "react-native";
 
interface Post {
  id: string;
  title: string;
}
 
const ESTIMATED_ROW_HEIGHT = 88;
 
export function PostFeed({ posts }: { posts: Post[] }) {
  return (
    <FlashList
      data={posts}
      estimatedItemSize={ESTIMATED_ROW_HEIGHT}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View style={styles.row}>
          <Text style={styles.title} numberOfLines={2}>
            {item.title}
          </Text>
        </View>
      )}
      ItemSeparatorComponent={() => <View style={styles.separator} />}
    />
  );
}
 
const styles = StyleSheet.create({
  row: { paddingHorizontal: 16, paddingVertical: 12, backgroundColor: "#fff", minHeight: ESTIMATED_ROW_HEIGHT },
  title: { fontSize: 16, fontWeight: "600", color: "#0f172a" },
  separator: { height: 8 },
});

Quando usar isso:

Feeds com muitas imagens, linhas de chat ou catálogos de produtos com mais de 50 linhas.
O profiler mostra quedas de quadros durante a rolagem rápida em dispositivos Android de gama média.
O ajuste de windowSize no FlatList não corrigiu flashes em branco.

Exemplo de Trabalho

import { memo, useCallback } from "react";
import { FlashList } from "@shopify/flash-list";
import { Image, StyleSheet, Text, View } from "react-native";
 
interface Product {
  id: string;
  name: string;
  price: string;
  imageUrl: string;
}
 
const ESTIMATED_ROW_HEIGHT = 96;
 
const ProductRow = memo(function ProductRow({ item }: { item: Product }) {
  return (
    <View style={styles.row}>
      <Image source={{ uri: item.imageUrl }} style={styles.thumb} />
      <View style={styles.meta}>
        <Text style={styles.name} numberOfLines={1}>
          {item.name}
        </Text>
        <Text style={styles.price}>{item.price}</Text>
      </View>
    </View>
  );
});
 
export function ProductFeedScreen({ products }: { products: Product[] }) {
  const renderItem = useCallback(
    ({ item }: { item: Product }) => <ProductRow item={item} />,
    [],
  );
 
  return (
    <View style={styles.screen}>
      <FlashList
        data={products}
        estimatedItemSize={ESTIMATED_ROW_HEIGHT}
        keyExtractor={(item) => item.id}
        renderItem={renderItem}
        drawDistance={250}
        contentContainerStyle={styles.list}
      />
    </View>
  );
}
 
const styles = StyleSheet.create({
  screen: { flex: 1, backgroundColor: "#f8fafc" },
  list: { paddingVertical: 8 },
  row: {
    flexDirection: "row",
    alignItems: "center",
    gap: 12,
    paddingHorizontal: 16,
    paddingVertical: 10,
    backgroundColor: "#fff",
    minHeight: ESTIMATED_ROW_HEIGHT,
  },
  thumb: { width: 72, height: 72, borderRadius: 8, backgroundColor: "#e2e8f0" },
  meta: { flex: 1 },
  name: { fontSize: 16, fontWeight: "600", color: "#0f172a" },
  price: { fontSize: 14, color: "#2563eb", marginTop: 4 },
});

O que isso demonstra:

estimatedItemSize - obrigatório; definido para a altura típica da linha.
minHeight na linha - alinha o tamanho renderizado com a estimativa para rolagem estável.
memo na linha - visualizações recicladas não devem carregar estado de closure obsoleto.
drawDistance={250} - pré-renderiza à frente da viewport para reduzir flashes em branco.
renderItem estável - useCallback evita renderizações desnecessárias da lista.

Mergulho Profundo

Checklist de Migração

Copie este checklist por tela ao migrar de FlatList:

## Migração para FlashList: ProductFeedScreen
 
- [ ] npx expo install @shopify/flash-list
- [ ] Trocar importação: FlatList → FlashList de @shopify/flash-list
- [ ] Adicionar estimatedItemSize (medir altura média da linha nas DevTools ou especificação de design)
- [ ] Definir minHeight no contêiner da linha para corresponder à estimativa
- [ ] Envolver o componente de linha em memo()
- [ ] Estabilizar renderItem com useCallback
- [ ] Auditar alturas de linha variáveis - substituir overrideItemLayout se necessário
- [ ] Testar rolagem rápida em dispositivo Android físico
- [ ] Verificar ListHeaderComponent / ListFooterComponent / estado vazio
- [ ] Confirmar layout de grade numColumns, se aplicável
- [ ] Profiler antes/depois - React DevTools + sobreposição FPS

Migração Passo a Passo

// Antes
import { FlatList } from "react-native";
 
<FlatList
  data={posts}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <PostRow item={item} />}
/>
 
// Depois
import { FlashList } from "@shopify/flash-list";
 
const ROW_HEIGHT = 88;
 
<FlashList
  data={posts}
  estimatedItemSize={ROW_HEIGHT}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <PostRow item={item} />}
/>

Alturas de Linha Variáveis

<FlashList
  data={messages}
  estimatedItemSize={72}
  overrideItemLayout={(layout, item) => {
    layout.size = item.hasAttachment ? 160 : 72;
  }}
  renderItem={({ item }) => <MessageRow item={item} />}
/>

Use overrideItemLayout quando a altura da linha for previsível a partir dos dados - não por quebra de texto arbitrária.

TypeScript

import type { ListRenderItem } from "@shopify/flash-list";
 
const renderItem: ListRenderItem<Product> = ({ item }) => <ProductRow item={item} />;

Importe tipos de @shopify/flash-list, não de react-native.

Armadilhas

estimatedItemSize ausente - A lista renderiza em branco ou a rolagem salta descontroladamente. Correção: Sempre defina; ajuste contra linhas reais.
Estado da linha em useState dentro de renderItem - Visualizações recicladas mostram seleção obsoleta. Correção: Linhas apenas com props; eleve a seleção para o pai extraData.
renderItem instável em linha - Nova função a cada renderização pai anula o memo. Correção: useCallback com dependências estáveis.
Assumindo paridade total da API FlatList - Algumas props de ponta diferem. Correção: Teste numColumns, rolagem aninhada e cabeçalhos no dispositivo.
Migrando listas de configurações de 8 linhas - Custo de ajuste de estimativa sem ganho. Correção: Mantenha FlatList até que o profiling prove a necessidade.

Alternativas

Alternativa	Use Quando	Não Use Quando
FlashList	Longos feeds, linhas de imagem, chat	Listas estáticas curtas
FlatList	Configurações, < 20 linhas simples	Lentidão na rolagem rápida no Android
SectionList	Cabeçalhos agrupados necessários	Feed homogêneo único
VirtualizedList diretamente	Virtualização personalizada	Feed vertical padrão

FAQs

Como instalo o FlashList no Expo SDK 57?

npx expo install @shopify/flash-list

Fixa uma versão compatível para o seu SDK. Reconstrua o cliente de desenvolvimento se o autolinking mudar.

Qual deve ser o estimatedItemSize?

Meça 5–10 linhas representativas - use a altura mediana. Inclua padding e separadores. Estimativas incorretas causam saltos na rolagem, não travamentos.

O FlashList funciona com useInfiniteQuery?

Sim - onEndReached / onEndReachedThreshold igual ao FlatList. Veja Scroll Infinito & Paginação.

Onde está o guia de comparação completo?

FlashList vs FlatList - trade-offs antes de migrar

Devo usar memo em todas as linhas?

Sim para listas recicladas - combine memo na linha, renderItem estável e estado apenas de props.

Relacionados

FlashList vs FlatList - trade-offs antes de migrar
Ajuste de Desempenho de Lista - conceitos de memo e windowSize
Scroll Infinito & Paginação - paginação após a migração
Armadilhas de Virtualização - linhas em branco e armadilhas de reciclagem
Noções Básicas de Bibliotecas Essenciais - quando adotar dependências de lista nativas

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

npx expo install @shopify/flash-list

import { FlashList } from "@shopify/flash-list";
import { StyleSheet, Text, View } from "react-native";
 
interface Post {
  id: string;
  title: string;
}
 
const ESTIMATED_ROW_HEIGHT = 88;
 
export function PostFeed({ posts }: { posts: Post[] }) {
  return (
    <FlashList
      data={posts}
      estimatedItemSize={ESTIMATED_ROW_HEIGHT}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View style={styles.row}>
          <Text style={styles.title} numberOfLines={2}>
            {item.title}
          </Text>
        </View>
      )}
      ItemSeparatorComponent={() => <View style={styles.separator} />}
    />
  );
}
 
const styles = StyleSheet.create({
  row: { paddingHorizontal: 16, paddingVertical: 12, backgroundColor: "#fff", minHeight: ESTIMATED_ROW_HEIGHT },
  title: { fontSize: 16, fontWeight: "600", color: "#0f172a" },
  separator: { height: 8 },
});

Quando usar isso:

Feeds com muitas imagens, linhas de chat ou catálogos de produtos com mais de 50 linhas.
O profiler mostra quedas de quadros durante a rolagem rápida em dispositivos Android de gama média.
O ajuste de windowSize no FlatList não corrigiu flashes em branco.

Exemplo de Trabalho

import { memo, useCallback } from "react";
import { FlashList } from "@shopify/flash-list";
import { Image, StyleSheet, Text, View } from "react-native";
 
interface Product {
  id: string;
  name: string;
  price: string;
  imageUrl: string;
}
 
const ESTIMATED_ROW_HEIGHT = 96;
 
const ProductRow = memo(function ProductRow({ item }: { item: Product }) {
  return (
    <View style={styles.row}>
      <Image source={{ uri: item.imageUrl }} style={styles.thumb} />
      <View style={styles.meta}>
        <Text style={styles.name} numberOfLines={1}>
          {item.name}
        </Text>
        <Text style={styles.price}>{item.price}</Text>
      </View>
    </View>
  );
});
 
export function ProductFeedScreen({ products }: { products: Product[] }) {
  const renderItem = useCallback(
    ({ item }: { item: Product }) => <ProductRow item={item} />,
    [],
  );
 
  return (
    <View style={styles.screen}>
      <FlashList
        data={products}
        estimatedItemSize={ESTIMATED_ROW_HEIGHT}
        keyExtractor={(item) => item.id}
        renderItem={renderItem}
        drawDistance={250}
        contentContainerStyle={styles.list}
      />
    </View>
  );
}
 
const styles = StyleSheet.create({
  screen: { flex: 1, backgroundColor: "#f8fafc" },
  list: { paddingVertical: 8 },
  row: {
    flexDirection: "row",
    alignItems: "center",
    gap: 12,
    paddingHorizontal: 16,
    paddingVertical: 10,
    backgroundColor: "#fff",
    minHeight: ESTIMATED_ROW_HEIGHT,
  },
  thumb: { width: 72, height: 72, borderRadius: 8, backgroundColor: "#e2e8f0" },
  meta: { flex: 1 },
  name: { fontSize: 16, fontWeight: "600", color: "#0f172a" },
  price: { fontSize: 14, color: "#2563eb", marginTop: 4 },
});

O que isso demonstra:

estimatedItemSize - obrigatório; definido para a altura típica da linha.
minHeight na linha - alinha o tamanho renderizado com a estimativa para rolagem estável.
memo na linha - visualizações recicladas não devem carregar estado de closure obsoleto.
drawDistance={250} - pré-renderiza à frente da viewport para reduzir flashes em branco.
renderItem estável - useCallback evita renderizações desnecessárias da lista.

Mergulho Profundo

Checklist de Migração

Copie este checklist por tela ao migrar de FlatList:

## Migração para FlashList: ProductFeedScreen
 
- [ ] npx expo install @shopify/flash-list
- [ ] Trocar importação: FlatList → FlashList de @shopify/flash-list
- [ ] Adicionar estimatedItemSize (medir altura média da linha nas DevTools ou especificação de design)
- [ ] Definir minHeight no contêiner da linha para corresponder à estimativa
- [ ] Envolver o componente de linha em memo()
- [ ] Estabilizar renderItem com useCallback
- [ ] Auditar alturas de linha variáveis - substituir overrideItemLayout se necessário
- [ ] Testar rolagem rápida em dispositivo Android físico
- [ ] Verificar ListHeaderComponent / ListFooterComponent / estado vazio
- [ ] Confirmar layout de grade numColumns, se aplicável
- [ ] Profiler antes/depois - React DevTools + sobreposição FPS

Migração Passo a Passo

// Antes
import { FlatList } from "react-native";
 
<FlatList
  data={posts}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <PostRow item={item} />}
/>
 
// Depois
import { FlashList } from "@shopify/flash-list";
 
const ROW_HEIGHT = 88;
 
<FlashList
  data={posts}
  estimatedItemSize={ROW_HEIGHT}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <PostRow item={item} />}
/>

Alturas de Linha Variáveis

<FlashList
  data={messages}
  estimatedItemSize={72}
  overrideItemLayout={(layout, item) => {
    layout.size = item.hasAttachment ? 160 : 72;
  }}
  renderItem={({ item }) => <MessageRow item={item} />}
/>

Use overrideItemLayout quando a altura da linha for previsível a partir dos dados - não por quebra de texto arbitrária.

TypeScript

import type { ListRenderItem } from "@shopify/flash-list";
 
const renderItem: ListRenderItem<Product> = ({ item }) => <ProductRow item={item} />;

Importe tipos de @shopify/flash-list, não de react-native.

Armadilhas

estimatedItemSize ausente - A lista renderiza em branco ou a rolagem salta descontroladamente. Correção: Sempre defina; ajuste contra linhas reais.
Estado da linha em useState dentro de renderItem - Visualizações recicladas mostram seleção obsoleta. Correção: Linhas apenas com props; eleve a seleção para o pai extraData.
renderItem instável em linha - Nova função a cada renderização pai anula o memo. Correção: useCallback com dependências estáveis.
Assumindo paridade total da API FlatList - Algumas props de ponta diferem. Correção: Teste numColumns, rolagem aninhada e cabeçalhos no dispositivo.
Migrando listas de configurações de 8 linhas - Custo de ajuste de estimativa sem ganho. Correção: Mantenha FlatList até que o profiling prove a necessidade.

Alternativas

Alternativa	Use Quando	Não Use Quando
FlashList	Longos feeds, linhas de imagem, chat	Listas estáticas curtas
FlatList	Configurações, < 20 linhas simples	Lentidão na rolagem rápida no Android
SectionList	Cabeçalhos agrupados necessários	Feed homogêneo único
VirtualizedList diretamente	Virtualização personalizada	Feed vertical padrão

FAQs

Como instalo o FlashList no Expo SDK 57?

npx expo install @shopify/flash-list

Fixa uma versão compatível para o seu SDK. Reconstrua o cliente de desenvolvimento se o autolinking mudar.

Qual deve ser o estimatedItemSize?

Meça 5–10 linhas representativas - use a altura mediana. Inclua padding e separadores. Estimativas incorretas causam saltos na rolagem, não travamentos.

O FlashList funciona com useInfiniteQuery?

Sim - onEndReached / onEndReachedThreshold igual ao FlatList. Veja Scroll Infinito & Paginação.

Onde está o guia de comparação completo?

FlashList vs FlatList - trade-offs antes de migrar

Devo usar memo em todas as linhas?

Sim para listas recicladas - combine memo na linha, renderItem estável e estado apenas de props.

Relacionados

FlashList vs FlatList - trade-offs antes de migrar
Ajuste de Desempenho de Lista - conceitos de memo e windowSize
Scroll Infinito & Paginação - paginação após a migração
Armadilhas de Virtualização - linhas em branco e armadilhas de reciclagem
Noções Básicas de Bibliotecas Essenciais - quando adotar dependências de lista nativas

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

@shopify/flash-list

Buscar na documentação

@shopify/flash-list