Picks one value from a long list by typing to filter it.
import { Combobox, Field } from "@usememos/ui";
const tags = ["book", "design", "travel"];
<Field.Root>
<Field.Label>Tag</Field.Label>
<Combobox.Root items={tags} value={tag} onValueChange={setTag}>
<Combobox.Input placeholder="Find a tag" />
<Combobox.Popup>
<Combobox.Empty>No tags found</Combobox.Empty>
<Combobox.List>
{(tag: string) => (
<Combobox.Item key={tag} value={tag}>{tag}</Combobox.Item>
)}
</Combobox.List>
</Combobox.Popup>
</Combobox.Root>
</Field.Root>Item icon accepts a Lucide element, an emoji in a span or a noninteractive identity mark. The decorative slot owns the icon square; children holds the label. Grid pickers keep their glyph in children. See Row anatomy.
| Part | Base UI part | Renders |
|---|---|---|
Combobox.Root |
Combobox.Root |
Nothing. Holds the value, the input text and a hidden input for forms. Takes size |
Combobox.Input |
Combobox.InputGroup, Input, Trigger |
An Input box: a search icon, the <input role="combobox"> and a chevron button that opens the list. Takes icon |
Combobox.Popup |
Combobox.Portal, Positioner, Popup |
The panel under the input, as wide as the input, portaled to the body |
Combobox.List |
Combobox.List |
The items, a <div role="listbox">. A function child renders each filtered item |
Combobox.Item |
Combobox.Item with ItemIndicator |
One option, with a check at the end when chosen. Takes icon |
Combobox.Empty |
Combobox.Empty |
The text shown when nothing matches. Stays mounted, so screen readers announce it |
Combobox.Group |
Combobox.Group |
A labeled set of items |
Combobox.GroupLabel |
Combobox.GroupLabel |
The name of a Group |
Combobox.Separator |
Combobox.Separator |
A line between groups |
Combobox.Row |
Combobox.Row |
One row of a grid, with grid on the root: square cells for icons or emoji |
Combobox.Collection |
Combobox.Collection |
Base UI's part, unstyled: renders one group's items from grouped items |
Combobox.useFilter |
Combobox.useFilter |
Base UI's hook: locale-aware contains, startsWith, endsWith for filter |
type Combobox.RootProps<Value, Multiple, Item> = BaseCombobox.Root.Props<Value, Multiple, Item> & {
size?: "sm" | "md";
};
interface Combobox.InputProps extends BaseCombobox.Input.Props {
icon?: IconElement | null; // default <Search />; null drops it
triggerLabel?: string; // the chevron's name outside a Field; default "Show options"
className?: string; // on the box, not the <input>
style?: React.CSSProperties; // on the box
}
interface Combobox.PopupProps extends BaseCombobox.Popup.Props {
side?: Side; align?: Align; // Positioner props; default side "bottom", align "start"
container?: HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null; // portal target
}
interface Combobox.ItemProps extends BaseCombobox.Item.Props {
icon?: IconElement;
}Base UI's props pass through: items, value, defaultValue, onValueChange, inputValue, onInputValueChange, filter, itemToStringLabel, isItemEqualToValue, open, onOpenChange, name, disabled, required on the root; placeholder, disabled on Input; value, disabled on Item.
-
Pass
itemsto the root and render them with a function child ofList. The root filters them as people type;Emptyneedsitemsto know when nothing matches. -
For object items, pass
itemToStringLabelso the input shows the label, and give each Item the object asvalue. -
Label it with a Field; the label names the input and the chevron. Outside a Field, give Input an
aria-label. -
Use it for more than about 10 options, or when people type to find one. For fewer, use Select.
-
Typing opens the list. Up and Down move the highlight, Enter picks, Escape closes; focus stays in the input.
-
Multi-select (chips) is not built.
-
With
inlineon the root, the list sits in the page instead of a popup: putInput,EmptyandListdirectly inside the root, with noPopup. The root is then open unless you passopen, and the Input drops its chevron. Use it for a picker inside a Popover or a Dialog. -
With
gridon the root, split the filtered items into rows of a fixed count and wrap each inCombobox.Row. Arrow keys then move across rows and columns, and Enter picks. Give each cell anaria-label. This is the icon and emoji picker:<Combobox.Root items={icons} inline grid value={icon} onValueChange={pick} inputValue={query} onInputValueChange={setQuery} itemToStringLabel={(item) => item.label}> <Combobox.Input placeholder="Find an icon" aria-label="Find an icon" /> <Combobox.Empty>No icons found</Combobox.Empty> <Combobox.List aria-label="Icons"> {rows(icons.filter((item) => contains(item.label, query)), 8).map((row, index) => ( <Combobox.Row key={index}> {row.map((item) => ( <Combobox.Item key={item.value} value={item} aria-label={item.label}>{item.icon}</Combobox.Item> ))} </Combobox.Row> ))} </Combobox.List> </Combobox.Root>
The rows are rendered by the app, so filter them with the same query: keep it in
inputValueandonInputValueChange, and match withuseFilter().contains.
- The box is an Input: flat
surface,edge, with no border or surface change under hover, focus or press. The caret or text selection indicates typing focus, without animation. The search icon and chevron aretext-secondary; the chevron turnstexton hover. Disabled text and both icons usetext-disabled. The chevron has a built-in Tooltip usingtriggerLabel. - List:
mu-popup, 6px padding, as wide as the input and at leastmenu-width. Rows follow Combobox's size: 28px at sm, 32px at md, highlight in the row's radius. The list is at mostlist-height(240px) tall, then it scrolls. - Rows are text weight 400; the highlighted row uses
hover; the chosen row has a check at the end. List items and group labels use 8px inline padding at both sizes, including when an item has a leading icon; the icon-to-label gap is 8px. Inline lists follow the same floating-list item contract; grid cells keep the square layout below. - Empty text:
bodyintext-secondary,space-3byspace-4padding. - Grid cells: square, a control height,
insetapart,row-radius; the highlighted cell useshover, the chosen cell sits in awelllike a pressed Toggle. No check. - Opening and closing use the shared Motion fade and
space-1offset overduration-fade. Both are immediate under reduced motion; input feedback and option highlighting never animate.