A performant and customizable Alphabet Section List for React Native.
npm install react-native-letter-flatlist|
AlphabetList is a customizable FlatList-based AβZ index list component for React Native. It allows you to display large datasets grouped by alphabet with smooth scroll-to-letter functionality. The component features a vertical alphabet sidebar that users can tap to jump directly to a section. It supports custom rendering for both items and headers, as well as styling options for all UI elements. Ideal for contact lists, brand directories, or any sorted data that benefits from alphabetical navigation. Built with TypeScript and supports local or remote images with minimal configuration. |
|
sh
npm install react-native-letter-flatlist
`
---
π Usage
`tsx
import React from 'react';
import { SafeAreaView, StyleSheet } from 'react-native';
import { AlphabetList } from 'react-native-letter-flatlist';
const people = [
{ name: 'Alice' },
{ name: 'Amanda' },
{ name: 'Ben' },
{ name: 'Charlie' },
{ name: 'David' },
{ name: 'Eve' },
{ name: 'Frank' },
{ name: 'Zack' },
];
export default function App() {
return (
data={people}
sortField="name"
showHeader={true}
showAllLetters={true}
/>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
},
});
`
---
βοΈ Props
| Prop | Type | Default | Description |
|-------------------------|----------------------------------|-----------|-----------------------------------------------------------------------------|
| data | T[] | β | The array of items to display. |
| sortField | keyof T | β | The key used to group and sort items alphabetically. |
| renderItem | (item: T) => ReactElement | Default | Optional custom render for each item. |
| renderHeader | (letter: string) => ReactElement| Default | Optional custom render for each alphabet header. |
| showHeader | boolean | true | Whether to show alphabet headers above each section. |
| showAllLetters | boolean | false | Whether to show all AβZ even if no items exist under some letters. |
| itemHeight | number | 40 | Height for each item row (for scroll positioning). |
| headerHeight | number | 40 | Height for each header row (for scroll positioning). |
| itemTextStyle | TextStyle | β | Style override for default item text. |
| headerContainerStyle | ViewStyle | β | Style override for default header container. |
| headerTextStyle | TextStyle | β | Style override for default header text. |
| activeAlphabetStyle | TextStyle | β | Style for active (clickable) letters in the right-side index. |
| inactiveAlphabetStyle | TextStyle | β | Style for inactive (non-clickable) letters in the right-side index. |
| alphabetContainerStyles| ViewStyle | β | Style for the container of the right-side alphabet list. |
---
π¨ Style Customization
| Prop | Type | Description |
|---------------------------|-------------|-----------------------------------------------------------------------------|
| itemTextStyle | TextStyle | Style override for the default item text. |
| headerContainerStyle | ViewStyle | Style override for the default header container. |
| headerTextStyle | TextStyle | Style override for the default header text. |
| activeAlphabetStyle | TextStyle | Style for active (clickable) alphabet letters in the right-side index. |
| inactiveAlphabetStyle | TextStyle | Style for inactive (non-clickable) alphabet letters in the right-side index.|
| alphabetContainerStyles | ViewStyle | Style for the vertical container of the right-side AβZ index. |
---
πΌ Supported Image Formats
- Remote image objects: { uri: 'https://...' }
- Local image assets: require('./path/to/image.jpg')
- Direct string URLs: 'https://example.com/image.jpg'
---
π§ Best Practices
- Outer container height of AlphabetList must be greater than or euqal to the alphabets height for better performance
---
π‘ Tip
To use default rendering:
- You can skip renderItem and/or renderHeader β default components will be used.
- Set showHeader={false} to hide alphabet section headers entirely.
- Enable showAllLetters={true}` to display all AβZ letters on the right side, even if some letters have no matching data (they will appear disabled).