expo-react-native-multiple-select

A multi-select component for React Native and Expo, rewritten in TypeScript. Inspired by react-native-multiple-select.

Installation

npm install expo-react-native-multiple-select

Expo projects

No extra setup needed. The component uses @expo/vector-icons for icons, which is included in the Expo SDK.

Bare React Native projects

Install react-native-vector-icons as a fallback:

npm install react-native-vector-icons

Follow the react-native-vector-icons installation guide for native linking.

Custom icons

You can skip both icon libraries entirely by providing your own icons via IconComponent or renderIcon. See Custom Icons below.

Usage

Basic multi-select

import { useState } from 'react';
import MultiSelect from 'expo-react-native-multiple-select';

const items = [
  { _id: '1', name: 'JavaScript' },
  { _id: '2', name: 'TypeScript' },
  { _id: '3', name: 'Python' },
  { _id: '4', name: 'Go' },
];

export default function App() {
  const [selected, setSelected] = useState<string[]>([]);

  return (
    <MultiSelect
      items={items}
      selectedItems={selected}
      onSelectedItemsChange={setSelected}
      selectText="Pick languages"
      searchInputPlaceholderText="Search languages..."
      submitButtonText="Done"
    />
  );
}

Single select

<MultiSelect
  items={items}
  selectedItems={selected}
  onSelectedItemsChange={setSelected}
  single
  selectText="Pick one"
/>

Typed usage with custom keys

interface Fruit {
  id: string;
  label: string;
  disabled?: boolean;
}

const fruits: Fruit[] = [
  { id: 'apple', label: 'Apple' },
  { id: 'banana', label: 'Banana' },
  { id: 'cherry', label: 'Cherry', disabled: true },
];

<MultiSelect<Fruit>
  items={fruits}
  selectedItems={selected}
  onSelectedItemsChange={setSelected}
  uniqueKey="id"
  displayKey="label"
/>

Custom icons

Override all icons with a component:

import { Ionicons } from '@expo/vector-icons';

<MultiSelect
  items={items}
  selectedItems={selected}
  onSelectedItemsChange={setSelected}
  IconComponent={Ionicons}
/>

Or use a render function for full control:

<MultiSelect
  items={items}
  selectedItems={selected}
  onSelectedItemsChange={setSelected}
  renderIcon={({ name, size, color, style }) => (
    <MyCustomIcon name={name} size={size} color={color} style={style} />
  )}
/>

Override only the search icon:

<MultiSelect
  items={items}
  selectedItems={selected}
  onSelectedItemsChange={setSelected}
  searchIcon={<Ionicons name="search" size={20} color="#999" />}
/>

Imperative methods via ref

import { useRef } from 'react';
import MultiSelect from 'expo-react-native-multiple-select';
import type { MultiSelectHandle } from 'expo-react-native-multiple-select';

function MyComponent() {
  const ref = useRef<MultiSelectHandle>(null);

  return (
    <>
      <MultiSelect
        ref={ref}
        items={items}
        selectedItems={selected}
        onSelectedItemsChange={setSelected}
      />
      <Button title="Clear all" onPress={() => ref.current?._removeAllItems()} />
      <Button title="Toggle" onPress={() => ref.current?._toggleSelector()} />
    </>
  );
}

Add new items inline

<MultiSelect
  items={items}
  selectedItems={selected}
  onSelectedItemsChange={setSelected}
  canAddItems
  onAddItem={(updatedItems) => {
    // updatedItems includes the newly created item
    setItems(updatedItems);
  }}
/>

Props

Core

| Prop | Type | Default | Description | |------|------|---------|-------------| | items | T[] | required | Array of item objects | | selectedItems | (string \| number)[] | [] | Array of selected item keys | | onSelectedItemsChange | (items: (string \| number)[]) => void | required | Called when selection changes | | uniqueKey | string | '_id' | Property name used as unique identifier | | displayKey | string | 'name' | Property name used for display text | | single | boolean | false | Single-select mode |

Text

| Prop | Type | Default | |------|------|---------| | selectText | string | 'Select' | | selectedText | string | 'selected' | | searchInputPlaceholderText | string | 'Search' | | submitButtonText | string | 'Submit' | | noItemsText | string | 'No items to display.' |

Appearance

| Prop | Type | Default | |------|------|---------| | fontSize | number | 14 | | itemFontSize | number | 16 | | textColor | string | '#525966' | | tagBorderColor | string | '#00A5FF' | | tagTextColor | string | '#00A5FF' | | tagRemoveIconColor | string | '#C62828' | | selectedItemTextColor | string | '#00A5FF' | | selectedItemIconColor | string | '#00A5FF' | | itemTextColor | string | '#525966' | | submitButtonColor | string | '#CCC' |

