Combobox
Searchable select: type to filter options, pick with Enter, with an empty state.
Example
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 { Combobox } from "@porcelana/ui";
import "@porcelana/ui/styles.css"; // once, at your app rootProps
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.
| Prop | Type | Default | Description |
|---|---|---|---|
optionsrequired | ComboboxOption[] | – | Options to choose from; disabled ones are skipped. |
allowDeselect | boolean | true | Selecting the active option again clears it. Default true. |
aria-label | string | – | Defines a string value that labels the current element. @see aria-labelledby. |
defaultValue | string | null | null | Initial value when uncontrolled. |
disabled | boolean | – | Prevents interaction and dims the control. |
emptyText | string | No results | Shown when nothing matches the search. |
id | string | – | 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. |
open | boolean | – | Controlled open state. Use with onOpenChange. |
placeholder | string | Select… | Hint shown when there is no value. |
searchLabel | string | Search options | Accessible name of the search field inside the popup. |
searchPlaceholder | string | Search… | Placeholder of the search field. |
type | "button" | "submit" | "reset" | – | Button type (defaults to "button"). |
value | string | 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.