Skip to content
Porcelana

Combobox

Searchable select: type to filter options, pick with Enter, with an empty state.

Inputs

Example

Example.tsx
import { Combobox, Field } from "@porcelana/ui";

const rooms = [
  { value: "bedroom", label: "Bedroom" },
  { value: "kitchen", label: "Kitchen", keywords: ["cook"] },
  { value: "office", label: "Office" },
  { value: "terrace", label: "Terrace" },
  { value: "attic", label: "Attic", disabled: true }
];

export default function Example() {
  return (
    <div style={{ maxWidth: 360 }}>
      <Field label="Room">
        <Combobox options={rooms} placeholder="Pick a room" searchPlaceholder="Search rooms" />
      </Field>
    </div>
  );
}

Import

Import
import { Combobox } from "@porcelana/ui";
import "@porcelana/ui/styles.css"; // once, at your app root

Props

Generated from the TypeScript types. Standard HTML attributes are passed through and not listed.

Combobox

Searchable select. Trigger is a button (works with Field for labelling); the popup is a cmdk listbox with arrow-key navigation and type-to-filter.

PropTypeDefaultDescription
optionsrequiredComboboxOption[]–Options to choose from; disabled ones are skipped.
allowDeselectbooleantrueSelecting the active option again clears it. Default true.
aria-labelstring–Defines a string value that labels the current element. @see aria-labelledby.
defaultValuestring | nullnullInitial value when uncontrolled.
disabledboolean–Prevents interaction and dims the control.
emptyTextstringNo resultsShown when nothing matches the search.
idstring–Element id. Generated automatically when omitted.
onOpenChange((open: boolean) => void)–Called when the open state changes.
onValueChange((value: string | null) => void)–Called with the new value.
openboolean–Controlled open state. Use with onOpenChange.
placeholderstringSelect…Hint shown when there is no value.
searchLabelstringSearch optionsAccessible name of the search field inside the popup.
searchPlaceholderstringSearch…Placeholder of the search field.
type"button" | "submit" | "reset"–Button type (defaults to "button").
valuestring | null–Controlled value. Use with onValueChange.

Accessibility

  • The trigger is a combobox button; the popup is a cmdk listbox with arrow navigation.
  • Focus moves into the search field on open and returns to the trigger on close.
  • keywords add extra search terms per option.

Mobile

  • The list scrolls inside the popover (max half the screen height) without scrolling the page behind it.