Combobox
A popover with a searchable list, for picking one value or several.
Single selection
Compose Combobox.Root, a trigger, and Combobox.Content holding a Combobox.Command.
Combobox.Input filters the rows of Combobox.List as you type, and
Combobox.Empty shows when nothing matches. Mark the chosen row with a check in
end and close the popover in onSelect.
Inside a form, use fullSizeAndButtonWithChevronToTheRight with w-full for a
field-sized trigger, and fullWidth on the content so the list matches the
trigger's width.
Multiple selection
Combobox.ItemCheckbox adds a checkbox to the row and keeps the popover open
while you toggle. Hovering a row shows an only button; handle it with
onOnlyClick to select that row alone, or pass showOnlyButton={false} to hide it.
A controlled Combobox.Input with onClear and clearLabel shows a clear
button once there is a query. Put footer actions after the list behind a
Combobox.Separator alwaysRender, so the divider stays while the list is filtered.
Groups
Combobox.Group takes a heading. Search hides a group once none of its rows
match. Add the group name to each row's keywords so searching for the group
finds its rows.
Trigger variants
buttonWithChevron renders a compact button with a chevron that flips while
the list is open; pass mode="ghost" for an inline switcher in a header. Short
lists can skip the input; pass shouldFilter={false} to Combobox.Command when
there is nothing to filter. With asChild, any button opens the list, which suits
actions such as adding a person.
Usage
Search matches each row's value and keywords. When results come from the
server, pass shouldFilter={false} to Combobox.Command, control the input with
value and onValueChange, and render only the rows you get back. While they
load, set loading on Combobox.Input to swap the search icon for a spinner, or
render Combobox.Loading inside the list.
Combobox.Root is non-modal by default. Inside a drawer or a modal dialog it is
always modal, so a long list can still scroll.
Combobox.Item with href renders a link row; Enter and click both navigate.
For long lists, ComboboxVirtualList from
@repo/design-system/components/primitives/combobox/virtual-list renders only
the visible rows.
Combobox.Root Properties
Controlled open state of the popover
Initial open state when uncontrolled
Default: false
Called when the open state changes
Traps focus and blocks the page behind the list. Always true inside a drawer or a modal dialog
Default: false
Combobox.Trigger Properties
Merges the trigger behavior into its child element, such as a Button
Default: false
Renders a Button with a chevron that flips while the list is open
Default: false
Renders a field-style Button with a truncated label on the left and the chevron on the right
Default: false
Button variants only. Icon name, descriptor, or node before the label
Button variants only. Replaces the chevron
Button variants only. Hides the chevron
Default: false
Button variants only. buttonWithChevron defaults to small, the full-size variant to regular
Button variants only. Button style, such as ghost or dashed
Default: secondary
Button variants only. The full-size variant shows a spinner in place of the chevron and is disabled
Whether the trigger is disabled
Default: false
Full-size variant only. Classes for the label wrapper
Button variants only. Classes for the Button's inner content
Combobox.Content Properties
Minimum width of the popover in pixels
Default: 249
Uses the trigger's width as the minimum width instead of size
Default: false
Alignment of the popover relative to the trigger
Default: center
Preferred side of the trigger to render against
Default: bottom
Distance in pixels from the trigger
Default: 10
Offset in pixels along the alignment axis
Default: 0
Renders the popover in a portal. Set to false to render it in place
Default: true
Props for the portal, such as container
Fades the popover out on close. Turn off when picking an option shifts the layout underneath
Default: true
Combobox.Command Properties
Filters and sorts rows by the input's query. Set to false when you filter the rows yourself
Default: true
Custom ranking. Return 0 to hide a row, higher numbers to rank it first
Arrow keys wrap from the last row to the first
Default: true
Controlled value of the highlighted row
Called when the highlighted row changes
Accessible label for the command menu
Combobox.Input Properties
Placeholder text
Controlled query
Called when the query changes
Shows a spinner in place of the search icon
Default: false
Shows a clear button while value is not empty. Requires clearLabel
Accessible label for the clear button. Required with onClear
Classes for the row that holds the icon and the input
Combobox.List Properties
Maximum height before the list scrolls. Numbers are pixels; strings are any CSS length
Default: 300
Combobox.Item Properties
Unique value used for search and highlighting. Defaults to the row's text
Extra terms that match the row in search
Called when the row is clicked or chosen with Enter
Whether the row is disabled
Default: false
Icon name, descriptor, or node before the label
Icon name, descriptor, or node at the end of the row, such as a check for the chosen row
Renders the row as a link. Enter and click both navigate
With href. Forwarded to Next.js Link
Default: true
With href. Called as the row starts navigating in this tab
Turns off the tooltip that shows a truncated label in full
Default: false
Side of the truncated-label tooltip
Classes for the label wrapper
Combobox.ItemCheckbox Properties
Whether the row is checked
Called when the row is toggled
Shows an only button on hover
Default: true
Called when the only button is clicked
Locks the checkbox and explains why in a tooltip. The row stays interactive
Unique value used for search and highlighting
Extra terms that match the row in search
Whether the row is disabled
Default: false
Icon name, descriptor, or node between the checkbox and the label
Icon name, descriptor, or node after the label
Renders the label without truncation, for labels that own their layout
Default: false
Combobox.Group and Combobox.Separator Properties
Group only. Heading shown above the group's rows
Group only. Keeps the group rendered when search matches none of its rows
Default: false
Separator only. Keeps the separator while there is a query. Without it, separators hide during search
Default: false
Other Parts
Shown when search matches no row
Loading row for async results. Takes label and progress
Standalone heading outside a group. size defaults to small
Button styled like a row, for actions below the list
Link styled like a row, for navigation below the list