Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 71 ยท Lists

FlatList Essentials

Learn FlatList in React Native: data and renderItem, keyExtractor, separators, header, footer, empty state, numColumns and extraData, with live stand-ins.

Almost every app has a list: messages, products, settings, search results. In Core Components you saw that ScrollView mounts every child at once, which is fine for ten rows and painful for ten thousand. FlatList is React Native's answer. You hand it an array and a function that draws one row, and it draws only the rows near the screen, reusing memory as the user scrolls.

This lesson covers the props you need for 90 percent of lists: data, renderItem, keyExtractor, separators, header, footer, an empty state, grid columns and extraData. Performance tuning has its own lesson, Fast Lists. The web version of the same idea is in lists and keys.

Read-only and stand-in. The real FlatList needs a native scroll view, so it appears in plain code blocks. The TryIts use a small stand-in component that accepts the same props and renders all rows to HTML. It shows the structure (header, separators, footer, empty state, columns); it does not virtualize.

The minimum list

A FlatList needs two props: data (an array) and renderItem (a function).

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

type Fruit = { id: string; name: string };

const fruits: Fruit[] = [
  { id: '1', name: 'Apple' },
  { id: '2', name: 'Banana' },
  { id: '3', name: 'Cherry' },
];

export function FruitList() {
  return (
    <FlatList
      data={fruits}
      renderItem={({ item }) => (
        <View style={{ padding: 16 }}>
          <Text>{item.name}</Text>
        </View>
      )}
    />
  );
}

renderItem receives an object with the item, its index and a separators helper. Destructure what you need. The function returns the element for one row.

FlatList scrolls by itself, so do not put it inside a vertical ScrollView: you lose virtualization and React Native warns you. If the list is only one part of a screen, make the other parts the header or footer of the list (see below).

keyExtractor: stable identity

React needs a key for each row to know which row is which when data changes. FlatList looks for item.key, then item.id, and falls back to the index (with a warning in development). If your data has neither, or uses another field, provide a keyExtractor:

TSX
<FlatList
  data={users}
  keyExtractor={(user) => user.email}
  renderItem={({ item }) => <UserRow user={item} />}
/>

The key must be a string and unique and stable for that item. Never use the index when rows can be reordered, inserted or deleted, because the row at index 2 is a different item after the change and its state (a checkbox, a text input) will jump to the wrong row.

Instead of writing borders into every row, FlatList has slots for the parts around the rows:

TSX
<FlatList
  data={messages}
  renderItem={renderMessage}
  keyExtractor={(m) => m.id}
  ItemSeparatorComponent={() => <View style={{ height: 1, backgroundColor: '#e2e8f0' }} />}
  ListHeaderComponent={<SearchBar />}
  ListFooterComponent={<Text style={{ padding: 16 }}>End of list</Text>}
  ListEmptyComponent={<Text style={{ padding: 16 }}>No messages yet</Text>}
  contentContainerStyle={{ paddingBottom: 24 }}
/>
  • ItemSeparatorComponent is drawn between rows, never above the first or below the last.
  • ListHeaderComponent and ListFooterComponent scroll with the content. A footer is a good place for a loading spinner.
  • ListEmptyComponent appears only when data is empty. It is where "No results" or an illustration goes.
  • contentContainerStyle styles the inner content, like on ScrollView; use it for padding and flexGrow: 1 so an empty state can be centered.

Two props make a list

data An array of items.
renderItem Draws one row.
1 / 2

Stand-in: a FlatList that renders to HTML

The FlatList below is a stand-in. It accepts the same prop names, picks keys the same way (explicit extractor, then key, then id), puts the separator only between rows, and shows the empty component when there is no data. Click the button to empty the data.

FlatList slots: header, separator, footer, empty

Clear the list: the separators disappear with the rows, the empty message replaces them, and header and footer stay. That is exactly how the real component behaves.

Grids with numColumns

Set numColumns to show several items per row. Items are laid out row by row, and the last row may have fewer items:

TSX
<FlatList
  data={photos}
  keyExtractor={(p) => p.id}
  numColumns={3}
  columnWrapperStyle={{ gap: 8 }}
  contentContainerStyle={{ gap: 8, padding: 8 }}
  renderItem={({ item }) => <Photo photo={item} style={{ flex: 1, aspectRatio: 1 }} />}
/>

Use flex: 1 on each cell so cells share the width evenly. Two rules to remember: numColumns cannot be changed on the fly (give the list a different key when you switch, for example between portrait and landscape), and it cannot be combined with horizontal.

Starting position, header styles and scroll methods

