# rn-alphabet-section-list

> A simple React Native component that takes an array of data and renders a SectionList with alphabetically sorted data.

Latest version **1.0.9** (published 2021-02-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install rn-alphabet-section-list
pnpm add rn-alphabet-section-list
yarn add rn-alphabet-section-list
bun add rn-alphabet-section-list
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.9 |
| Published | 2021-02-04 |
| First published | 2021-02-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 23 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Kieran McIntyre, johnagill-1 |
| Maintainers | johnstakester |
| Keywords | react-native, alphabet, SectionList, letters, address, addressbook, custom |

## Links

- npm: https://www.npmjs.com/package/rn-alphabet-section-list
- Repository: https://github.com/johnagill-1/react-native-alphabet-list
- Homepage: https://github.com/johnagill-1/react-native-alphabet-list#readme
- Issues: https://github.com/johnagill-1/react-native-alphabet-list/issues
- npm.io page: https://npm.io/package/rn-alphabet-section-list

## Dependencies (1)

- [react-native-section-list-get-item-layout](https://npm.io/package/react-native-section-list-get-item-layout.md) ^2.2.3

## Recent versions

- 1.0.9 (latest) — 2021-02-04
- 1.0.8 — 2021-02-04
- 1.0.7 — 2021-02-04
- 1.0.6 — 2021-02-04
- 1.0.5 — 2021-02-04
- 1.0.4 — 2021-02-04
- 1.0.3 — 2021-02-04
- 1.0.2 — 2021-02-04
- 1.0.1 — 2021-02-04

## README

# rn-alphabet-section-list

A simple React Native component that takes an array of data and renders a SectionList with alphabetically (or custom) sorted data.

![AlphabetList](https://media.giphy.com/media/SACshMzMIP2NvP8rvY/giphy.gif)

## Motivation

Unlike alternatives, this package takes an array of data rather than an object with letters as keys.

For example,

_Other packages_

```javascript
const data = {
  A: [{...}, ...],
  B: [{...}, ...],
  C: [{...}, ...],
  ...
}
```

_This package_

```javascript
const data = [{...}, {...}, {...}, ...]
```

For _react-native-section-alphabet-list_, the data does not need to be pre-formatted and sorted before use. The component handles all this logic internally. You can also provide an array of characters to sort your sections in a custom order.

## Installation

Using npm:

```bash
npm install react-native-section-alphabet-list
```

or with yarn:

```bash
yarn add react-native-section-alphabet-list
```

## Basic Usage

```javascript
import { AlphabetList } from "react-native-section-alphabet-list";

const data = [
  { value: 'Lillie-Mai Allen', key: 'lCUTs2' },
  { value: 'Emmanuel Goldstein', key: 'TXdL0c' },
  { value: 'Winston Smith', key: 'zqsiEw' },
  { value: 'William Blazkowicz', key: 'psg2PM' },
  { value: 'Gordon Comstock', key: '1K6I18' },
  { value: 'Philip Ravelston', key: 'NVHSkA' },
  { value: 'Rosemary Waterlow', key: 'SaHqyG' },
  { value: 'Julia Comstock', key: 'iaT1Ex' },
  { value: 'Mihai Maldonado', key: 'OvMd5e' },
  { value: 'Murtaza Molina', key: '25zqAO' },
  { value: 'Peter Petigrew', key: '8cWuu3' },
]

render() {
  return (
    <AlphabetList
      data={data}
      indexLetterColor={'blue'}
      renderCustomItem={(item) => (
        <View style={styles.listItemContainer}>
          <Text style={styles.listItemLabel}>{item.value}</Text>
        </View>
      )}
      renderCustomSectionHeader={(section) => (
        <View style={styles.sectionHeaderContainer}>
          <Text style={styles.sectionHeaderLabel}>{section.title}</Text>
        </View>
      )}
    />
  )
}
```

## API

### Props

| Prop | Description | Type | Signature (func) | Default |
| --- | --- | --- | --- | --- |
| `data` | List of objects to be sorted and rendered in the `SectionList`. Each item must have both a `value` property and unique a `key` property. | `array` | | |
| `index` (optional) | The characters used to sort each item into sections. These characters are rendered on the right-hand side and clicking on each item scrolls the user to its respective section. The default is the letters of the alphabet. | `array` | | `['a', 'b', 'c', 'd', 'e', 'f', ...]` (see `DEFAULT_CHAR_INDEX` [here](https://github.com/Kieran-McIntyre/react-native-section-alphabet-list/blob/master/src/values/consts.ts))|
| `renderCustomItem` (optional) | Render a row in the SectionList. Should return a valid React Element. | `func` | `{ item: { value: string, key: string } } : ReactElement` | |
| `renderCustomSectionHeader` (optional) | Render a section header in the SectionList. Should return a valid React Element. | `func` | `{ section: { title: string, index: number, data: array } } : ReactElement` | |
| `getItemHeight` (optional) | For [`sectionListGetItemLayout`](https://www.npmjs.com/package/react-native-section-list-get-item-layout). This may be necessary if each item has a dynamic height. This allows for smooth scrolling and accurate positioning when scrolling to a section.  | `func` | `{ sectionIndex: number, rowIndex: number } : number`  | |
| `sectionHeaderHeight` (optional) | The height of the section header. | `number` | | `40` |
| `indexLetterColor` (optional) | Changes the colour of each character in the letter index.  | `string` | | `#007aff` |
| `uncategorizedAtTop` (optional) | If `true`, the uncategorised items (the `#` section) is moved to the top of the list.  | `boolean` | | false |

You can also provide any valid `SectionList` props. A list of available props can be found [here](https://reactnative.dev/docs/sectionlist#props).

### Custom `index`

You can provide a custom array of characters to the component using the `index` prop. For example, if we wanted to sort alphabetically in-reverse, we could do:

```javascript
const customIndex = [
  'z',
  'y',
  'x',
  'w',
  ...
]

<AlphabetList
  ...
  index={customIndex}
/>
```


## Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update the tests as appropriate.

## License

[MIT](https://choosealicense.com/licenses/mit/)

---
_Source: https://npm.io/package/rn-alphabet-section-list · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._