# Bootstrap 6 Combobox > A select-like control written as markup: a form-control toggle next to a popup list box. The plugin runs the open state, the selection, the keyboard and form submission, and leaves the content of every option to you. ## Overview A combobox is a ` ``` ### Pre-selected value Set `value` — `data-coreui-value` on the toggle — and that option starts selected: the toggle reads its label from the moment the page loads. It takes an array in `multiple` mode. A `.selected` class on an option in the markup does not select it; the combobox writes that class from its value. ```html ``` ### With form field Wrap the control in [`.form-field`](https://coreui.io/bootstrap/docs/forms/field/) to lay it out with its label and description, and to get validation feedback in the right place. ```html

Country

We ship to these three for now.

``` ## Custom content An option is an ordinary element, so it takes whatever markup belongs there. The toggle shows its text: `.list-box-option-label` when there is one, the option's own text otherwise — so an option with an icon and a description still reads as one word in the closed control. ### Icons ```html ``` ### Descriptions Wrap the name in `.list-box-option-label` and the second line in `.list-box-option-description`. The toggle shows the label alone. ```html ``` ### Checkbox indicator Nothing marks the selection on its own — `aria-selected` and the `.selected` background carry it. `indicator: "checkbox"` puts a checkbox in front of every option and keeps it in step with the selection. It is a decorative ``, not an input, so it never takes the focus and never announces a second control per option. ```html ``` ### All together ```html ``` ## Search `search` puts the List box's own search field at the top of the panel and hides what does not match. Because a hidden option leaves the navigation, everything downstream follows: the arrows skip it and the empty state appears when nothing is left. The focus moves into the field when the panel opens, and `aria-activedescendant` moves there with it, so typing and choosing happen in one place. The field is a `.form-control.list-box-search` carrying `data-coreui-list-box-search`; put one in the panel yourself and it is used as it is, wherever you placed it. `searchPlaceholder` fills its placeholder and `ariaSearchLabel` its accessible name. ```html ``` The panel is as tall as its content — cap it where you want a scroll container, with `max-height` and `overflow-y` on `.list-box-options`, as above. ### Matching past the accents `searchNormalize` compares both sides without their diacritics, so `zoe` finds `Zoë` and `oe` finds both. It normalizes to `NFD` and drops the combining diacritics, which leaves the labels themselves untouched — only the comparison changes. ```html ``` ### External search `search: "external"` builds the same field and filters nothing. Every keystroke fires `search.coreui.combobox` with the `query`, and you answer with `setItems()` — the list shows what you hand it, so the query is yours to interpret. The value the user picked stays while the results change, and the toggle keeps its label when the next answer does not carry it. ## Groups Group options in a `.list-box-section` and name it with a `.list-box-section-label`. The plugin adds `role="group"`; point `aria-labelledby` at the label so the group is announced with its name. A section whose options are all filtered out is hidden with its label. ```html ``` ## Multiple select `multiple` toggles options instead of replacing the selection, and the panel stays open so several picks cost one opening. The toggle shows the one label while a single option is selected and `selectedLabel` past that — a function of the count and the number of options, or a string in which `{count}` and `{total}` are replaced. A selected value the list no longer carries, after an external search answer, counts in `{total}` as well, so the total never drops below the count. `selectionLimit` caps how many can be taken at once. ```html ``` ## Sizing The toggle carries `.form-control`, so `.form-control-sm` and `.form-control-lg` reach it unchanged and it stands exactly as tall as a text input of the same size. ```html ``` ## Disabled Set `data-coreui-disabled="true"` (or the `disabled` option) to turn the whole control off: the panel never opens, the list box is disabled with it, and a button toggle gets the `disabled` attribute. A single option opts out with `.disabled` and `aria-disabled="true"`, which takes it out of the keyboard order and out of every selection method. ```html ``` ## Form submission The plugin inserts a hidden ``, and like a ` ``` In `multiple` mode three selections post `country=us&country=uk&country=ca`, so read them on the server as a list. With nothing selected a single combobox posts `country=`, as a native select with an empty first option does, and a `multiple` one posts nothing, as a `` takes part in the browser's validation, so `required` blocks the submit while nothing is selected. When a validation reports it, the plugin lays it along the start of the toggle, so the browser shows its message under the combobox, and the focus it gets goes to the toggle. The state shows on the toggle as the `.is-*` class, and the message that follows the toggle is added to its `aria-describedby` while the state is `'invalid'`. ```html ``` The state comes from four places, in this order: - The `validationState` option: `'valid'`, `'invalid'` or a state you added to `$form-validation-states`. - An `.is-invalid` or `.is-valid` class written on the toggle in the markup, for example by a server that has already checked the value. It is read once, when the component starts. - A validation that reports the hidden select invalid: a submit, `checkValidity()` or `reportValidity()`, which the form plugin and the [stepper](https://coreui.io/bootstrap/docs/forms/stepper/) call as well. From then on the toggle shows it invalid whenever the value is invalid, until a native reset of the form. - In a form with `data-coreui-validate`, the `:user-invalid` state of the hidden select, and with `data-coreui-validate="valid"` also its `:user-valid` state. A state you give, with the option or with the class, is a verdict on the value it was given for, so the next change of the value the user makes in the list drops it; picking the option a single combobox already holds keeps it. What your code does in a `change.coreui.combobox`, `input` or `change` listener while the pick runs counts as your change, so a state you give there stays, and a change through `setValue()`, `clear()` or `setItems()` keeps the state. To set it again, call `setValidationState()`: it updates the state without rebuilding the combobox, replaces a class written on the toggle, so `setValidationState(null)` withdraws that class. While the given state is `'invalid'`, the select blocks the submit with the text of the linked message, or `Invalid value.` when there is none; a disabled combobox does not block. A native reset of the form puts back the value the combobox started with and drops a state given before it; a state you give from a `reset` listener on the form, or right after `form.reset()`, stays. A message placed where the stylesheet does not show it for the toggle can be named in `data-coreui-invalid-feedback` on the toggle. The toggle is a ` ``` ### Via JavaScript ```js const combobox = new coreui.Combobox('#myCombobox', { name: 'country', placeholder: 'Pick a country…', search: true }) ``` With no panel in the markup, `items` builds one — the same array a [List box](https://coreui.io/bootstrap/docs/components/list-box/) takes: ```js const combobox = new coreui.Combobox('#myCombobox', { items: [ { value: 'us', label: 'United States' }, { label: 'Europe', items: [{ value: 'uk', label: 'United Kingdom' }] } ] }) ``` A combobox whose list depends on another field, such as the cities of the chosen country, sets `resetSelectionOnItemsChange: true`: `setItems()` with different values then drops the value and takes the item marked `selected`. Leave it off with `search: 'external'`, where every answer brings different values and would drop the pick. ### Options | Name | Type | Default | Description | | --- | --- | --- | --- | | `allowList` | object | [Default value](https://coreui.io/bootstrap/docs/getting-started/javascript/#sanitizer) | Object which contains allowed attributes and tags for the labels rendered from `items`. | | `ariaSearchLabel` | string | `'Search options'` | Accessible name of the search field. An input with its own `aria-label` keeps it. | | `caretIcon` | string | `'`; leave it alone and the panel goes next to the toggle unless an ancestor would clip it. Inside a modal dialog it goes into the dialog instead, because the rest of the page is inert. | | `disabled` | boolean | `false` | Turns the control off: the panel never opens and the list box is disabled. The combobox sets the `.disabled` class and, on a button toggle, the `disabled` attribute from it. | | `html` | boolean | `false` | Parses the labels rendered from `items` as HTML instead of inserting them as text. | | `indicator` | string | `'none'` | `'checkbox'` puts a decorative checkbox in front of every option. | | `items` | array | `[]` | The options to render: `{ value, label, description, disabled, selected }`, or `{ label, items, disabled }` for a section, where `disabled: true` disables every item in it. Replaces whatever the panel already holds. | | `multiple` | boolean | `false` | Toggles options instead of replacing the selection, and keeps the panel open. | | `name` | string, null | `null` | Name of the hidden select the value is submitted under, inserted right before the toggle. With `multiple` it posts one key per value, as a `