Beyond the props above, a few more control where the list starts and what you can do with it from code:

  • initialScrollIndex opens the list at a given row without scrolling through the earlier ones. It needs getItemLayout (see List Performance), because the list must know where row n lies without rendering the rows before it.
  • ListHeaderComponentStyle and ListFooterComponentStyle style the wrapper around the header and footer, for example to add padding that does not apply to rows.
  • inverted flips the list for a chat; horizontal makes it scroll sideways.
  • Through a ref: scrollToIndex({ index, animated, viewPosition }), scrollToOffset, scrollToEnd, scrollToItem, flashScrollIndicators() (iOS), getScrollResponder(), getScrollableNode() and getNativeScrollRef() for the lower-level scroll view.

FlatList accepts all the ScrollView props, such as snapToInterval, pagingEnabled and onScroll, since it renders one.

Viewability: which rows are on screen?

onViewableItemsChanged tells you which rows are visible, which is how you pause a video that scrolled away or log which products were seen.

JSX
const viewabilityConfig = {
  itemVisiblePercentThreshold: 60,   // a row counts as viewable at 60% visible
  minimumViewTime: 300,              // ...if it stays that long
};

const onViewableItemsChanged = useRef(({ viewableItems, changed }) => {
  setVisibleIds(viewableItems.map((v) => v.item.id));
}).current;

<FlatList
  data={items}
  renderItem={renderItem}
  viewabilityConfig={viewabilityConfig}
  onViewableItemsChanged={onViewableItemsChanged}
/>

Two rules trip people up. viewabilityConfig and onViewableItemsChanged must not change between renders, so keep the config outside the component or in a useRef/useCallback; changing them throws an error. And when you need different callbacks for different rules, use viewabilityConfigCallbackPairs, an array of { viewabilityConfig, onViewableItemsChanged } objects. Each viewableItems entry has item, key, index and isViewable.

The old ListView

Very old tutorials use ListView with dataSource, renderRow, initialListSize, pageSize and renderSeparator. That component was removed from React Native years ago because it was slow and hard to use. Replace it with FlatList: dataSource becomes data, renderRow becomes renderItem, renderSeparator becomes ItemSeparatorComponent, renderFooter becomes ListFooterComponent, initialListSize becomes initialNumToRender and onChangeVisibleRows becomes onViewableItemsChanged.

extraData and re-rendering

FlatList is a pure component: it re-renders rows only when its props change. If your rows depend on something outside data, for example a selectedId held in state, the list does not know. Pass that value as extraData:

TSX
const [selectedId, setSelectedId] = useState<string | null>(null);

<FlatList
  data={items}
  extraData={selectedId}
  keyExtractor={(i) => i.id}
  renderItem={({ item }) => (
    <Row item={item} selected={item.id === selectedId} onPress={() => setSelectedId(item.id)} />
  )}
/>

Also avoid mutating the array in place (items.push(x)): React sees the same array and skips the update. Always create a new array, as in objects and arrays in state.

Other props you will meet often: horizontal for a sideways list, initialNumToRender (how many rows to draw first, default 10), onEndReached for loading more (covered in SectionList, Pull to Refresh and Infinite Scroll) and inverted for chat screens that start at the bottom.

Stand-in: a grid and key extraction

This second stand-in shows how numColumns splits data into rows, and how the key is chosen. The key list at the bottom is what React would use to track rows.

numColumns chunks and key extraction

With three columns, seven tiles become three rows (3, 3, 1). The empty spacers keep the last tile the same width as the others, which is what flex: 1 on real cells achieves.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which two props does a FlatList minimally need?

    data is the array; renderItem draws one row. Everything else is optional.
  2. 2. Where is ItemSeparatorComponent drawn?

    Separators sit between neighboring rows, so there is none above the first or below the last.
  3. 3. Rows depend on a selectedId stored in state, but they do not update when it changes. What fixes it?

    FlatList only re-renders when its props change. extraData tells it that something outside data matters to the rows.
  4. 4. Why is using the array index as a key a bad idea for a list that can be reordered?

    After a reorder, index 2 holds a different item, so React reuses the old row state for the wrong data.
  5. 5. How should you switch numColumns between portrait and landscape?

    numColumns cannot change on the fly. A different key forces a fresh list.

Summary

  • FlatList takes data and renderItem and draws only what is near the screen.
  • Keys must be unique, stable strings: use id/key or a keyExtractor, not the index of a changing list.
  • ItemSeparatorComponent, ListHeaderComponent, ListFooterComponent and ListEmptyComponent replace hand-written borders and conditionals.
  • numColumns makes a grid (change the list key to change it); never nest a vertical FlatList inside a vertical ScrollView.
  • Use extraData when rows depend on state outside data, and always create new arrays instead of mutating.

Next, keep long lists smooth in Fast Lists: Virtualization and Tuning.