Skip to main content
A performant interface for rendering simple, flat lists, supporting the most handy features:
  • Fully cross-platform
  • Optional horizontal mode
  • Configurable viewability callbacks
  • Header and footer support
  • Separator support
  • Pull to refresh
  • Scroll loading
  • ScrollToIndex support
If you need section support, use SectionList.

​
Example

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

const DATA = [
  { id: '1', title: 'First Item' },
  { id: '2', title: 'Second Item' },
  { id: '3', title: 'Third Item' },
];

const App = () => {
  const renderItem = ({ item }) => (
    <View style={styles.item}>
      <Text style={styles.title}>{item.title}</Text>
    </View>
  );

  return (
    <FlatList
      data={DATA}
      renderItem={renderItem}
      keyExtractor={item => item.id}
    />
  );
};

const styles = StyleSheet.create({
  item: {
    backgroundColor: '#f9c2ff',
    padding: 20,
    marginVertical: 8,
    marginHorizontal: 16,
  },
  title: {
    fontSize: 32,
  },
});

export default App;

​
Props

​
data
Array<ItemT>
required
An array (or array-like list) of items to render.
​
renderItem
(info: ListRenderItemInfo<ItemT>) => React.Element | null
Takes an item from data and renders it into the list. Provides additional metadata like index and separators.
​
keyExtractor
(item: ItemT, index: number) => string
Used to extract a unique key for a given item at the specified index. The default extractor checks item.key, then falls back to using the index.
​
ItemSeparatorComponent
React.ComponentType
Rendered in between each item, but not at the top or bottom.
​
ListHeaderComponent
React.ComponentType | React.Element
Rendered at the top of all the items.
​
ListFooterComponent
React.ComponentType | React.Element
Rendered at the bottom of all the items.
​
ListEmptyComponent
React.ComponentType | React.Element
Rendered when the list is empty.
​
extraData
any
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.
​
horizontal
boolean
If true, renders items next to each other horizontally instead of stacked vertically.
​
numColumns
number
default:1
Multiple columns can only be rendered with horizontal={false} and will zig-zag like a flexWrap layout. Items should all be the same height.
​
columnWrapperStyle
ViewStyle
Optional custom style for multi-item rows generated when numColumns > 1.
​
initialNumToRender
number
How many items to render in the initial batch. This should be enough to fill the screen but not much more.
​
initialScrollIndex
number
Instead of starting at the top with the first item, start at initialScrollIndex. Requires getItemLayout to be implemented.
​
inverted
boolean
Reverses the direction of scroll. Uses scale transforms of -1.
​
onEndReached
(info: {distanceFromEnd: number}) => void
Called once when the scroll position gets within onEndReachedThreshold of the rendered content.
​
onEndReachedThreshold
number
How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback.
​
onRefresh
() => void
If provided, a standard RefreshControl will be added for “Pull to Refresh” functionality. Make sure to also set the refreshing prop correctly.
​
refreshing
boolean
Set this true while waiting for new data from a refresh.
​
getItemLayout
(data, index) => {length: number, offset: number, index: number}
An optional optimization that lets us skip measurement of dynamic content if you know the height of items a priori. getItemLayout is efficient and easy to use if you have fixed height items.
​
removeClippedSubviews
boolean
This may improve scroll performance for large lists. The default value is true for Android.
​
viewabilityConfig
ViewabilityConfig
See ViewabilityHelper.js for flow type and further documentation.
​
onViewableItemsChanged
(info: {viewableItems: Array<ViewToken>, changed: Array<ViewToken>}) => void
Called when the viewability of rows changes.

​
Methods

​
scrollToEnd()

scrollToEnd(params?: {animated?: boolean})
Scrolls to the end of the content. May be janky without getItemLayout prop.

​
scrollToIndex()

scrollToIndex(params: {
  animated?: boolean,
  index: number,
  viewOffset?: number,
  viewPosition?: number,
})
Scrolls to the item at the specified index such that it is positioned in the viewable area.

​
scrollToItem()

scrollToItem(params: {
  animated?: boolean,
  item: ItemT,
  viewOffset?: number,
  viewPosition?: number,
})
Requires linear scan through data - use scrollToIndex instead if possible.

​
scrollToOffset()

scrollToOffset(params: {animated?: boolean, offset: number})
Scroll to a specific content pixel offset in the list.

​
Performance

FlatList is a PureComponent which means it will not re-render if props remain shallow-equal. Make sure to:
  • Pass extraData if your renderItem depends on external data
  • Use keyExtractor to provide stable keys
  • Implement getItemLayout for fixed-height items
  • Use removeClippedSubviews for large lists

Build docs developers (and LLMs) love

Get started for freeTalk to us