FlatList

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

Array<ItemT>

required

An array (or array-like list) of items to render.

(info: ListRenderItemInfo<ItemT>) => React.Element | null

Takes an item from data and renders it into the list. Provides additional metadata like index and separators.

(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.

React.ComponentType

Rendered in between each item, but not at the top or bottom.

React.ComponentType | React.Element

Rendered at the top of all the items.

React.ComponentType | React.Element

Rendered at the bottom of all the items.

React.ComponentType | React.Element

Rendered when the list is empty.

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.

boolean

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

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.

ViewStyle

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

number

How many items to render in the initial batch. This should be enough to fill the screen but not much more.

number

Instead of starting at the top with the first item, start at initialScrollIndex. Requires getItemLayout to be implemented.

boolean

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

(info: {distanceFromEnd: number}) => void

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

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.

() => void

If provided, a standard RefreshControl will be added for “Pull to Refresh” functionality. Make sure to also set the refreshing prop correctly.

boolean

Set this true while waiting for new data from a refresh.

(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.

boolean

This may improve scroll performance for large lists. The default value is true for Android.

ViewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

(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

Core Components

User Interface

List Components

Android Components

iOS Components

Example

Props

Methods

scrollToEnd()

scrollToIndex()

scrollToItem()

scrollToOffset()

Performance

​Example

​Props

​Methods

​scrollToEnd()

​scrollToIndex()

​scrollToItem()

​scrollToOffset()

​Performance

Example

Props

Methods

scrollToEnd()

scrollToIndex()

scrollToItem()

scrollToOffset()

Performance