Combobox

Autocomplete input and command palette with a list of suggestions.

tsx

1
2
3
4
5
6
7
8
9
10
11<Combobox
  name="framework"
  value="next"
  options={[
    { value: "next", label: "Next.js" },
    { value: "sveltekit", label: "SvelteKit" },
    { value: "nuxt", label: "Nuxt.js" },
  ]}
  searchPlaceholder="Search…"
  noResultLabel="No results."
/>

Combobox is a searchable select. The trigger button shows the selected value; clicking it opens a popover with a search input and a filterable list of options. The selected value is written to a hidden input for form submission.

Compare with Select (native or custom dropdown without search). Use Combobox once the list goes past ~10 options, where search becomes necessary.

Installation

Terminal

$ bext ui add combobox

Copy and paste the following into src/components/ui/combobox.tsx.

combobox.tsx

1
2
3
4
5
6
7
8
9
10
11<Combobox
  name="framework"
  value="next"
  options={[
    { value: "next", label: "Next.js" },
    { value: "sveltekit", label: "SvelteKit" },
    { value: "nuxt", label: "Nuxt.js" },
  ]}
  searchPlaceholder="Search…"
  noResultLabel="No results."
/>

This component is interactive. Make sure the shared island is loaded (see Islands). It reacts to data-ui="combobox" hooks.

Usage

tsx

1
2
3
4
5
6
7
8
9
10
11
12
13import { Combobox } from "@bext-stack/ui/primitives"

<Combobox
  name="framework"
  value={value}
  options={[
    { value: "next", label: "Next.js" },
    { value: "sveltekit", label: "SvelteKit" },
    { value: "nuxt", label: "Nuxt.js" },
    { value: "remix", label: "Remix" },
  ]}
  placeholder="Choose a framework"
/>

Anatomy

<Combobox name="…" value={value} options={[...]} />
  ├── <input type="hidden" name value />
  ├── <button data-ui-cb-trigger>
  │   ├── <span>{label or placeholder}</span>
  │   └── <ChevronDown />
  └── <div data-ui-cb-pop>
      ├── <input data-ui-cb-search placeholder={searchPlaceholder} />
      └── <div data-ui-cb-list>
          └── <div data-ui-cb-item data-value>{label}</div> × N

API Reference

Combobox

Prop	Type	Default	Description
name	string	—	Name of the hidden input for form submission.
value	string	—	Selected value (matches options[].value).
options	ComboboxOption[]	—	List of { value, label, disabled? }.
placeholder	string	"Sélectionner…"	Trigger text when empty.
emptyLabel	string	"Aucune option."	Message shown when the list has no option at all.
searchPlaceholder	string	"Rechercher…"	Placeholder of the search field.
noResultLabel	string	"Aucun résultat."	Message shown when the search has no match.
required	boolean	—	Sets required on the hidden input.
disabled	boolean	—	Disables the trigger.
triggerWidth	string (utility)	"w-[240px]"	Width of the trigger button.

Data Attributes

Attributes you can target in custom CSS to override the style for each state.

Attribute	On	Values	Description
data-ui="combobox"	root	—	Root marker.
data-ui-cb-trigger	trigger button	—	Clicking opens or closes the popover.
data-ui-cb-search	input	—	Fuzzy-filter input: the island filters items by data-label.
data-ui-cb-item	each option	data-value data-label data-disabled?	Clicking sets the value and closes.
data-ui-cb-empty	div	hidden by default	Shown when no item matches.

Keyboard

Key	Action
`Enter / Space`	On a closed trigger: opens. On an item: selects and closes.
`Escape`	Closes the open popover.
`Typing`	Focus moves to the search input; typing filters in real time.

Accessibility

The trigger carries aria-haspopup="listbox" aria-expanded. The list carries role="listbox", items role="option".

The hidden input is a real form field, so native HTML5 validation (required) works.

Examples

Placeholder (empty)

tsx

<Combobox name="x" options={…} placeholder="Choose one" />

Try it live

Open in play

Edit this component live in the bext playground. The PRISM + signals version is the bext-native idiom: fine-grained reactivity, no virtual DOM.

src/app/page.tsx 2 files · signals · runs in your browser

import { signalsIsland } from "@bext-stack/framework/signals";
import Showcase from "../islands/Showcase";

// A combobox: a button opens a searchable list (open signal + <Show>).
// The query signal filters a computed <List>; selecting an option writes
// the `value` signal, closes the popover, and the button label updates.
export default function Page() {
  return (
    <main style="max-width:640px;margin:0 auto;padding:48px 20px;font-family:Inter,system-ui,sans-serif">
      <h1 style="letter-spacing:-0.02em;margin-bottom:4px">Combobox</h1>
      <p style="color:#64748b;margin-top:0">A searchable select: open, filter, choose; the value signal updates.</p>
      {signalsIsland("Showcase", Showcase, {})}
    </main>
  );
}

Pure PRISM + real bext signals: fine-grained, no re-render.

src/app/page.tsx 2 files · react · runs in your browser

import Combobox from "../components/Combobox";

export default function Page() {
  return (
    <main style={{ maxWidth: 560, margin: "0 auto", padding: "48px 20px", fontFamily: "Inter, system-ui, sans-serif" }}>
      <h1 style={{ letterSpacing: "-0.02em", marginBottom: 4 }}>Combobox</h1>
      <p style={{ color: "#64748b", marginTop: 0 }}>A button that opens a searchable list and sets the selected value.</p>
      <div style={{ marginTop: 20 }}><Combobox /></div>
    </main>
  );
}

The React idiom: same UI, for comparison.

← Collapsible Command →

On This Page