react-multiple-select-container

A lightweight, zero-dependency React component for selecting multiple values — with built-in state management, search, chips, and keyboard support.

Why?

Handling <select multiple> natively is painful. This package gives you a production-ready multi-select dropdown that just works — controlled or uncontrolled, with search, select-all, max limits, and accessible markup out of the box.

Install

npm install react-multiple-select-container

Quick Start

import { MultiSelect } from "react-multiple-select-container";
import "react-multiple-select-container/styles.css";

const fruits = [
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Cherry", value: "cherry" },
  { label: "Mango", value: "mango" },
  { label: "Orange", value: "orange" },
];

function App() {
  return (
    <MultiSelect
      options={fruits}
      placeholder="Pick your fruits"
      onChange={(selected) => console.log(selected)}
    />
  );
}

That's it — the component manages its own state internally.

Controlled Mode

Need full control? Pass value and onChange:

import { useState } from "react";
import { MultiSelect } from "react-multiple-select-container";
import "react-multiple-select-container/styles.css";

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

  return (
    <MultiSelect
      options={fruits}
      value={selected}
      onChange={setSelected}
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | options | Option[] | required | Array of { label, value, disabled? } | | value | string[] | — | Selected values (controlled mode) | | defaultValue | string[] | [] | Initial values (uncontrolled mode) | | onChange | (values: string[]) => void | — | Callback on selection change | | placeholder | string | "Select..." | Placeholder text | | searchable | boolean | true | Show search input in dropdown | | searchPlaceholder | string | — | Search input placeholder (omit for none) | | selectAll | boolean | true | Show "Select All" option | | selectAllLabel | string | "Select All" | Label for select all | | maxSelections | number | — | Cap the number of selections | | disabled | boolean | false | Disable the component | | className | string | "" | Custom class on container | | showChips | boolean | true | Show chips (true) or count (false) | | closeOnSelect | boolean | false | Close dropdown after each pick |

useMultiSelect Hook

For custom UIs, use the hook directly:

import { useMultiSelect } from "react-multiple-select-container";

const options = [
  { label: "Red", value: "red" },
  { label: "Green", value: "green" },
  { label: "Blue", value: "blue" },
];

function CustomSelect() {
  const {
    selected,
    toggle,
    selectAll,
    clearAll,
    isSelected,
    selectedOptions,
  } = useMultiSelect(options);

  return (
    <div>
      <p>Selected: {selectedOptions.map((o) => o.label).join(", ")}</p>
      <button onClick={selectAll}>Select All</button>
      <button onClick={clearAll}>Clear</button>
      {options.map((opt) => (
        <label key={opt.value}>
          <input
            type="checkbox"
            checked={isSelected(opt.value)}
            onChange={() => toggle(opt.value)}
          />
          {opt.label}
        </label>
      ))}
    </div>
  );
}

Examples

With max selections

<MultiSelect
  options={fruits}
  maxSelections={3}
  placeholder="Pick up to 3"
/>

Compact count mode

<MultiSelect
  options={fruits}
  showChips={false}
  placeholder="Select items"
/>

Disabled options

const options = [
  { label: "Available", value: "a" },
  { label: "Sold Out", value: "b", disabled: true },
  { label: "In Stock", value: "c" },
];

<MultiSelect options={options} />

Styling

Import the default styles:

import "react-multiple-select-container/styles.css";

All classes are prefixed with rms- so they won't clash with your styles. Override any class to customize:

.rms-control {
  border-radius: 12px;
  border-color: #3b82f6;
}

.rms-chip {
  background: #dbeafe;
  color: #1d4ed8;
}

License

MIT