Skip to main content
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

​
sections
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
​
renderItem
(info: SectionListRenderItemInfo<ItemT>) => React.Element | null
Default renderer for every item in every section. Can be overridden on a per-section basis.
​
renderSectionHeader
(info: {section: SectionT}) => React.Element | null
Rendered at the top of each section.
​
renderSectionFooter
(info: {section: SectionT}) => React.Element | null
Rendered at the bottom of each section.
​
keyExtractor
(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.
​
ItemSeparatorComponent
React.ComponentType
Rendered in between each item, but not at the top or bottom of each section.
​
SectionSeparatorComponent
React.ComponentType
Rendered at the top and bottom of each section.
​
ListHeaderComponent
React.ComponentType | React.Element
Rendered at the very beginning of the list.
​
ListFooterComponent
React.ComponentType | React.Element
Rendered at the very end of the list.
​
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).
​
initialNumToRender
number
How many items to render in the initial batch. This should be enough to fill the screen but not much more.
​
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.
​
onRefresh
() => void
If provided, a standard RefreshControl will be added for “Pull to Refresh” functionality.
​
refreshing
boolean
Set this true while waiting for new data from a refresh.
​
removeClippedSubviews
boolean
This may improve scroll performance for large lists.
​
stickySectionHeadersEnabled
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

Build docs developers (and LLMs) love

Get started for freeTalk to us