# Combobox
## Usage This component ships a `combobox()` macro for Jinja and Nunjucks. ```html ``` Combobox is input-first. The visible input filters the list; the hidden input stores the submitted value. ```html
``` ### HTML structure
<div class="combobox">
Root element. Add data-auto-highlight="true" to make the first visible option active when the list opens or filters. Add data-format="object" to serialize selected values as objects. Add data-filter="manual" when your app owns filtering.
<input type="text" role="combobox">
The editable control. It can be a direct child, inside .input-group, or inside data-popover for popup mode.
<button aria-haspopup="listbox"> Optional
Opens the list from an input group or popup trigger. In popup mode, include a child with data-value and optional data-placeholder to display the selected value.
<button data-clear> Optional
Clears the current selection. Put the clear icon inside the button.
<svg class="combobox-trigger-icon"> Optional
Decorative trailing icon for input-style comboboxes. Replace the SVG to customize the icon.
<div data-popover>
The suggestions popup. Use data-side and data-align like Popover.
<div role="listbox">
The suggestions list. Add aria-multiselectable="true" in multiple mode. The component uses that attribute to render selected chips around the input.
<div role="option" data-value="...">
Selectable option. Options can contain custom HTML; use data-label when the input should display different text than the rendered content.
<input type="hidden">
Submitted value. Single mode stores a string; multiple mode stores a JSON array. With data-format="object", selected values are stored as objects.
### JavaScript API | API | Type | Description | | --- | --- | --- | | `change` | Event | Dispatched on selection changes with `event.detail.value` and `event.detail.selected`. | | `combobox.setValue(value)` | Method | Sets the selected value from a plain value or `{ value, label }` object. | | `combobox.clear()` | Method | Clears the selected value. | | `combobox.refresh()` | Method | Rescans options after children change inside the existing `role="listbox"` element. | ## Examples ### Multiple
### Clear button
### Groups
### Custom items
### Invalid

Select a framework to continue.

 ### Disabled
### Auto highlight Auto highlight makes the first visible option active when the list opens or filters, so pressing Enter can select it without arrowing first.
### Popup ### Input group
### RTL