FlatList and List Patterns

FlatList and List Patterns

Build performant scrollable lists with FlatList, SectionList, and FlashList for large data sets

When to Use

• Rendering lists of items that may exceed screen height
• Implementing infinite scroll with pagination
• Building section-grouped lists (contacts, settings)
• Optimizing list rendering performance for hundreds or thousands of items
• Adding pull-to-refresh, swipe actions, or sticky headers

Instructions

1. Use FlatList for simple lists, SectionList for grouped data, and FlashList for maximum performance.

import { FlatList } from 'react-native';

function OrderList({ orders }: { orders: Order[] }) {
  return (
    <FlatList
      data={orders}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => <OrderCard order={item} />}
    />
  );
}

2. Always provide keyExtractor. Use a stable unique ID from your data. Never use array index as the key — it breaks reordering and causes incorrect recycling.

3. Memoize renderItem components to prevent unnecessary re-renders during scrolling.

const OrderCard = memo(function OrderCard({ order }: { order: Order }) {
  return (
    <View style={styles.card}>
      <Text>{order.title}</Text>
      <Text>{order.status}</Text>
    </View>
  );
});

// Stable renderItem reference
const renderItem = useCallback(({ item }: { item: Order }) => <OrderCard order={item} />, []);

4. Set getItemLayout when item heights are fixed. This eliminates measurement overhead and enables instant scroll-to-index.

<FlatList
  data={items}
  getItemLayout={(data, index) => ({
    length: ITEM_HEIGHT,
    offset: ITEM_HEIGHT * index,
    index,
  })}
/>

5. Implement infinite scroll with onEndReached.

function InfiniteList() {
  const [data, setData] = useState<Item[]>([]);
  const [page, setPage] = useState(1);
  const [loading, setLoading] = useState(false);

  const loadMore = useCallback(async () => {
    if (loading) return;
    setLoading(true);
    const newItems = await fetchItems(page + 1);
    setData((prev) => [...prev, ...newItems]);
    setPage((p) => p + 1);
    setLoading(false);
  }, [page, loading]);

  return (
    <FlatList
      data={data}
      renderItem={renderItem}
      keyExtractor={(item) => item.id}
      onEndReached={loadMore}
      onEndReachedThreshold={0.5}
      ListFooterComponent={loading ? <ActivityIndicator /> : null}
    />
  );
}

6. Add pull-to-refresh with refreshing and onRefresh.

<FlatList
  data={data}
  renderItem={renderItem}
  refreshing={isRefreshing}
  onRefresh={async () => {
    setIsRefreshing(true);
    const fresh = await fetchItems(1);
    setData(fresh);
    setIsRefreshing(false);
  }}
/>

7. Use SectionList for grouped data with headers.

import { SectionList } from 'react-native';

const sections = [
  { title: 'Today', data: todayItems },
  { title: 'Yesterday', data: yesterdayItems },
];

<SectionList
  sections={sections}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <ItemRow item={item} />}
  renderSectionHeader={({ section }) => <Text style={styles.header}>{section.title}</Text>}
  stickySectionHeadersEnabled
/>;

8. Use FlashList for better performance with large lists. FlashList by Shopify uses cell recycling instead of unmounting, providing significantly better scroll performance.

npm install @shopify/flash-list

import { FlashList } from '@shopify/flash-list';

<FlashList
  data={items}
  renderItem={({ item }) => <ItemRow item={item} />}
  estimatedItemSize={80} // Required — approximate height in pixels
  keyExtractor={(item) => item.id}
/>;

9. Handle empty states with ListEmptyComponent.

<FlatList
  data={data}
  renderItem={renderItem}
  ListEmptyComponent={<EmptyState message="No orders yet" />}
  ListHeaderComponent={<SearchBar />}
/>

Details

FlatList vs. FlashList: FlatList unmounts items as they scroll off-screen and mounts new ones. FlashList recycles views, updating existing components with new data. FlashList is typically 5-10x faster for large lists. Use FlashList when lists exceed ~100 items or when smooth 60fps scrolling is critical.

Performance tuning props:

• removeClippedSubviews={true} — detach offscreen views from the native hierarchy
• maxToRenderPerBatch={10} — items rendered per batch (lower = more responsive, slower fill)
• windowSize={5} — number of viewport-heights to render around visible area (lower = less memory, more blank space during fast scrolling)
• updateCellsBatchingPeriod={50} — milliseconds between batch renders

Common mistakes:

• Inline arrow functions in renderItem (causes re-render every cycle)
• Missing keyExtractor (defaults to index, breaks recycling)
• Not memoizing list items (every parent re-render re-renders every visible item)
• Using ScrollView for dynamic lists (renders all items at once, no virtualization)
• Setting onEndReachedThreshold too low (triggers only at the very bottom, feels laggy)

Source

https://reactnative.dev/docs/flatlist

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.