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.