Combobox·续
Search menu items
Enable filtering with data-bs-search="true" on the toggle. Add a search input and optional no-results message inside the .menu, before the items. Items are filtered by matching their textContent against the query.
<Example code={<button class="form-control combobox-toggle" type="button"
data-bs-toggle="combobox"
data-bs-name="country"
data-bs-placeholder="Select a country…"
data-bs-search="true">
<span class="combobox-value">Select a country…</span>
<svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
<div class="combobox-search">
<input type="text" class="form-control combobox-search-input" placeholder="Search…" autocomplete="off" aria-label="Search…">
</div>
<button class="menu-item" type="button" data-bs-value="us">United States</button>
<button class="menu-item" type="button" data-bs-value="uk">United Kingdom</button>
<button class="menu-item" type="button" data-bs-value="ca">Canada</button>
<button class="menu-item" type="button" data-bs-value="au">Australia</button>
<button class="menu-item" type="button" data-bs-value="de">Germany</button>
<button class="menu-item" type="button" data-bs-value="fr">France</button>
<button class="menu-item" type="button" data-bs-value="jp">Japan</button>
<button class="menu-item" type="button" data-bs-value="br">Brazil</button>
<button class="menu-item" type="button" data-bs-value="in">India</button>
<button class="menu-item" type="button" data-bs-value="mx">Mexico</button>
<div class="combobox-no-results d-none">No results found</div>
</div>} />
Groups
Use .menu-header elements to create labeled groups within the menu.
<Example code={<button class="form-control combobox-toggle" type="button"
data-bs-toggle="combobox"
data-bs-name="language"
data-bs-placeholder="Select a language…">
<span class="combobox-value">Select a language…</span>
<svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
<div class="menu-header">Frontend</div>
<button class="menu-item" type="button" data-bs-value="html">HTML</button>
<button class="menu-item" type="button" data-bs-value="css">CSS</button>
<button class="menu-item" type="button" data-bs-value="js">JavaScript</button>
<div class="menu-header">Backend</div>
<button class="menu-item" type="button" data-bs-value="python">Python</button>
<button class="menu-item" type="button" data-bs-value="ruby">Ruby</button>
<button class="menu-item" type="button" data-bs-value="go">Go</button>
</div>} />
Multiple select
Add data-bs-multiple="true" to the toggle 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.
<Example code={<button class="form-control combobox-toggle" type="button"
data-bs-toggle="combobox"
data-bs-name="skills"
data-bs-placeholder="Select skills…"
data-bs-multiple="true">
<span class="combobox-value">Select skills…</span>
<svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
<button class="menu-item" type="button" data-bs-value="html">
HTML
<svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
</button>
<button class="menu-item" type="button" data-bs-value="css">
CSS
<svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
</button>
<button class="menu-item" type="button" data-bs-value="js">
JavaScript
<svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
</button>
<button class="menu-item" type="button" data-bs-value="python">
Python
<svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
</button>
<button class="menu-item" type="button" data-bs-value="ruby">
Ruby
<svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
</button>
</div>} />
Sizing
Use .form-control-sm or .form-control-lg on the toggle button to change size.
<Example code={`<button class="form-control form-control-sm combobox-toggle" type="button" data-bs-toggle="combobox" data-bs-placeholder="Small select…"> <span class="combobox-value">Small select…</span> <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg> </button> <div class="menu"> <button class="menu-item" type="button" data-bs-value="1">Option one</button> <button class="menu-item" type="button" data-bs-value="2">Option two</button> </div>
<button class="form-control combobox-toggle" type="button" data-bs-toggle="combobox" data-bs-placeholder="Default select…"> <span class="combobox-value">Default select…</span> <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg> </button> <div class="menu"> <button class="menu-item" type="button" data-bs-value="1">Option one</button> <button class="menu-item" type="button" data-bs-value="2">Option two</button> </div>
<button class="form-control form-control-lg combobox-toggle" type="button" data-bs-toggle="combobox" data-bs-placeholder="Large select…"> <span class="combobox-value">Large select…</span> <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg> </button> <div class="menu"> <button class="menu-item" type="button" data-bs-value="1">Option one</button> <button class="menu-item" type="button" data-bs-value="2">Option two</button> </div>`} />
Disabled
Add disabled to the toggle button or individual menu items.
<Example code={`<button class="form-control combobox-toggle" type="button" data-bs-toggle="combobox" data-bs-placeholder="Cannot interact…" disabled> <span class="combobox-value">Cannot interact…</span> <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg> </button> <div class="menu"> <button class="menu-item" type="button" data-bs-value="1">Option one</button> <button class="menu-item" type="button" data-bs-value="2">Option two</button> </div>
<button class="form-control combobox-toggle mt-3" type="button" data-bs-toggle="combobox" data-bs-placeholder="Select an option…"> <span class="combobox-value">Select an option…</span> <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg> </button> <div class="menu"> <button class="menu-item" type="button" data-bs-value="1">Available</button> <button class="menu-item" type="button" data-bs-value="2" disabled>Unavailable</button> <button class="menu-item" type="button" data-bs-value="3">Available</button> </div>`} />
Form submission
The combobox creates a hidden <input> for form submission when data-bs-name is set on the toggle. The hidden input’s name matches the attribute value and its value updates whenever the selection changes.
<!-- What you write -->
<button class="form-control combobox-toggle" type="button"
data-bs-toggle="combobox"
data-bs-name="country">
...
</button>
<div class="menu">...</div>
<!-- What the JS creates (inserted before the toggle) -->
<input type="hidden" name="country" value="us">
For multiple selection, the hidden input value is a comma-separated list of selected values.
JavaScript
Via data attributes
| Attribute | Description |
|---|---|
data-bs-toggle="combobox" |
Initializes the combobox on the toggle button. |
data-bs-value |
On a .menu-item, the value submitted and shown when that option is selected. |
data-bs-search |
Enables the search/filter field inside the menu. |
data-bs-multiple |
Enables multi-select behavior. |
data-bs-name |
name of the auto-created hidden input for form submission. |
data-bs-placeholder |
Placeholder text shown in the toggle when nothing is selected. |
Dependencies
Options
Options can be passed via data attributes on the toggle button (e.g., data-bs-search="true") or as a config object when initializing via JavaScript.
| Name | Type | Default | Description |
|---|---|---|---|
multiple |
boolean | false |
Enable multi-select mode. Selections toggle and the menu stays open. |
name |
string | null | null |
Name for the auto-created hidden input. Also settable via data-bs-name. |
placeholder |
string | '' |
Placeholder text for the toggle. Also settable via data-bs-placeholder. |
search |
boolean | false |
Enable search input in the menu. Also settable via data-bs-search. |
searchNormalize |
boolean | false |
Normalize accented characters for search matching. |
placement |
string | 'bottom-start' |
Menu placement (uses Floating UI). |
offset |
array | [0, 2] |
Offset from the toggle [skidding, distance]. |
boundary |
string | element | 'clippingParents' |
Overflow boundary for the menu. |
Methods
| Method | Description |
|---|---|
toggle |
Toggles the menu. |
show |
Shows the menu. |
hide |
Hides the menu. |
dispose |
Destroys the combobox instance and removes the hidden input. |
getInstance |
Static method to get the combobox instance from a DOM element. |
getOrCreateInstance |
Static method to get or create a combobox instance. |
Events
Events are fired on the toggle button element.
| Event | Description |
|---|---|
show.bs.combobox |
Fires immediately when the show method is called. |
shown.bs.combobox |
Fires when the menu has been made visible. |
hide.bs.combobox |
Fires immediately when the hide method is called. |
hidden.bs.combobox |
Fires when the menu has been hidden. |
change.bs.combobox |
Fires when a selection is made. The event detail includes value and item. |
Accessibility
The combobox component follows WAI-ARIA combobox patterns:
- The toggle button has
aria-haspopup="listbox"andaria-expanded. - Each selectable item should have
role="option"andaria-selected. - Full keyboard navigation: Arrow keys, Home, End, Enter, Space, Escape, and Tab.
- Disabled items have the
disabledattribute andaria-disabled="true".
CSS custom properties
The combobox uses CSS custom properties prefixed with --combobox-* for the toggle, and inherits --menu-* properties from the Menu component for the menu overlay. See the source SCSS for the full list of available tokens.
