React Native Sectionlist Tutorial Examples

Introduction

React Native's SectionList component is a powerful tool for displaying sectioned data in scrollable lists. Unlike standard flat lists, SectionList organizes content into distinct groups with their own headers, making it ideal for contact lists, product catalogs, settings screens, and any data that benefits from categorical organization.

SectionList inherits from VirtualizedList, meaning it shares the same memory-efficient rendering approach that only displays items currently visible on screen. This makes it suitable for large datasets without sacrificing performance. The component supports fully cross-platform rendering, configurable viewability callbacks, list headers and footers, item and section separators, heterogeneous data types, pull-to-refresh functionality, and scroll loading, all documented in React Native's official documentation.

When to Use SectionList

SectionList excels in scenarios where data naturally groups into categories. Contact lists organized alphabetically, e-commerce product catalogs by category, settings screens with grouped options, chat applications with message threads, and timeline views with date-based sections all benefit from SectionList's structured approach.

For teams building mobile applications with React Native, SectionList provides a foundation for creating intuitive, organized interfaces that scale gracefully with content complexity. Understanding how SectionList compares to other React patterns, such as higher-order components, helps developers make informed architectural decisions for their applications.

Basic SectionList Implementation

Required Props

Every SectionList implementation requires two essential props: sections and renderItem. The sections prop accepts an array of section objects, where each object must contain a title and a data array containing the items for that section. The renderItem prop is a function that returns the UI representation for each item within a section.

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

