Multi Select React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Multi Select is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import MultiSelect from @/components/ui/multi-select.

import { useState } from "react"
import { Car, Building2, Smartphone, Dumbbell } from "lucide-react"
import { MultiSelect, type MultiSelectOption } from "@/components/ui/multi-select"

const CATEGORIES: MultiSelectOption[] = [
  { value: "real-estate", label: "Real estate", icon: <Building2 /> },
  { value: "vehicles", label: "Vehicles", icon: <Car /> },
  { value: "electronics", label: "Electronics", icon: <Smartphone /> },
  { value: "sports", label: "Sports", icon: <Dumbbell /> },
]

export function FollowedCategories() {
  const [categories, setCategories] = useState<string[]>(["vehicles"])
  return (
    <MultiSelect
      label="Followed categories"
      placeholder="Pick categories"
      options={CATEGORIES}
      value={categories}
      onValueChange={setCategories}
      maxSelected={3}
      selectAll
      name="categories"
      labels={{
        selected: (n) => `${n} picked`,
        limit: (n, max) => `${n} of ${max} picked`,
      }}
    />
  )
}

Props

• options*
  MultiSelectItems

  Options and groups: { value, label, description?, icon?, badge?, disabled?, keywords?, textValue? } or { label, items }. The icon also shows inside the chip.

• value
  string[]

  The chosen values, controlled. Values not among the options keep their chips (labels from the cache, else the value).

• defaultValue
  string[]

  The starting values while uncontrolled (empty when omitted). A form reset returns to them.

• onValueChange
  (value: string[]) => void

  Called with the new values after a toggle, a chip removal, select all, clear, or Done in the phone sheet.

• labeldefault ""
  ReactNode

  The field label. A click focuses the trigger; plain text also titles the phone sheet and names the trigger with the count.

• descriptiondefault ""
  ReactNode

  Helper text under the field, linked with aria-describedby.

• errordefault ""
  ReactNode

  Replaces the description with an animated error and marks the field invalid.

• requireddefault false
  boolean

  The red mark after the label, aria-required on the trigger; with name an empty field blocks the form submit.

• invaliddefault false
  boolean

  The invalid look and aria-invalid without a message.

• disableddefault false
  boolean

  Dims the field, never opens, chips are not removable and nothing is submitted.

• readOnlydefault false
  boolean

  The chips stay visible and the field focusable, but it never opens and nothing can be removed or cleared.

• placeholderdefault "Select options"
  string

  Shown in the field while nothing is chosen.

• displaydefault "chips"
  "chips" | "count" | "text"

  How the value shows in the field: chips; "3 selected"; or the names joined and truncated.

• maxVisibleChipsdefault 0
  number

  At most this many chips, then +N. 0 shows as many as fit on one line, measured on resize.

• wrapdefault false
  boolean

  Chips wrap onto more lines and the field grows instead of collapsing into +N.

• chipRemovabledefault true
  boolean

  Each chip has an x that removes it without opening the list; Backspace on the field removes the last one.

• showChipIconsdefault true
  boolean

  The option's icon (an avatar, a flag) inside its chip.

• maxSelecteddefault 0
  number

  The most options that can be chosen; at the limit the other rows turn disabled. 0 means no limit.

• selectAlldefault false
  boolean

  A "Select all" row on top that toggles every visible option (respecting maxSelected).

• clearabledefault true
  boolean

  An x at the end of the field that clears everything while something is chosen.

• closeOnSelectdefault false
  boolean

  Closes the popover after every pick. The phone sheet always waits for Done.

• searchdefault "auto"
  "auto" | "always" | "never"

  The search row: auto shows it above 8 options, with loadOptions or with creatable.

• searchPlaceholderdefault "Search…"
  string

  The search row's placeholder.

• emptyTextdefault "No results"
  string

  Shown when the search matches nothing (or there are no options).

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The chips, the checkboxes and the sheet's Done button.

• colordefault ""
  string

  Any CSS color for the chips and checkboxes; replaces the tone. Leave empty to use the tone.

