Forms

Combobox

A value picked from a long list you can search: a time zone, a category, a set of tags. Options come as data, in groups, with keywords that find them. It takes one value or several, can create what was typed, and marks an option picked for the person, such as by a model, so they confirm or change it. On the overlay surface, with the command palette's rows.

view .md

Preview

time zone418 zones. Try "tok" or "sao"

tagsseveral values; type a new one to create it

categoryone suggested, to confirm

Installation

terminal

bash

npx @entrepta/cli@latest add combobox

// Resolves dependencies, copies the source, and installs npm packages automatically.

Usage

combobox.tsx

tsx

import { Combobox } from "@/components/entrepta/combobox"

<Field id="zone" label="time zone">
  <Combobox
    options={[
      { value: "America/Sao_Paulo", label: "São Paulo", group: "Americas", keywords: ["brazil"] },
      { value: "Europe/Lisbon", label: "Lisbon", group: "Europe", hint: "UTC+1" },
    ]}
    value={zone}
    onValueChange={setZone}
    searchPlaceholder="Search time zones…"
    emptyText="No time zones match"
  />
</Field>

// several values, created on the spot
<Combobox
  aria-label="tags"
  multiple
  creatable
  onCreate={(label) => addTag(label)}   // returns the new value
  options={tags}
  value={chosen}
  onValueChange={setChosen}
/>

Props

Prop	Type	Default	Description
options	{ value; label; group?; hint?; keywords?; suggested?; disabled? }[]	-	The list. group is the heading an option sits under
value / onValueChange	string \| null, or string[] with multiple	-	Controlled. With multiple, each pick toggles and the list stays open
multiple	boolean	false	Several values, shown as two chips and a count
creatable / onCreate	boolean / (label: string) => string	-	Offer to create what was typed when nothing matches it; the returned value is selected
renderOption	(option) => ReactNode	-	The row's content, such as an IconTile and a name
emptyText, searchPlaceholder, createLabel, suggestedLabel	ReactNode, string, (query) => ReactNode, string	-	The words, for another language or a more precise message