Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 38 ยท Components and Styling

Lists, FlatList and SectionList

Render long lists efficiently in Expo: FlatList props, keyExtractor, getItemLayout, pull to refresh, infinite scroll, SectionList, empty states and when to use FlashList.

Lists are in almost every app: feeds, contacts, search results, messages. Rendering a thousand rows with ScrollView and .map() mounts a thousand views at once, which is slow and memory hungry. Virtualized lists render only what is on screen (plus a buffer) and recycle the rest. React Native's FlatList and SectionList do exactly that.

Components are read-only (they need a device). The live stand-ins model the window calculation and data handling so you can see why virtualization helps.

FlatList basics

TSX
import { FlatList, Text, View } from 'react-native';

type Trail = { id: string; name: string; km: number };

export function TrailList({ trails }: { trails: Trail[] }) {
  return (
    <FlatList
      data={trails}
      keyExtractor={(t) => t.id}
      renderItem={({ item }) => (
        <View style={{ padding: 16 }}>
          <Text style={{ fontWeight: '700' }}>{item.name}</Text>
          <Text>{item.km} km</Text>
        </View>
      )}
      ItemSeparatorComponent={() => <View style={{ height: 1, backgroundColor: '#ddd' }} />}
      ListHeaderComponent={<Text style={{ padding: 16 }}>All trails</Text>}
      ListEmptyComponent={<Text style={{ padding: 16 }}>No trails yet.</Text>}
      ListFooterComponent={<View style={{ height: 32 }} />}
    />
  );
}

The essentials:

  • data: an array. renderItem: called per visible item with { item, index }.
  • keyExtractor: returns a unique, stable string per item. Without it FlatList falls back to the index (or item.key), which breaks reordering and state. Never use a random value.
  • Header, footer, separator and empty components cover the usual UI.
  • numColumns={2} makes a grid (children get equal width; do not change it on the fly without changing key).
  • horizontal makes a carousel.
  • contentContainerStyle (padding, gaps) and style (the scroll area) work as for ScrollView.

Why virtualization

ScrollView + map Mounts every row
FlatList Mounts a window of rows
Recycling Reuses off-screen rows

Fewer views means less memory and faster scrolling.

1 / 2

The window, modeled

Roughly, FlatList renders the rows that intersect the viewport plus a buffer measured in viewport heights (windowSize, default 21: ten screens above and below). This stand-in computes which indexes get rendered for fixed-height rows.

JS Which rows are rendered?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Performance props

  • getItemLayout: if rows have fixed height, getItemLayout={(_, i) => ({ length: 80, offset: 80 * i, index: i })} lets the list skip measuring and makes scrollToIndex instant.
  • initialNumToRender: rows in the first batch (enough to fill the screen).
  • windowSize, maxToRenderPerBatch, updateCellsBatchingPeriod: tune rendering vs blank areas while scrolling quickly.
  • removeClippedSubviews: detaches off-screen native views (can help on Android; test it).
  • Memoize rows: extract a row component and wrap it with React.memo, and pass stable callbacks (useCallback), so only changed rows re-render. Pass extraData when renderItem depends on state outside data (like a selected id), or the list will not update.
TSX
const Row = React.memo(function Row({ trail, selected, onPress }: RowProps) {
  return (
    <Pressable onPress={() => onPress(trail.id)} style={selected && styles.selected}>
      <Text>{trail.name}</Text>
    </Pressable>
  );
});

<FlatList
  data={trails}
  extraData={selectedId}
  keyExtractor={(t) => t.id}
  renderItem={({ item }) => <Row trail={item} selected={item.id === selectedId} onPress={select} />}
/>

For very large or complex lists, FlashList (@shopify/flash-list) recycles cells like native lists do and is usually much faster; its API is close to FlatList, with estimatedItemSize hints and getItemType for lists with several row types. Install it with npx expo install @shopify/flash-list.

Pull to refresh and infinite scroll

TSX
const [refreshing, setRefreshing] = useState(false);

<FlatList
  data={items}
  refreshing={refreshing}
  onRefresh={async () => { setRefreshing(true); await reload(); setRefreshing(false); }}
  onEndReached={loadNextPage}
  onEndReachedThreshold={0.5}      // call when within half a screen of the end
  ListFooterComponent={loadingMore ? <ActivityIndicator /> : null}
/>

onEndReached may fire several times; guard with a loading flag and a hasMore flag.

JS Pagination state, guarded

Press Run (or Ctrl + Enter) to see the console output here.

No output.

SectionList

SectionList groups rows under headers (contacts by letter, trails by region):

TSX
<SectionList
  sections={[
    { title: 'Alps', data: ['Eagle Pass', 'Lake Loop'] },
    { title: 'Coast', data: ['Cliff Walk'] },
  ]}
  keyExtractor={(item) => item}
  renderItem={({ item }) => <Text style={{ padding: 12 }}>{item}</Text>}
  renderSectionHeader={({ section }) => (
    <Text style={{ padding: 8, backgroundColor: '#eee', fontWeight: '700' }}>{section.title}</Text>
  )}
  stickySectionHeadersEnabled
/>
JS Group items into sections

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • A list inside a ScrollView of the same direction: it disables virtualization and warns. Use ListHeaderComponent instead.
  • Duplicate or missing keys, causing wrong rows or lost state.
  • Inline heavy renderItem functions that re-create every row on every render.
  • Changing numColumns without changing key.
  • A FlatList without bounded height (inside a view without flex: 1), so it renders everything.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is FlatList better than ScrollView with map() for 5,000 items?

    Virtualization mounts only the rows near the viewport and recycles the rest.
  2. 2. What must keyExtractor return?

    Stable unique keys let the list track rows when data changes.
  3. 3. Your rows depend on a selectedId state that is not inside data. What prop makes the list re-render?

    FlatList is a PureComponent; extraData tells it that outside values changed.
  4. 4. What does onEndReachedThreshold={0.5} mean?

    The threshold is expressed in visible lengths of the list.

Summary

  • Use FlatList (or FlashList) for long lists, SectionList for grouped data.
  • Give every item a stable key, memoize rows and pass extraData for outside state.
  • Use getItemLayout for fixed rows, pull-to-refresh via onRefresh, paging via onEndReached with guards.
  • Never nest a same-direction list inside a ScrollView.

Next: Touch and Text Input