FlashList vs FlatList

Trade-offs, recycling, and migration checklist for Shopify FlashList - when the default list isn't fast enough.

Receita

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

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" },
  title: { fontSize: 16, fontWeight: "600", color: "#0f172a" },
  separator: { height: 8 },
});

Quando usar isso: Feeds com muitas imagens, timelines de chat ou qualquer lista onde a análise de desempenho mostra quedas de quadros durante a rolagem rápida em dispositivos Android de gama média.

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 PRODUCTS: Product[] = Array.from({ length: 200 }, (_, i) => ({
  id: `p-${i}`,
  name: `Product ${i + 1}`,
  price: `$${(9.99 + (i % 50)).toFixed(2)}`,
  imageUrl: `https://picsum.photos/seed/${i}/120/120`,
}));
 
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 default function ProductFeedScreen() {
  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 definido para a altura típica da linha - necessário para a matemática de layout do FlashList.
• minHeight na linha alinha o tamanho renderizado com a estimativa para rolagem estável.
• memo em ProductRow emparelha com a reciclagem de views - as linhas devem tolerar reutilização sem estado obsoleto.
• drawDistance={250} pré-renderiza um pouco além da viewport para reduzir flashes em branco durante a rolagem rápida.
• Mesmos padrões keyExtractor / renderItem do FlatList - a migração é principalmente adição de props.

Análise Profunda

Como Funciona

• FlatList virtualiza montando/desmontando subárvores de linhas à medida que entram e saem da janela de renderização. A rolagem rápida ainda pode alocar muitas views por segundo.
• FlashList mantém um pool reciclado de contêineres de linha - novos dados são vinculados a views nativas existentes em vez de criar árvores novas a cada vez.
• FlashList precisa de estimatedItemSize porque ele dimensiona o conteúdo antes que todas as linhas sejam medidas - a estimativa impulsiona os cálculos de deslocamento até que a medição real chegue.
• Estimativas incorretas causam salto de rolagem (o conteúdo muda quando a altura real difere) ou breves espaços em branco durante a rolagem rápida.
• FlashList suporta o mesmo modelo mental: data, renderItem, keyExtractor, separadores, cabeçalhos, onEndReached.
• Por baixo dos panos, FlashList ainda roda na infraestrutura de rolagem do React Native - não é uma implementação de lista nativa separada.

FlatList vs FlashList

Checklist de Migração

1. Instalar: npx expo install @shopify/flash-list
2. Trocar importação: FlatList → FlashList de @shopify/flash-list
3. Adicionar estimatedItemSize: Meça uma linha típica nas DevTools ou especificações de design (inclua padding).
4. Auditar componentes de linha: Remova o estado local que sobrevive à reciclagem; derive a UI apenas das props item.
5. Combinar alturas mínimas: Defina minHeight ou altura fixa próxima à estimativa quando possível.
6. Alturas variáveis: Use overrideItemLayout por tipo de item ou listas separadas por variante de layout.
7. Testar rolagem rápida: Role rapidamente em um dispositivo Android de baixo custo; observe espaços em branco e saltos.
8. Re-testar onEndReached: O comportamento do limite é semelhante, mas verifique as proteções de paginação.
9. Listas de seção: Use FlashList com cabeçalhos fixos ou mantenha SectionList até precisar do ganho de desempenho.
10. Analisar antes/depois: Monitor de desempenho do React Native DevTools ou console.time em torno de sessões de rolagem.

// Antes
import { FlatList } from "react-native";
<FlatList data={items} renderItem={...} keyExtractor={...} />
 
// Depois
import { FlashList } from "@shopify/flash-list";
<FlashList
  data={items}
  estimatedItemSize={72}
  renderItem={...}
  keyExtractor={...}
/>

Props de Ajuste Fino

<FlashList
  data={items}
  estimatedItemSize={120}
  getItemType={(item) => (item.pinned ? "pinned" : "normal")}
  overrideItemLayout={(layout, item) => {
    layout.size = item.pinned ? 160 : 96;
  }}
  renderItem={renderItem}
/>

Gotchas de Reciclagem

• Linhas recicladas reutilizam a mesma instância de componente - useState dentro de uma linha pode mostrar o estado do item anterior por um frame.
• Efeitos colaterais em useEffect sem dependências adequadas disparam no item errado.
• Correção: Mantenha o estado da linha nos dados item ou em mapas pai (expandedIds); as linhas devem ser funções puras das props.

Notas de TypeScript

import type { FlashListProps, ListRenderItem } from "@shopify/flash-list";
 
interface Article {
  id: string;
  headline: string;
}
 
type ArticleListProps = Pick<
  FlashListProps<Article>,
  "data" | "onEndReached" | "refreshing" | "onRefresh"
> & {
  onPress: (article: Article) => void;
};
 
function ArticleList({ data, onPress, ...rest }: ArticleListProps) {
  const renderItem: ListRenderItem<Article> = useCallback(
    ({ item }) => <ArticleRow article={item} onPress={() => onPress(item)} />,
    [onPress],
  );
 
  return (
    <FlashList
      data={data}
      estimatedItemSize={104}
      keyExtractor={(item) => item.id}
      renderItem={renderItem}
      {...rest}
    />
  );
}

• Importe tipos de @shopify/flash-list, não de react-native.
• FlashListProps<T> espelha FlatListProps<T> para a maioria das props de lista.

Parâmetros e Valores de Retorno

Gotchas

• Falta de estimatedItemSize - FlashList avisa e recorre a suposições de layout ruins; a rolagem parece quebrada. Correção: Sempre defina-o; meça linhas reais no simulador.

• Estimativa longe da realidade - Uma estimativa de 200px em linhas de 80px causa um salto quando a medição corrige. Correção: Meça a altura da linha p50; use overrideItemLayout para valores discrepantes.

• Componentes de linha com estado - useState para "curtido" dentro da linha mostra o estado do item anterior após a reciclagem. Correção: Armazene o estado de interação no pai/item ou em mapas extraData.

• Migrar sem memo - A reciclagem amplifica re-renderizações desnecessárias dentro das linhas. Correção: Use memo nos componentes de linha; renderItem estável com useCallback.

• Usar FlashList para 10 linhas de configurações - Dependência extra e ajuste fino sem ganho mensurável. Correção: Mantenha FlatList ou ScrollView até que a análise de desempenho prove a necessidade.

• Ignorar dimensões de imagem - Imagens carregando de forma assíncrona mudam a altura da linha após o primeiro layout, causando um salto em ambos os tipos de lista; pior quando a estimativa está errada. Correção: width/height fixos na Image, fundo de placeholder ou proporção conhecida.

• Assumir 100% de paridade de API - Algumas props de borda diferem; teste ListHeaderComponent, numColumns e rolagem aninhada. Correção: Leia a documentação do @shopify/flash-list para sua versão; execute o checklist de migração no dispositivo.

Alternativas

FAQs

Relacionados

• Receitas FlatList - props base antes de migrar para FlashList
• Otimização de Desempenho de Lista - memo, manipuladores estáveis e conceitos de windowSize que se aplicam a ambas as listas
• Gotchas de Virtualização - linhas em branco, clipping e armadilhas de reciclagem
• Scroll Infinito e Paginação - props de paginação após a migração
• @shopify/flash-list - instalação e configuração específica da biblioteca
• Estudo de Caso de Desempenho: Feed em Escala - FlashList em tempo real + ajuste de imagem

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).