README.md

react-native-sectioned-multi-select

Hi, there's a breaking change in v0.8.0, I chose not to release a major version for various reasons. Please see Icons. In short, you must pass Icon (from react-native-vector-icons, or any icon lib) to the IconRenderer prop now.

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: https://github.com/renrizzolo/react-native-sectioned-multi-select/blob/9c5f71852aef7a7ac03e7761d5dd810cd2ccef5d/exampleapp/App.js#L322-L397 (note the switch, you can refer to this to know what to map icon names to e.g if you're just passing in a different RN Vector Icons font).

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}
          readOnlyHeadings={true}
          onSelectedItemsChange={this.onSelectedItemsChange}
          selectedItems={this.state.selectedItems}
        />
      </View>
    );
  }
}

You can programatically remove all items by setting up a ref to the component:

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

and then use the _removeAllItems function:

onPress={() => this.SectionedMultiSelect._removeAllItems()}

You can open the modal programatically with the _toggleSelector() method:

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

Prop	Default	type	Desc
items		array	the items
uniqueKey	'id'	string	the unique key for your items
subKey	'sub'	string	the array of sub items within items
displayKey	'name'	string	the key for the display name / title of the item
iconKey		string	the key for the display icon / bitmap of the item
selectedItems	[]	array	the selected items
onSelectedItemsChange		function	function that runs when an item is toggled
onSelectedItemObjectsChange		function	function that returns the selected items as their original objects instead of an array of ids
onCancel		function	function that runs when the cancel button is pressed
onConfirm		function	function that runs when the confirm button is pressed
onToggleSelector		function	callback function that runs when the selector is toggled. receives a boolean for the open/close state of the modal

Options

Prop	Default	type	Desc
loading	false	bool	set the loading state, shows loadingComponent if true
single	false	bool	allow only one selection
showDropDowns	true	bool	whether to allow dropdown toggles to show/hide the sub items (if false, sub items are always shown)
expandDropDowns	false	bool	when using showDropDowns, set to true to expand all the dropdowns on mount
animateDropDowns	true	bool	whether to animate toggling of dropdowns
showChips	true	bool	whether to show the chips of the selected items
hideSelect	false	bool	hide the select component
hideConfirm	false	bool	hide the confirm buttom
showCancelButton	false	bool	Show a cancel button next to the confirm button. Dismisses modal and removes all selected items.
alwaysShowSelectText	false	bool	Don't show number of items selected or the single selected item on the select label (unless single is true).
readOnlyHeadings	false	bool	whether the parent items can be pressed or not. If true and showDropdowns is true, pressing the parent item will toggle the dropdown
hideSearch	false	bool	hide the search bar entirely
selectChildren	false	bool	if true, selecting a parent item will automatically select its children
highlightChildren	false	bool	if true, selecting a parent item will automatically highlight its children (but the child ids won't be broadcast to the selectedItems state)
showRemoveAll	false	bool	Whether to show a Remove all chip at the beginning of the selected items chips
modalSupportedOrientations	['landscape', 'portrait']	array	The supportedOrientations of the Modal
modalAnimationType	'fade'	string	The animation type of the Modal (fade or slide)
modalWithSafeAreaView	false	bool	If true uses a <SafeAreaView> component for the backdrop component. Useful for e.g iPhone X notch
modalWithTouchable	false	bool	If true wraps the backdrop component with <TouchableWithoutFeedback> . Closes modal on press (this._closeSelector(); fires onToggleSelector(false)).
parentChipsRemoveChildren	false	bool	If true, pressing a parent chip's remove button will remove all of its selected children.

Customization

Prop	Default	type	Desc
selectText	'Select'	string	the text for the select component
confirmText	'Confirm'	string	the text for the confirm button
selectedText	'selected'	string OR function	the text that follows the number of items selected
renderSelectText		function	Function that allows you to set custom Select Text given access to component's props
searchPlaceholderText	'Search categories...'	string	the placeholder text for the search input
searchAdornment		function	receives search input text and is output on the right side of the search input
removeAllText	'Remove all'	string	Text for optional remove all button
filterItems	null	function	Use a custom filtering function for the search: receives searchText, items, props. Should return an array of item objects.
headerComponent	undefined	object	optional component to display above the search bar
footerComponent	undefined	object	optional component to display below the confirm button
stickyFooterComponent	undefined	object	optional component to display below the confirm button, but outside of the scroll view
noResultsComponent	Sorry, no results	object	the component to display when the search results are empty
loadingComponent	ActivityIndicator	object	the component to display when loading is set to true
noItemsComponent	No Items	object	Shown when the items array is empty / null
selectToggleIconComponent	Material keyboard-arrow-down	object	The icon to the right of the dropdown in its initial state )
searchIconComponent	Material search	object	The search input icon (default Magnifying glass)
selectedIconComponent	Material check	object	The icon component to the left of the selected item (default Checkmark)
unselectedIconComponent		object	The icon component to the left of the unselected item
dropDownToggleIconUpComponent	Material keyboard-arrow-up	object	The parent dropdown icon in closed state
dropDownToggleIconDownComponent	Material keyboard-arrow-down	object	The parent dropdown icon in opened state
cancelIconComponent	Material cancel	object	The cancel button's inner component
customChipsRenderer		function	Use a custom render function for custom chips: receives uniqueKey, subKey, displayKey, items, selectedItems, colors, styles. should return valid jsx
chipRemoveIconComponent	Material close	object	The chip remove button's icon component
styles	{}	object	Styles object - see styles section
colors	{...}	object	colors object - see colors section
itemFontFamily	Avenir / normal - bold	object	font family for the parent items. Can be a regular style object
subItemFontFamily	Avenir / normal - 200	object	font family for the sub items. Can be a regular style object
searchTextFontFamily	Avenir / normal - 200	object	font family for the search input. Can be a regular style object
confirmFontFamily	Avenir / normal - bold	object	font family for the confirm button.
itemNumberOfLines	null	number	numberOfLines for item text
selectLabelNumberOfLines	1	number	numberOfLines for select label text
customLayoutAnimation	easeInEaseOut	object	define your own LayoutAnimation preset or custom animation
IconRenderer		function OR object	The icon component to use. Receives name, size (in some cases), and style props
itemsFlatListProps	{}	object	extra props to add to / override the FlatList of parent items
subItemsFlatListProps	{}	object	extra props to add to / override the parent items' sub items FlatList

Colors

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

These are the available colors and their defaults:

Name	Default	Description
primary	#3f51b5	used for the dropdown toggle icon, the no results text and the background of the confirm button.
success	#4caf50	used for the selected checkmark icon.
cancel	#1A1A1A	used for the cancel button background
text	#2e2e2e	Parent item text color
subText	#848787	Sub item text color
selectToggleTextColor	#333	Select button text color
searchPlaceholderTextColor	#999	Search input placeholder text color
searchSelectionColor	rgba(0,0,0,0.2)	Search input text selection color
itemBackground	#fff	parent item background color
subItemBackground	#ffffff	sub item background color
chipColor	#848787	chip color
disabled	#d7d7d7	Selected icon color for sub items when highlight children is used

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.