react-native-lexical-list

This is a wrapper to the SectionList, adding support for alphabets on the side, which can be dragged or clicked, to scroll the list to the corresponding section.

Table of contents

• Demo
• Getting started
• Usage
  • LexicalSectionList component
    • Props
    • Use of getItemLayout
    • Optimization
  • AlphabetList component
    • Props

Demo

Source code

Getting started

yarn add react-native-lexical-list

or

npm install react-native-lexical-list

Usage

LexicalSectionList component

import LexicalSectionList from "react-native-lexical-list";

export const TestList = () => {
  const sections = [
    {
      title: "A",
      data: ["Alison", "Arthur", "Amy"],
    },
    {
      title: "B",
      data: ["Ben", "Bob", "Barney", "Batman"],
    },
    {
      title: "C",
      data: ["Charlie", "Chaplin"],
    },
  ];

  return (
    <LexicalSectionList
      sections={sections}
      itemHeight={24}
      alphabetListOptions={{ itemHeight: 18 }}
      renderItem={({ item }) => <Text>{item}</Text>}
      renderSectionHeader={({ section: { title } }) => <Text>{title}</Text>}
    />
  );
};

Props

All of the SectionList props can be passed to LexicalSectionList.

The sections must have a title field as shown above. This is used to display items in the AlphabetList on the side and also in the section headers. The data field can be an array of any type.

Following are the additional props added to LexicalSectionList:

| Prop | Type | Required | Desc | | :----------------------------: | :--------------------: | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | alphabetListOptions | object | Yes | Props to be passed on to the AlphabetList component. See AlphabetList Props below. | | itemHeight | number | Yes | Height of rows of the SectionList. See getItemLayout below. | | sectionHeaderHeight | number | No | See getItemLayout below | | sectionFooterHeight | number | No | See getItemLayout below | | separatorHeight | number | No | See getItemLayout below | | listHeaderHeight | number | No | See getItemLayout below | | disableScrollToTopOnDataUpdate | boolean | No | When the value of the sections prop changes, the list scrolls to the top by default. This is useful for when the list is updated using search filtering. | | style | StyleProp<ViewStyle> | No | Container style | | listStyle | StyleProp<ViewStyle> | No | This is passed on to the underlying SectionList as style prop |

Use of getItemLayout

When the user chooses an alphabet, to be able to scroll list to the correct position, SectionList requires us to supply a getItemLayout method. As explained in this post, it is tricky to implement it for SectionList (as opposed to FlatList). An open source function (from the writer of that post) has been used, which requires item height, and optionally four other parameters. Visit the npm page for full documentation.

Optimization

initialNumToRender and maxToRenderPerBatch are SectionList props (which means they can be passed to LexicalSectionList as well), whose default values in react-native are 10 each. But because this kind of a lexical list is generally used with small amount of data to be rendered within each row, for a lot of rows, these values have been set to 100. This results in fast scrolling with much less blank spots, at the cost of a little higher memory usage. If you are rendering a lot of stuff within each item of the list, or are doing lengthy computations for each item, you might want to lower this number.

AlphabetList component

LexicalSectionList contains a SectionList and an AlphabetList. If you don't want the full thing, you can use the AlphabetList component by itself. It can be seen as a draggable list of strings or numbers, which returns the currently selected item and its index in a callback function.

import { AlphabetList } from "react-native-lexical-list";

...

<AlphabetList
  data={["A", "G", "H"]}
  itemHeight={18}
  itemStyle={{ fontWeight: "bold", color: "blue" }}
  onItemSelect={(alphabet) => console.log(alphabet)}
  containerStyle={{
    backgroundColor: "green"
    alignSelf: "center",
  }}
/>;

Props

| Prop | Type | Required | Desc | | :----------------: | :------------------------------------------------------------------------------------------: | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | data | (string or number)[] | Yes | Items to display in the AlphabetList. Generally these would be alphabets, but doesn't have to be. | | itemHeight | number | Yes | Height of each item in the AlphabetList, for accurate touch detection. It is recommended to use alignItems/justifyContent: 'center' with fixed height instead of using margins (padding should be fine). | | itemStyle | StyleProp<TextStyle> | No | Styles for the list item text | | containerStyle | StyleProp<ViewStyle> | No | Styles for the AlphabetList container | | indicatorStyle | StyleProp<ViewStyle> | No | Styles for the currently selected item indicator that pops up on the side while scrolling | | indicatorTextStyle | StyleProp<TextStyle> | No | Styles for the indicator text | | onItemSelect | function that takes parameters (item: string or number, index: number) and returns nothing | No | A callback function that is called each time the item selection changes |