Fonts

| Prop | Type | Default | |------|------|---------| | fontFamily | string | '' | | altFontFamily | string | '' | | selectedItemFontFamily | string | '' | | itemFontFamily | string | '' |

Layout

| Prop | Type | Default | Description | |------|------|---------|-------------| | fixedHeight | boolean | false | Fixed 250px dropdown height | | hideTags | boolean | false | Hide selected item tags | | hideSubmitButton | boolean | false | Hide submit button | | hideDropdown | boolean | false | Hide back arrow icon | | removeSelected | boolean | false | Hide already-selected items from list |

Search & Add

| Prop | Type | Default | Description | |------|------|---------|-------------| | canAddItems | boolean | false | Allow adding new items via search | | onAddItem | (items: T[]) => void | -- | Called with updated items array | | onChangeInput | (text: string) => void | -- | Called when search input changes | | filterMethod | 'partial' \| 'full' | 'partial' | Search filter strategy |

Callbacks

| Prop | Type | Description | |------|------|-------------| | onClearSelector | () => void | Called when selector closes via back arrow | | onToggleList | () => void | Called when selector opens or closes |

Icons

| Prop | Type | Description | |------|------|-------------| | searchIcon | ReactNode | Custom search icon (overrides all other icon resolution for search only) | | IconComponent | ComponentType<IconAdapterProps> | Custom icon component for all icons | | renderIcon | (props: IconAdapterProps) => ReactNode | Render function for all icons |

Icon resolution precedence: searchIcon (search only) > renderIcon > IconComponent > @expo/vector-icons > react-native-vector-icons.

Style overrides

| Prop | Type | |------|------| | tagContainerStyle | StyleProp<ViewStyle> | | styleMainWrapper | StyleProp<ViewStyle> | | styleSelectorContainer | StyleProp<ViewStyle> | | styleInputGroup | StyleProp<ViewStyle> | | styleItemsContainer | StyleProp<ViewStyle> | | styleListContainer | StyleProp<ViewStyle> | | styleDropdownMenu | StyleProp<ViewStyle> | | styleDropdownMenuSubsection | StyleProp<ViewStyle> | | styleRowList | StyleProp<ViewStyle> | | styleTextDropdown | StyleProp<TextStyle> | | styleTextDropdownSelected | StyleProp<TextStyle> | | styleTextTag | StyleProp<TextStyle> | | styleIndicator | StyleProp<TextStyle> | | searchInputStyle | StyleProp<TextStyle> |

Input passthrough

| Prop | Type | Description | |------|------|-------------| | textInputProps | Partial<TextInputProps> | Extra props for the search TextInput | | flatListProps | Partial<FlatListProps<T>> | Extra props for the items FlatList |

Ref methods

| Method | Description | |--------|-------------| | _removeAllItems() | Clear all selected items | | _removeItem(item) | Remove a specific item from selection | | _toggleSelector() | Open or close the dropdown | | getSelectedItemsExt(items?) | Returns a React element rendering selected item tags |

Migration from react-native-multiple-select

This package is a TypeScript rewrite of react-native-multiple-select. All legacy props and behaviors are preserved.

What changed:

• Default icon library is @expo/vector-icons instead of react-native-vector-icons
• Written in TypeScript with full type definitions
• Functional component instead of class component
• New IconComponent and renderIcon props for custom icon overrides
• Generic type support: MultiSelect<T> for typed item objects
• No lodash dependency

What stayed the same:

• All prop names and default values
• uniqueKey / displayKey pattern
• Single-select and multi-select behavior
• Search, filter, and add-item flows
• Style override props
• Ref methods (_removeAllItems, _removeItem, _toggleSelector, getSelectedItemsExt)

Minimal migration:

- import MultiSelect from 'react-native-multiple-select';
+ import MultiSelect from 'expo-react-native-multiple-select';

If you were using react-native-vector-icons directly and are now on Expo, no other changes are needed -- icons resolve automatically.

Exports

// Default export
import MultiSelect from 'expo-react-native-multiple-select';

// Named type exports
import type {
  MultiSelectProps,
  MultiSelectHandle,
  ItemType,
  IconAdapterProps,
  RenderIconFn,
} from 'expo-react-native-multiple-select';

// Color pack (for matching component theme)
import { colorPack } from 'expo-react-native-multiple-select';

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT