Loading...
Skip to main content

Combobox

A customizable select-like component built with markup-first HTML, powered by the Menu component for positioning and keyboard navigation.

Overview

The combobox component provides a styled select experience using a Combobox with ComboboxOption children — rendered as a toggle button paired with a menu overlay. Unlike traditional select enhancements, the combobox is markup-first: you declare the options as React children. The JavaScript handles show/hide, selection state, form submission via a hidden input, and keyboard navigation.

  • Full control over menu item content (icons, descriptions, badges, images — anything)
  • Live search/filtering
  • Check mark indicators for selected items
  • Single and multiple selection modes
  • Full keyboard navigation and accessibility
  • Form submission via auto-created hidden input

Example

Use Combobox with ComboboxOption children. Each selectable option needs a value prop.

<Combobox
name="option"
placeholder="Select an item…"
>
<ComboboxOption value="1">
Option one
</ComboboxOption>
<ComboboxOption value="2">
Option two
</ComboboxOption>
<ComboboxOption value="3">
Option three
</ComboboxOption>
</Combobox>

Placeholders

Set placeholder text with the placeholder prop. Combobox displays it when nothing is selected.

<Combobox
name="country"
placeholder="Pick a country…"
>
<ComboboxOption value="us">
United States
</ComboboxOption>
<ComboboxOption value="uk">
United Kingdom
</ComboboxOption>
<ComboboxOption value="ca">
Canada
</ComboboxOption>
</Combobox>

Pre-selected value

Set defaultValue on Combobox to pre-select an option, or use value and onChange for controlled selection. The toggle text updates automatically on initialization.

<Combobox
defaultValue="editor"
name="role"
placeholder="Choose a role…"
>
<ComboboxOption value="admin">
Admin
</ComboboxOption>
<ComboboxOption value="editor">
Editor
</ComboboxOption>
<ComboboxOption value="viewer">
Viewer
</ComboboxOption>
</Combobox>

With form field

Use the form field component to layout and wrap your combobox with a label, description, and validation feedback messages in a vertical stack.

<FormField>
<FormLabel htmlFor="exampleCombobox">
Combobox
</FormLabel>
<Combobox
id="exampleCombobox"
name="country"
placeholder="Pick a country…"
>
<ComboboxOption value="us">
United States
</ComboboxOption>
<ComboboxOption value="uk">
United Kingdom
</ComboboxOption>
<ComboboxOption value="ca">
Canada
</ComboboxOption>
</Combobox>
</FormField>

Custom content

Since menu items are standard HTML, you can put anything inside them — SVG icons, images, description text, badges, or any other markup.

Icons

Set icon on ComboboxOption for a leading icon, rendered with the library’s Icon component.

<Combobox
name="language"
placeholder="Choose a language…"
>
<ComboboxOption
icon="file-earmark-code"
value="html"
>
HTML
</ComboboxOption>
<ComboboxOption
icon="file-earmark-code"
value="css"
>
CSS
</ComboboxOption>
<ComboboxOption
icon="file-earmark-code"
value="js"
>
JavaScript
</ComboboxOption>
</Combobox>

Descriptions

Use the description prop on ComboboxOption for secondary text. The component supplies the flex column layout.

<Combobox
name="role"
placeholder="Select a role…"
>
<ComboboxOption
description="Full access to all resources"
value="admin"
>
Admin
</ComboboxOption>
<ComboboxOption
description="Can edit and publish content"
value="editor"
>
Editor
</ComboboxOption>
<ComboboxOption
description="Read-only access"
value="viewer"
>
Viewer
</ComboboxOption>
</Combobox>

Checked icon

Set checkedIcon on each ComboboxOption to show a check mark indicator. It is hidden by default and becomes visible when the option is selected.

<Combobox
defaultValue="active"
name="status"
placeholder="Choose a status…"
>
<ComboboxOption
checkedIcon
description="Visible to users"
value="active"
>
Active
</ComboboxOption>
<ComboboxOption
checkedIcon
description="Not yet published"
value="draft"
>
Draft
</ComboboxOption>
<MenuDivider />
<ComboboxOption
checkedIcon
value="archived"
>
Archived
</ComboboxOption>
</Combobox>

All together

Combine all three for a rich menu item layout.

<Combobox
name="priority"
placeholder="Set priority…"
>
<ComboboxOption
checkedIcon
description="No rush"
icon="file-earmark-code"
value="low"
>
Low
</ComboboxOption>
<ComboboxOption
checkedIcon
description="Normal priority"
icon="file-earmark-code"
value="medium"
>
Medium
</ComboboxOption>
<ComboboxOption
checkedIcon
description="Needs attention"
icon="file-earmark-code"
value="high"
>
High
</ComboboxOption>
</Combobox>

Search menu items

Enable filtering with search. The component adds a search input and no-results message before the items; customize them with searchPlaceholder and noResultsText. Items are filtered by matching their textContent against the query.

