react-native-sectioned-multi-select

A multi (or single) select component with support for sub categories, search, chips. It's intended for long-ish lists, as it opens in a Modal (I might make this optional in the future).

This is based on https://github.com/toystars/react-native-multiple-select. The problems I had were that I needed it to be in a modal, because of nested ScrollViews not working on Android, and I needed to display categories with sub-categories.

Caveats

• Currently all ids must be unique. So if you're pulling data from multiple sources, be aware that id clashes will cause (major) problems i.e both items with the same id will get selected. Looking for contributors for this - would require a bit of a refactor (see #33).
• There is no ajax support.

Preview

Usage

You can install this package with the following command: npm i react-native-sectioned-multi-select or yarn add react-native-sectioned-multi-select

Icons

The library uses icon names from react-native-vector-icons/MaterialIcons, however, it no longer imports the react-native-vector-icons library. You should install react-native-vector-icons yourself, then pass the icon to the IconRenderer prop.

import Icon from 'react-native-vector-icons/MaterialIcons`
...
<SectionedMultiSelect IconRenderer={Icon} />

Similarly, for Expo environments you can use:

import {MaterialIcons} from '@expo/vector-icons';
...
<SectionedMultiSelect IconRenderer={MaterialIcons} />

If you prefer to use your own icon images or icon font, the IconRenderer prop can be used to replace the icons used. See an example here:

icons prop

You can now pass your own icons object to map the properties to a different icon library or your own IconRenderer component. For each of these keys, the IconRenderer will be called with the corresponding name and size props. All properties are spread to the IconRenderer, so you can override style or other props your icon component might use.

Here is the default icons object, which uses Material Icons names.

icons: {
  search: {
    name: 'search', // search input
    size: 24
  },
  arrowUp: {
    name: 'keyboard-arrow-up', // dropdown toggle
    size: 22
  },
  arrowDown: {
    name: 'keyboard-arrow-down', // dropdown toggle
    size: 22
  },
  selectArrowDown: {
    name: 'keyboard-arrow-down', // select
    size: 24
  },
  close: {
    name: 'close', // chip close
    size: 16
  },
  check: {
    name: 'check', // selected item
    size: 16
  },
  cancel: {
    name: 'cancel', // cancel button
    size: 18
  }
}

Required props:

items | array
uniqueKey | string
onSelectedItemsChange | function
IconRenderer | function or object

Basic Example

import React, { Component } from 'react';
import { View } from 'react-native';
import Icon from 'react-native-vector-icons/MaterialIcons'
import SectionedMultiSelect from 'react-native-sectioned-multi-select';

const items = [
  // this is the parent or 'item'
  {
    name: 'Fruits',
    id: 0,
    // these are the children or 'sub items'
    children: [
      {
        name: 'Apple',
        id: 10,
      },
      {
        name: 'Strawberry',
        id: 17,
      },
      {
        name: 'Pineapple',
        id: 13,
      },
      {
        name: 'Banana',
        id: 14,
      },
      {
        name: 'Watermelon',
        id: 15,
      },
      {
        name: 'Kiwi fruit',
        id: 16,
      },
    ],
  },
  {
    // next parent item
   ...
  },

];

export default class App extends Component {
  constructor() {
    super();
    this.state = {
      selectedItems: [],
    };
  }
  onSelectedItemsChange = (selectedItems) => {
    this.setState({ selectedItems });
  };

  render() {
    return (
      <View>
        <SectionedMultiSelect
          items={items}
          IconRenderer={Icon}
          uniqueKey="id"
          subKey="children"
          selectText="Choose some things..."
          showDropDowns={true}
          onSelectedItemsChange={this.onSelectedItemsChange}
          selectedItems={this.state.selectedItems}
        />
      </View>
    );
  }
}

Refs / internal methods

You can do some programatic operations by setting up a ref to the component and accessing its internal methods:

// function component
import React, { useRef } from 'react'

const App = () => {
const ref = useRef(null)
  return (
    <SectionedMultiSelect
      ...
      ref={ref}
    />
  )
}

// class component
<SectionedMultiSelect
    ...
    ref={SectionedMultiSelect => this.SectionedMultiSelect = SectionedMultiSelect}
/>

Remove all items:

// function component
onPress={() => ref && ref.current && ref.current._removeAllItems()}
// class component
onPress={() => this.SectionedMultiSelect._removeAllItems()}

Toggle the modal:

// function component
onPress={() => ref && ref.current && ref.current._toggleSelector()}
// class component
onPress={() => this.SectionedMultiSelect._toggleSelector()}

Recipes

See Recipes for more detailed usage examples / customizations.

Items

Your items should have a uniqueKey(default: 'id') and a displayKey (default: 'name'). Any child items of that item should be in subKey, and they will have uniqueKey and displayKey properties. As you can see from the example above, my items all have a unique id property and the child items is an array within the subKey property.

Sub categories are optional, there's no need to have subKey items if you don't want to.

You can also pass in extra options to individual items:

• disabled: true - the item will be disabled
• Icons: the component prop iconKey is the name of the property that individual item icons will be derived from. E.g icon: {uri: ...}. See full example here

Props

Props, there are lots.

Main

Options

Customization

Colors

You can pass a colors object to theme it how you like.

These are the available colors and their defaults:

Styles

You can pass a styles object to style it how you like.

These are the styles you can change:
container modalWrapper backdrop listContainer
selectToggle
selectToggleText
item
selectedItem
subItem
itemText selectedItemText
selectedSubItemText selectedSubItem subItemText
searchBar
center
separator
subSeparator
chipsWrapper
chipContainer parentChipContainer parentChipText chipText
chipIcon
searchTextInput
scrollView
button
confirmText
cancelButton
itemIconStyle

Changelog

View changelog.