FlatList

A performant interface for rendering basic, flat lists, supporting the most handy features:

• Fully cross-platform.
• Optional horizontal mode.
• Configurable viewability callbacks.
• Header support.
• Footer support.
• Separator support.
• Pull to Refresh.
• Scroll loading.
• ScrollToIndex support.
• Multiple column support.

If you need section support, use <SectionList>.

Example

TypeScript

JavaScript

To render multiple columns, use the numColumns prop. Using this approach instead of a flexWrap layout can prevent conflicts with the item height logic.

More complex, selectable example below.

• Passing extraData={selectedId} to FlatList ensures that FlatList re-renders when selectedId changes. Because FlatList implements PureComponent, it only re-renders if its props change. While renderItem in this example is recreated on each render because it is defined inline, passing extraData is essential whenever renderItem has a stable reference (such as when memoized or defined outside the component) so that FlatList knows that an external dependency has updated.
• keyExtractor tells the list to use the ids for the react keys instead of the default key property.

TypeScript

JavaScript

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView>) that aren't explicitly listed here, along with the following caveats:

• Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
• This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
• In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
• By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

---

Reference

Props

VirtualizedList Props

Inherits VirtualizedList Props.

---

Required

renderItem

React TSX

renderItem({
  item: ItemT,
  index: number,
  separators: {
    highlight: () => void;
    unhighlight: () => void;
    updateProps: (select: 'leading' | 'trailing', newProps: any) => void;
  }
}): JSX.Element;

Takes an item from data and renders it into the list.

Provides additional metadata like index if you need it, as well as a more generic separators.updateProps function which let you set whatever props you want to change the rendering of either the leading separator or trailing separator in case the more common highlight and unhighlight (which set the highlighted: boolean prop) are insufficient for your use case.

Type
function

• item (Object): The item from data being rendered.
• index (number): The index corresponding to this item in the data array.
• separators (Object)
  • highlight (Function)
  • unhighlight (Function)
  • updateProps (Function)
    • select (enum('leading', 'trailing'))
    • newProps (Object)

Example usage:

React TSX

<FlatList
  ItemSeparatorComponent={
    Platform.OS !== 'android' &&
    (({highlighted}) => (
      <View
        style={[style.separator, highlighted && {marginLeft: 0}]}
      />
    ))
  }
  data={[{title: 'Title Text', key: 'item1'}]}
  renderItem={({item, index, separators}) => (
    <TouchableHighlight
      key={item.key}
      onPress={() => this._onPress(item)}
      onShowUnderlay={separators.highlight}
      onHideUnderlay={separators.unhighlight}>
      <View style={{backgroundColor: 'white'}}>
        <Text>{item.title}</Text>
      </View>
    </TouchableHighlight>
  )}
/>

---

Required

data

An array (or array-like list) of items to render. Other data types can be used by targeting VirtualizedList directly.

Type
ArrayLike

---

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted and leadingItem props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, function, element

---

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, element

---

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, element

---

ListFooterComponentStyle

Styling for internal View for ListFooterComponent.

Type
View Style

---

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, element

---

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent.

Type
View Style

---

ListItemComponent

Each data item is rendered using this element, as an alternative to renderItem. It receives the same props, and takes precedence over renderItem when both are provided.

Type
component, element

---

columnWrapperStyle

Optional custom style for multi-item rows generated when numColumns > 1.

Type
View Style

---

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

Type
any

---

getItemLayout

React TSX

(data, index) => {length: number, offset: number, index: number}

getItemLayout is an optional optimization that allows skipping the measurement of dynamic content if you know the size (height or width) of items ahead of time. getItemLayout is efficient if you have fixed size items, for example:

React TSX

  getItemLayout={(data, index) => (
    {length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
  )}

Adding getItemLayout can be a great performance boost for lists of several hundred items. Remember to include separator length (height or width) in your offset calculation if you specify ItemSeparatorComponent.

Type
function

---

horizontal

If true, renders items next to each other horizontally instead of stacked vertically.

Type
boolean

---

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

Type	Default
number	10

---

initialScrollIndex

Instead of starting at the top with the first item, start at initialScrollIndex. This disables the "scroll to top" optimization that keeps the first initialNumToRender items always rendered and immediately renders the items starting at this initial index. Requires getItemLayout to be implemented.

Type
number

---

inverted

Reverses the direction of scroll. Uses scale transforms of -1.