react-native-searchable-multiselect

A searchable, tag-style multi-select input for React Native. Type to filter existing options, tap to select/deselect, and optionally create new color-tagged options inline — all with a fully controlled, headless-friendly API (no Redux or navigation dependency baked in).

Author: Neeraj Singh

Install

npm install react-native-searchable-multiselect
# or
yarn add react-native-searchable-multiselect

No extra native linking is required — it's pure JS/TSX on top of react-native core components.

Basic usage

import React, { useState } from "react";
import { View } from "react-native";
import { MultiSelect, OptionItem } from "react-native-searchable-multiselect";

const initialOptions: OptionItem[] = [
  { label: "Design", value: "1", color: "#60A5FA" },
  { label: "Engineering", value: "2", color: "#4ADE80" },
];

export default function Example() {
  const [options, setOptions] = useState(initialOptions);
  const [selected, setSelected] = useState<string[]>([]);

  return (
    <View style={{ padding: 16 }}>
      <MultiSelect
        label="Tags"
        required
        options={options}
        setOptions={setOptions}
        selected={selected}
        onChange={setSelected}
      />
    </View>
  );
}

Creating options against your backend

Pass onCreateOption to persist new tags remotely (e.g. via Redux, an API call, React Query, etc). Return the created OptionItem (or a promise that resolves to one); return null/undefined to abort.

<MultiSelect
  options={options}
  setOptions={setOptions}
  selected={selected}
  onChange={setSelected}
  onCreateOption={async (label, color) => {
    const res = await api.createTag({ name: label, color });
    return { label, value: res.id.toString(), color };
  }}
  onCreateError={(msg) => Toast.show(msg)} // e.g. "Please select a color"
/>

Custom icons & theme

<MultiSelect
  options={options}
  selected={selected}
  onChange={setSelected}
  icons={{
    dropdown: require("./assets/dropdown.png"),
    close: require("./assets/close.png"),
    plus: require("./assets/plus.png"),
    empty: require("./assets/empty.png"),
  }}
  theme={{
    primary: "#EC4899",
    colorPalette: ["#F87171", "#4ADE80", "#60A5FA"],
  }}
/>

If icons are omitted, lightweight text glyphs (▼ / × / ✓) are used instead, so the component works out of the box with zero asset setup. A starter icon set (check.png, close.png, dropdown.png) is bundled under src/assets/ if you'd like a visual starting point — copy/replace them with your own app's icon style as needed.

Exports

• MultiSelect — the main component (default export from src/MultiSelect)
• RequiredWrapper — small helper wrapper used by the component
• DEFAULT_COLOR_PALETTE, DEFAULT_THEME — theme helpers from src/theme
• createStyles — style factory from src/styles
• Type exports: OptionItem, MultiSelectProps, MultiSelectTheme, MultiSelectIcons, CreateOptionResult

Props

| Prop | Type | Default | Description | |---|---|---|---| | options | OptionItem[] | — | Full list of selectable options | | setOptions | Dispatch<SetStateAction<OptionItem[]>> | — | Called when a new option is created | | selected | string[] | — | Selected option values (controlled) | | onChange | (selected: string[]) => void | — | Fires on select/deselect/create | | label | string | — | Field label | | required | boolean | false | Shows validation styling | | showError | boolean | false | Shows the "required" error message | | placeholder | string | "Select or Create" | Closed-state placeholder | | searchPlaceholder | string | "Search or create" | Open-state input placeholder | | allowCreate | boolean | true | Enables the inline "create new" flow | | onCreateOption | (label, color) => Promise<OptionItem \| null> \| OptionItem \| null | — | Persist a new option | | onCreateError | (message: string) => void | — | Validation callback (e.g. no color chosen) | | icons | MultiSelectIcons | text glyphs | Override dropdown/empty/plus icons | | theme | MultiSelectTheme | see theme.ts | Colors + create-color palette | | emptyText | string | "No results found" | Empty state text | | createButtonText | string | "Create New" | Create button label |

License

MIT