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={&lt;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"> &lt;span class="combobox-value">Select a country…&lt;/span> &lt;svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg">&lt;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"/>&lt;/svg> &lt;/button> &lt;div class="menu"> &lt;div class="combobox-search"> &lt;input type="text" class="form-control combobox-search-input" placeholder="Search…" autocomplete="off" aria-label="Search…"> &lt;/div> &lt;button class="menu-item" type="button" data-bs-value="us">United States&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="uk">United Kingdom&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="ca">Canada&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="au">Australia&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="de">Germany&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="fr">France&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="jp">Japan&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="br">Brazil&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="in">India&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="mx">Mexico&lt;/button> &lt;div class="combobox-no-results d-none">No results found&lt;/div> &lt;/div>} />

Groups

Use .menu-header elements to create labeled groups within the menu.

<Example code={&lt;button class="form-control combobox-toggle" type="button" data-bs-toggle="combobox" data-bs-name="language" data-bs-placeholder="Select a language…"> &lt;span class="combobox-value">Select a language…&lt;/span> &lt;svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg">&lt;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"/>&lt;/svg> &lt;/button> &lt;div class="menu"> &lt;div class="menu-header">Frontend&lt;/div> &lt;button class="menu-item" type="button" data-bs-value="html">HTML&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="css">CSS&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="js">JavaScript&lt;/button> &lt;div class="menu-header">Backend&lt;/div> &lt;button class="menu-item" type="button" data-bs-value="python">Python&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="ruby">Ruby&lt;/button> &lt;button class="menu-item" type="button" data-bs-value="go">Go&lt;/button> &lt;/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={&lt;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"> &lt;span class="combobox-value">Select skills…&lt;/span> &lt;svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg">&lt;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"/>&lt;/svg> &lt;/button> &lt;div class="menu"> &lt;button class="menu-item" type="button" data-bs-value="html"> HTML &lt;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">&lt;path d="m2 7 4 5 8-8"/>&lt;/svg> &lt;/button> &lt;button class="menu-item" type="button" data-bs-value="css"> CSS &lt;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">&lt;path d="m2 7 4 5 8-8"/>&lt;/svg> &lt;/button> &lt;button class="menu-item" type="button" data-bs-value="js"> JavaScript &lt;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">&lt;path d="m2 7 4 5 8-8"/>&lt;/svg> &lt;/button> &lt;button class="menu-item" type="button" data-bs-value="python"> Python &lt;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">&lt;path d="m2 7 4 5 8-8"/>&lt;/svg> &lt;/button> &lt;button class="menu-item" type="button" data-bs-value="ruby"> Ruby &lt;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">&lt;path d="m2 7 4 5 8-8"/>&lt;/svg> &lt;/button> &lt;/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" and aria-expanded.
  • Each selectable item should have role="option" and aria-selected.
  • 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 --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.