Wondering what’s next for npm?Check out our public roadmap! »

    react-native-sectioned-multi-select
    TypeScript icon, indicating that this package has built-in type declarations

    0.8.1 • Public • Published

    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.

    NPM Version

    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

    preview 1 preview 2 preview 3 preview 4

    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.

    Install

    npm i react-native-sectioned-multi-select

    DownloadsWeekly Downloads

    2,808

    Version

    0.8.1

    License

    MIT

    Unpacked Size

    3.5 MB

    Total Files

    35

    Last publish

    Collaborators

    • avatar