• loadingdefault false
  boolean

  Options are on their way: a spinner replaces the chevron and the list shows a loading row.

• loadingTextdefault "Loading…"
  string

  The loading row's text and the spinner's accessible name.

• highlightMatchesdefault true
  boolean

  Bold matched letters while searching.

• leftIcon
  ReactNode

  A leading icon in the field.

• sizedefault "md"
  "sm" | "md" | "lg"

  32 / 40 / 48px (md grows to 44px on touch) with 20 / 24 / 28px chips, 16px text on phones.

• variantdefault "soft"
  "soft" | "outline" | "underline" | "ghost"

  The field look, the same as every other field.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner radius, scaled per size like the button; full also makes the chips pills. Ignored by underline.

• namedefault ""
  string

  Renders one hidden input per value with this name, so FormData.getAll(name), required and form reset work.

• id
  string

  The trigger's id (useId() by default); the label points at it.

• fieldProps
  Partial<FieldProps>

  Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.

• defaultOpendefault false
  boolean

  Starts with the list (or the sheet) open. Pass open and onOpenChange to control it.

• open
  boolean

  Whether the list is open, controlled. It never opens while disabled or readOnly.

• onOpenChange
  (open: boolean) => void

  Called when the list opens or closes.

• responsivedefault true
  boolean

  A bottom sheet with 48px checkbox rows and a Done button below 768px instead of the popover.

• sheetTitledefault ""
  string

  The phone sheet's title. Empty uses the label's text, else aria-label, else the placeholder.

• sidedefault "bottom"
  "top" | "right" | "bottom" | "left"

  Where the list opens; it flips when there is no room.

• aligndefault "start"
  "start" | "center" | "end"

  How the list lines up with the field.

• maxHeightdefault 360
  number

  The list's maximum height in px (search and footer included), capped by the room on screen.

• virtualThresholddefault 100
  number

  Above this many visible options only the rows in view render.

• loadOptions
  (query: string, context: { signal: AbortSignal }) => Promise<MultiSelectItems>

  Async options for the debounced query; the previous request is aborted and results are cached per query.

• debouncedefault 250
  number

  ms to wait after typing before loadOptions runs.

• minQueryLengthdefault 0
  number

  loadOptions waits for this many characters.

• creatabledefault false
  boolean

  A create row when the query matches nothing exactly; pair it with onCreate.

• onCreate
  (query: string) => (string | void | Promise<string | void>)

  Creates an option from the query; a returned value is selected.

• createLabel
  (query: string) => ReactNode

  The create row's text (default: Create "query").

• filter
  boolean, or (option: MultiSelectOption, query: string) => score (number, null hides)

  Default true: true filters with text-match; false means the options are already filtered; a function scores (null hides).

• fuzzydefault false
  boolean

  Fuzzy matching for the search.

• renderOption
  (option, state: { selected, highlighted, disabled, ranges }) => ReactNode

  Replaces a row's content; the row element, its checkbox, aria and classes stay.

• container
  HTMLElement | null

  Where the list or the sheet is portaled (document.body by default).

• labels
  Partial<MultiSelectLabels>

  Every string: { selectAll, clearAll, done, selected(n), limit(n, max), more(n), remove(label), results(n), clearSearch, retry }. Defaults: "Select all", "Clear all", "Done", "3 selected", "2 of 3 selected", "+3", "Remove Auto", the announced result count, the search clear button and the retry button.

• classNames
  Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "trigger" | "icon" | "chips" | "chip" | "overflow" | "placeholder" | "summary" | "clear" | "chevron" | "content" | "search" | "list" | "item" | "group" | "empty" | "footer", string>>

  Extra classes for the inner parts. box is the field box, trigger the button covering it, content the popover (or the sheet).

• className
  string

  Merged onto the Field root when there is a label, description or error, otherwise onto the box.

• ref
  RefObject<HTMLButtonElement | null> or (node) => void

  The trigger button; other props (onBlur, aria-*, data-*, form) go there too.

FAQ

Used in

More React input components