SectionList

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

Fully cross-platform
Configurable viewability callbacks
List header support
List footer support
Item separator support
Section header support
Section separator support
Heterogeneous data and item rendering support
Pull to refresh
Scroll loading

If you don’t need section support and want a simpler interface, use FlatList.

Example

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

const DATA = [
  {
    title: 'Main dishes',
    data: ['Pizza', 'Burger', 'Risotto'],
  },
  {
    title: 'Sides',
    data: ['French Fries', 'Onion Rings', 'Fried Shrimps'],
  },
  {
    title: 'Drinks',
    data: ['Water', 'Coke', 'Beer'],
  },
];

const App = () => (
  <SectionList
    sections={DATA}
    keyExtractor={(item, index) => item + index}
    renderItem={({ item }) => (
      <View style={styles.item}>
        <Text style={styles.title}>{item}</Text>
      </View>
    )}
    renderSectionHeader={({ section: { title } }) => (
      <Text style={styles.header}>{title}</Text>
    )}
  />
);

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

export default App;

Props

Array<SectionT>

required

The actual data to render, akin to the data prop in FlatList. Each section object should contain:

data: Array of items in the section
renderItem: Optional custom renderer for items in this section
ItemSeparatorComponent: Optional custom separator for this section

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

Default renderer for every item in every section. Can be overridden on a per-section basis.

(info: {section: SectionT}) => React.Element | null

Rendered at the top of each section.

(info: {section: SectionT}) => React.Element | null

Rendered at the bottom of each section.

(item: ItemT, index: number) => string

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering.

React.ComponentType

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

React.ComponentType

Rendered at the top and bottom of each section.

React.ComponentType | React.Element

Rendered at the very beginning of the list.

React.ComponentType | React.Element

Rendered at the very end of the list.

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

number

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

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.

() => void

If provided, a standard RefreshControl will be added for “Pull to Refresh” functionality.

boolean

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

boolean

This may improve scroll performance for large lists.

boolean

Makes section headers stick to the top of the screen until the next one pushes it up. Only enabled by default on iOS.

Methods

scrollToLocation()

scrollToLocation(params: {
  animated?: boolean,
  itemIndex: number,
  sectionIndex: number,
  viewOffset?: number,
  viewPosition?: number,
})

Scrolls to the item at the specified sectionIndex and itemIndex positioned in the viewable area.

recordInteraction()

recordInteraction()

Tells the list an interaction has occurred, which should trigger viewability calculations.

flashScrollIndicators()

flashScrollIndicators()

Displays the scroll indicators momentarily. Platform: iOS

Section Structure

Each section in the sections array should have the following structure:

type Section = {
  // Required: Array of data items
  data: Array<ItemT>,
  
  // Optional: Custom renderer for items in this section
  renderItem?: (info: SectionListRenderItemInfo<ItemT>) => React.Element | null,
  
  // Optional: Custom separator for this section
  ItemSeparatorComponent?: React.ComponentType,
  
  // Optional: Any other custom properties you want to access
  [key: string]: any,
};

Performance Tips

Implement getItemLayout for better scrolling performance
Use keyExtractor to provide stable unique keys
Pass extraData if your renderItem depends on external data
Consider using removeClippedSubviews for very long lists

Core Components

User Interface

List Components

Android Components

iOS Components

Example

Props

Methods

scrollToLocation()

recordInteraction()

flashScrollIndicators()

Section Structure

Performance Tips

​Example

​Props

​Methods

​scrollToLocation()

​recordInteraction()

​flashScrollIndicators()

​Section Structure

​Performance Tips

Example

Props

Methods

scrollToLocation()

recordInteraction()

flashScrollIndicators()

Section Structure

Performance Tips