<Combobox
name="country"
placeholder="Select a country…"
search
>
<ComboboxOption value="us">
United States
</ComboboxOption>
<ComboboxOption value="uk">
United Kingdom
</ComboboxOption>
<ComboboxOption value="ca">
Canada
</ComboboxOption>
<ComboboxOption value="au">
Australia
</ComboboxOption>
<ComboboxOption value="de">
Germany
</ComboboxOption>
<ComboboxOption value="fr">
France
</ComboboxOption>
<ComboboxOption value="jp">
Japan
</ComboboxOption>
<ComboboxOption value="br">
Brazil
</ComboboxOption>
<ComboboxOption value="in">
India
</ComboboxOption>
<ComboboxOption value="mx">
Mexico
</ComboboxOption>
</Combobox>

Groups

Use ComboboxGroup with a label to create labeled groups within the menu.

<Combobox
name="language"
placeholder="Select a language…"
>
<ComboboxGroup label="Frontend">
<ComboboxOption value="html">
HTML
</ComboboxOption>
<ComboboxOption value="css">
CSS
</ComboboxOption>
<ComboboxOption value="js">
JavaScript
</ComboboxOption>
</ComboboxGroup>
<ComboboxGroup label="Backend">
<ComboboxOption value="python">
Python
</ComboboxOption>
<ComboboxOption value="ruby">
Ruby
</ComboboxOption>
<ComboboxOption value="go">
Go
</ComboboxOption>
</ComboboxGroup>
</Combobox>

Multiple select

Set multiple for multi-select behavior. Selected items are toggled on click and the menu stays open. The toggle displays the count when more than one item is selected.

<Combobox
multiple
name="skills"
placeholder="Select skills…"
>
<ComboboxOption
checkedIcon
value="html"
>
HTML
</ComboboxOption>
<ComboboxOption
checkedIcon
value="css"
>
CSS
</ComboboxOption>
<ComboboxOption
checkedIcon
value="js"
>
JavaScript
</ComboboxOption>
<ComboboxOption
checkedIcon
value="python"
>
Python
</ComboboxOption>
<ComboboxOption
checkedIcon
value="ruby"
>
Ruby
</ComboboxOption>
</Combobox>

Sizing

Use controlSize="sm" or controlSize="lg" to change the toggle button’s size.

<>
<Combobox
controlSize="sm"
name="option"
placeholder="Small select…"
>
<ComboboxOption value="1">
Option one
</ComboboxOption>
<ComboboxOption value="2">
Option two
</ComboboxOption>
</Combobox>
<Combobox
name="option"
placeholder="Default select…"
>
<ComboboxOption value="1">
Option one
</ComboboxOption>
<ComboboxOption value="2">
Option two
</ComboboxOption>
</Combobox>
<Combobox
controlSize="lg"
name="option"
placeholder="Large select…"
>
<ComboboxOption value="1">
Option one
</ComboboxOption>
<ComboboxOption value="2">
Option two
</ComboboxOption>
</Combobox>
</>

Disabled

Add disabled to the toggle button or individual menu items.

<>
<Combobox
disabled
name="option"
placeholder="Cannot interact…"
>
<ComboboxOption value="1">
Option one
</ComboboxOption>
<ComboboxOption value="2">
Option two
</ComboboxOption>
</Combobox>
<Combobox
className="mt-3"
name="option"
placeholder="Select an option…"
>
<ComboboxOption value="1">
Available
</ComboboxOption>
<ComboboxOption
disabled
value="2"
>
Unavailable
</ComboboxOption>
<ComboboxOption value="3">
Available
</ComboboxOption>
</Combobox>
</>

Form submission

For form submission, Combobox creates a hidden input whose name matches the required name prop and whose value updates whenever the selection changes.

<Combobox name="country" defaultValue="us">
<ComboboxOption value="us">United States</ComboboxOption>
<ComboboxOption value="ca">Canada</ComboboxOption>
</Combobox>

For multiple selection, the component creates one hidden input per selected value, all sharing the same name. Read these values with FormData.getAll(name).

Usage

Combobox manages selection with defaultValue, or value and onChange for controlled state. Pass search, searchNormalize, multiple, and sizing options as props; no plugin initialization is needed.

Options

Pass options directly as Combobox props. The wrapper manages the menu and form inputs.

NameTypeDefaultDescription
multiplebooleanfalseEnable multi-select mode. Selections toggle and the menu stays open.
namestringRequiredName for the auto-created hidden inputs.
placeholderstring''Placeholder text for the toggle.
searchbooleanfalseEnable search input in the menu.
searchNormalizebooleanfalseNormalize accented characters for search matching.

Accessibility

The combobox component follows WAI-ARIA combobox patterns:

  • The toggle button has aria-haspopup="listbox" and aria-expanded.
  • Each ComboboxOption receives role="option" and aria-selected automatically.
  • Full keyboard navigation: Arrow keys, Home, End, Enter, Space, Escape, and Tab.
  • Disabled items have the disabled attribute and aria-disabled="true".

CSS custom properties

The combobox uses CSS custom properties prefixed with --bs-combobox-* for the toggle, and inherits --bs-menu-* properties from the Menu component for the menu overlay. See the upstream variable definitions for the full list of available tokens.

Documentation navigation
On this page
On this page