const BasicSectionList = () => {
 const sections = [
 {
 title: 'Fruits',
 data: ['Apple', 'Banana', 'Orange', 'Mango']
 },
 {
 title: 'Vegetables',
 data: ['Carrot', 'Broccoli', 'Spinach']
 },
 {
 title: 'Dairy',
 data: ['Milk', 'Cheese', 'Yogurt']
 }
 ];

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

The keyExtractor prop generates unique keys for list items, which is crucial for React's reconciliation process and proper list updates. Without unique keys, React may not correctly track which items have changed, added, or removed, leading to rendering issues and potential bugs.

Our React development team regularly implements SectionList in production applications, applying these patterns to build performant, user-friendly mobile interfaces. For developers exploring TypeScript integration with React Native, the SectionList API supports type-safe section definitions that enhance code reliability.

Advanced Features

Custom Item Separators

Separators help users visually distinguish between items and sections. SectionList supports two types of separators: ItemSeparatorComponent for items within a section, and SectionSeparatorComponent for boundaries between different sections.

const renderSeparator = () => (
 <View style={styles.separator} />
);

<SectionList
 sections={sections}
 ItemSeparatorComponent={renderSeparator}
 SectionSeparatorComponent={SectionSeparator}
 // ...
/>

Pull to Refresh

Pull-to-refresh is a standard mobile pattern that allows users to update content by pulling down on the list.

const [refreshing, setRefreshing] = useState(false);

const onRefresh = async () => {
 setRefreshing(true);
 try {
 const newData = await fetchNewData();
 setData(newData);
 } catch (error) {
 console.error('Error refreshing:', error);
 }
 setRefreshing(false);
};

<SectionList
 sections={sections}
 refreshing={refreshing}
 onRefresh={onRefresh}
 // ...
/>

Sticky Headers

Sticky headers remain visible at the top of the viewport while scrolling through their section.

<SectionList
 sections={sections}
 stickySectionHeadersEnabled={true}
 // ...
/>

These features combine to create polished, professional list interfaces that match native mobile app expectations. When building cross-platform mobile applications, these patterns ensure consistent user experiences across iOS and Android devices.

Working with Complex Data

Nested Object Structures

Real-world applications often require displaying complex data with multiple properties. SectionList's flexible renderItem function can destructure and display nested objects effectively.

const complexData = [
 {
 title: 'Online Users',
 data: [
 { id: 1, name: 'John Doe', status: 'active', lastSeen: 'now' },
 { id: 2, name: 'Jane Smith', status: 'active', lastSeen: 'now' }
 ]
 },
 {
 title: 'Offline Users',
 data: [
 { id: 3, name: 'Mike Johnson', status: 'inactive', lastSeen: '2h ago' },
 { id: 4, name: 'Sarah Wilson', status: 'inactive', lastSeen: '1d ago' }
 ]
 }
];

const renderItem = ({ item }) => (
 <View style={styles.complexItem}>
 <Text style={styles.userName}>{item.name}</Text>
 <View style={styles.userInfo}>
 <Text style={styles.status}>
 {item.status === 'active' ? '🟢' : '⚫️'}
 </Text>
 <Text style={styles.lastSeen}>{item.lastSeen}</Text>
 </View>
 </View>
);

Custom Section Rendering

Each section can define its own renderItem function, enabling different item layouts for different section types. This capability allows developers to create rich, varied interfaces within a single list component.

For enterprise mobile applications handling complex data hierarchies, SectionList's per-section rendering provides the flexibility needed to display diverse content types elegantly. This pattern is particularly valuable when integrating with API testing tools that return varied data structures across different endpoints.

Performance Optimization

Using getItemLayout

For lists with items of consistent height, providing getItemLayout eliminates the need for SectionList to measure items dynamically.

const getItemLayout = (data, index) => ({
 length: 50,
 offset: 50 * index,
 index
});

<SectionList
 sections={sections}
 getItemLayout={getItemLayout}
 // ...
/>

Memoization with useCallback

Memoizing render functions with useCallback prevents unnecessary re-renders when parent components update.

const renderItem = useCallback(({ item }) => (
 <View style={styles.item}>
 <Text>{item.name}</Text>
 </View>
), []);

Batch Rendering Configuration

• initialNumToRender: Number of items to render in the initial batch (default: 10)
• maxToRenderPerBatch: Number of items to render per subsequent batch
• windowSize: Number of viewports worth of content to keep rendered

<SectionList
 sections={sections}
 initialNumToRender={10}
 maxToRenderPerBatch={10}
 windowSize={5}
 removeClippedSubviews={true}
 // ...
/>

Implementing these optimization techniques is essential for achieving smooth 60fps scrolling in lists with hundreds or thousands of items. Our performance testing methodology ensures that mobile applications deliver responsive, fluid user experiences even under heavy data loads.

SectionList Methods

scrollToLocation

The scrollToLocation method programmatically scrolls to a specific item within a section.

const sectionListRef = useRef(null);

const scrollToSecondSection = () => {
 sectionListRef.current?.scrollToLocation({
 sectionIndex: 1,
 itemIndex: 0,
 viewPosition: 0,
 animated: true
 });
};

flashScrollIndicators

On iOS, flashScrollIndicators() momentarily displays scroll indicators.

recordInteraction

The recordInteraction() method notifies the list that user interaction has occurred.

These imperative methods provide fine-grained control over list behavior, enabling features like jump-to-section navigation, animated transitions, and programmatic scroll management that enhance overall user experience. When combined with advanced CSS animation techniques, developers can create smooth, polished user interfaces that rival native applications.

Best Practices

Data Structure Design

Design your section data structure to be consistent and predictable. Each section should have a meaningful title that helps users understand the grouping, and the data array should contain items with consistent properties across sections.

Key Generation

Always provide a robust keyExtractor function that generates unique, stable keys for items. Avoid using array indices as keys when items can be added, removed, or reordered.

Empty States

Handle empty sections gracefully using the ListEmptyComponent prop.

Accessibility

Ensure section headers and items are accessible by providing proper labels and considering platform-specific accessibility features.

Platform-Specific Considerations

Note that stickySectionHeadersEnabled defaults to true on iOS but false on Android. Always test sticky header behavior on both platforms.

Following these best practices ensures that your React Native implementations are robust, accessible, and deliver consistent experiences across all supported platforms. For teams adopting modern styling approaches like Panda CSS, SectionList components can be styled consistently with type-safe CSS-in-JS patterns.

Sources

1. React Native SectionList Documentation - Official API reference with all props, methods, and type definitions
2. Galaxies.dev React Native SectionList Tutorial - Comprehensive guide with practical examples and best practices
3. GeeksforGeeks SectionList Component - Beginner-friendly explanation and examples