# Combobox > A searchable select on a real select element, bound with th:field; type to filter, choose one value or several as chips, and load the options from the server as you type. Source: https://shadleaf.dev/current/components/combobox/ **Example: Combobox.** Type to filter the list; th:field marks the bound item. ```html

Framework

Next.js

SvelteKit

Nuxt.js

Remix

Astro

``` ## Built from parts A combobox is `` holding ``s, optionally in ``s with ``s between them. Like [``](https://shadleaf.dev/current/components/select.md), it renders a real ``, so `th:field` binds a collection (`List`, `Set`, ...) and the form submits one value per chosen item. Spring's hidden marker input comes with it, so choosing none binds an empty collection. **Example: Multiple.** With multiple, the chosen items are chips before the input and th:field binds a collection. ```html

Frameworks

Next.js

SvelteKit

Nuxt.js

Remix

Astro

``` ## Placeholder and clearing `placeholder` is the input's text while nothing is chosen. For a single value it is also a first option with an empty value, hidden from the list, which is chosen while the field has no value: a `required` combobox with nothing chosen is invalid, as for a select. Emptying the input and leaving it clears the choice. `show-clear` adds a button that does the same, in place of the chevron while there is something to clear; in a multiple combobox it removes every chip. **Example: Clear button.** show-clear puts a button that clears the choice in place of the chevron while there is one. ```html

Stack

Next.js

SvelteKit

Nuxt.js

``` ## Groups, separators and icons `` is an ``: its label shows above its items, and hides while none of them match what was typed. `` is an `

`, hidden while typing. **Example: Groups and separators.** Some 80 time zones, too many to scan, so you type a city instead (bru finds Brussels). A group's heading hides while none of its items match; separators hide while you type. ```html

Timezone

(GMT-10) Honolulu

(GMT-9) Anchorage

(GMT-8) Los Angeles

(GMT-8) Tijuana

(GMT-8) Vancouver

(GMT-7) Denver

(GMT-7) Edmonton

(GMT-7) Phoenix

(GMT-6) Chicago

(GMT-6) Guatemala

(GMT-6) Mexico City

(GMT-6) Winnipeg

(GMT-5) Bogota

(GMT-5) Havana

(GMT-5) Lima

(GMT-5) New York

(GMT-5) Toronto

(GMT-4) Caracas

(GMT-4) Halifax

(GMT-4) La Paz

(GMT-4) Santiago

(GMT-3:30) St. John's

(GMT-3) Buenos Aires

(GMT-3) Montevideo

(GMT-3) São Paulo

(GMT+0) Dublin

(GMT+0) Lisbon

(GMT+0) London

(GMT+0) Reykjavik

(GMT+1) Amsterdam

(GMT+1) Berlin

(GMT+1) Brussels

(GMT+1) Budapest

(GMT+1) Copenhagen

(GMT+1) Madrid

(GMT+1) Oslo

(GMT+1) Paris

(GMT+1) Prague

(GMT+1) Rome

(GMT+1) Stockholm

(GMT+1) Vienna

(GMT+1) Warsaw

(GMT+1) Zurich

(GMT+2) Athens

(GMT+2) Bucharest

(GMT+2) Helsinki

(GMT+2) Kyiv

(GMT+3) Istanbul

(GMT+3) Moscow

(GMT+0) Accra

(GMT+0) Casablanca

(GMT+1) Algiers

(GMT+1) Kinshasa

(GMT+1) Lagos

(GMT+2) Cairo

(GMT+2) Johannesburg

(GMT+3) Addis Ababa

(GMT+3) Nairobi

(GMT+2) Jerusalem

(GMT+3) Riyadh

(GMT+3:30) Tehran

(GMT+4) Dubai

(GMT+5) Karachi

(GMT+5:30) Kolkata

(GMT+5:45) Kathmandu

(GMT+6) Dhaka

(GMT+7) Bangkok

(GMT+7) Ho Chi Minh City

(GMT+7) Jakarta

(GMT+8) Hong Kong

(GMT+8) Manila

(GMT+8) Shanghai

(GMT+8) Singapore

(GMT+8) Taipei

(GMT+9) Seoul

(GMT+9) Tokyo

(GMT+8) Perth

(GMT+9:30) Adelaide

(GMT+10) Brisbane

(GMT+10) Melbourne

(GMT+10) Port Moresby

(GMT+10) Sydney

(GMT+12) Auckland

(GMT+12) Fiji

``` An item may start with an [icon](https://shadleaf.dev/current/components/icon.md). The list shows it; the input and the chips show the item's text. **Example: Custom items.** An item may start with an icon. The input and the chips show its text. ```html

Status

Backlog

Todo

In progress

Done

``` ## Filtering and auto-highlight The list shows the items whose text contains what was typed, ignoring case and accents (`turk` finds Türkiye). By default nothing is highlighted while typing, so Enter does not choose by accident; `auto-highlight` highlights the first match, so typing a few letters and pressing Enter chooses it. Long lists scroll; the list never grows taller than the window. **Example: Long lists.** The list scrolls when it is taller than the window; auto-highlight makes Enter choose the first match. ```html

Country

Argentina

Australia

Austria

Belgium

Brazil

Canada

Chile

China

Colombia

Czechia

Denmark

Egypt

Finland

France

Germany

Greece

India

Indonesia

Ireland

Italy

Japan

Kenya

Mexico

Morocco

Netherlands

New Zealand

Nigeria

Norway

Peru

Poland

Portugal

South Africa

South Korea

Spain

Sweden

Switzerland

Thailand

Türkiye

United Kingdom

United States

Vietnam

``` ## Options from the server `search-url` makes the combobox ask the server for the options as people type, for lists too long to put in the page. 300 ms after the last key, it sends a `GET` to that URL with the text as `q`, and expects the HTML of ``s (and groups and separators, if you like) back. A Thymeleaf fragment renders them: ```html

[[${chosenCountry.name}]]

``` ```java @GetMapping("/countries/search") String searchCountries(@RequestParam String q, Model model) { model.addAttribute("countries", countryService.search(q, 20)); return "countries :: options"; } ``` ```html

[[${country.name}]]

``` - **The answer replaces the options** that are not chosen. A chosen option stays, so the value does not change; when the answer leaves it out, it stays hidden from the list. Render the chosen option(s) in the page, as above, so the combobox can show and submit them before anyone types. - **The server filters.** The browser shows what the answer holds, without filtering it again; an empty answer shows "No items found." (or `empty`). Limit the number of results on the server. - **An empty input** brings back the options the page came with: render a first few there, or none. - **A newer query aborts the request before it**, so a slow answer never replaces a newer one. While waiting, the list says "Searching…"; an answer that is not a 2xx, or that was redirected (a session that expired and sent the request to the login page), shows "The options could not be loaded." - **To add parameters**, such as another field's value for options that depend on it, listen for `sl-combobox-search` on the select. It fires before each request, with `detail.query` and `detail.url`, a `URL` whose `searchParams` you can change; `preventDefault()` skips the request. ```js document.addEventListener('sl-combobox-search', event => { if (event.target.id === 'city') { event.detail.url.searchParams.set('country', document.getElementById('country').value); } }); ``` Searching needs JavaScript. Without it, the combobox is a select with the options in the page, so only those can be chosen. ## Width The combobox sits in a wrapper that also holds the input and the list. `class` goes to that wrapper, so `class="w-full"` widens it; every other attribute goes to the ``, so `hx-trigger="change"` and your own listeners work as for any select. A script that changes the select's options or value should fire `change` itself; the input and the chips follow. - **Form reset** puts the combobox back to its rendered value. **Example: With errors.** In a field with errors, the combobox is aria-invalid and described by the message. ```html

Language

Java

Kotlin

Groovy

Other languages

Java

Kotlin

Groovy

``` ## Disabled `disabled` on the combobox, or on a `` around it, disables it: it fades with its chips. `disabled` on an item leaves it in the list, faded; the keyboard and the pointer skip it. **Example: Disabled.** A disabled combobox, and disabled items that the keyboard and the pointer skip. ```html

Runtime

JVM

Plugins

Lombok

MapStruct

Build tool

Maven

Ant

Gradle

``` ## Keyboard The focus stays in the input; the highlighted item is announced through `aria-activedescendant`, as the [ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/) describes. | Key | Does | | --- | --- | | Typing | Opens the list and filters it | | Arrow down, arrow up | Opens the list on the chosen item; next, previous item | | Alt + arrow down | Opens the list without highlighting | | Page down, page up | Ten items further, back | | Enter | Chooses the highlighted item; in a multiple combobox, adds or removes it and keeps the list open | | Alt + arrow up | Chooses the highlighted item and closes the list | | Escape | Closes the list, putting back the text of the choice | | Tab | Closes the list without choosing and moves on | | Home, End | Move the caret, as in any text field | | Backspace (multiple, empty input) | Removes the last chip | | Arrow left (multiple, at the start of the input) | Moves to the chips' remove buttons: arrow left and right between them, Backspace or Delete removes one | The number of matches is announced once typing pauses ("3 results"; the texts are messages, `sl.combobox.*`, see [Translating](https://shadleaf.dev/current/guides/translating.md)). The clear and chevron buttons stay out of the tab order: each has a key. The item under the pointer is highlighted. ## With htmx - A response that renders the form again with errors keeps the chosen values (`th:field` marks them). - A swap that replaces an open combobox leaves nothing open behind. - Back restores the combobox as htmx saved it; it builds its input and list again from the restored select. - A combobox can trigger a request itself: `hx-get="/cities" hx-trigger="change" hx-target="#city-field"`. Options swapped into the select are picked up by the list. ## Forced colours The input and the list keep a visible border, the highlighted item an outline and the chips a border, when the system's colours replace the page's (Windows High Contrast). A disabled combobox turns `GrayText` instead of fading. ## Left out These are left out on purpose: - **The popup layout**, with a button as the trigger and the input inside the list, and **addons** in the input. - **Free text**: the value is always one of the items. - **Chips that cannot be removed**: a chip always has its remove button, and shows the item's text. - **Placing the list elsewhere**: the list opens below the input, or above it when there is no room. ## Without JavaScript The server renders a real select, drawn like the [native select](https://shadleaf.dev/current/components/select-native.md): a single combobox is a select with a chevron, a multiple one a list box (Ctrl- or Cmd-click chooses several). Both bind, submit and validate as any select. With Alpine, `slCombobox` puts its input and list in the select's place. ## Attributes ### sl:combobox Attributes of ``: A text input that filters a list of options as you type. Like `sl:select`, it is a real `select` with `sl:combobox-item`, `sl:combobox-group` and `sl:combobox-separator` as content, so `th:field` binds it (a collection with `multiple`) and the form submits it. Once Alpine runs, `slCombobox` hides the select and puts an input and a list box in its place; without it, the select is drawn like `sl:native-select`. Every attribute that is not a prop passes through to the `select`, except `class`, which goes to the wrapper around it. In a `sl:field`, it takes the field's `th:field`, id and `aria-describedby`. | Attribute | Values | Default | Description | | --- | --- | --- | --- | | `placeholder` | *string* | — | The input's text while nothing is chosen. For a single value also the text of a first option with an empty value, hidden from the list: a required combobox with it chosen is invalid. | | `multiple` | *boolean* | — | Choose any number of options, shown as chips before the input. The select is a `select multiple`, so `th:field` binds a collection. | | `show-clear` | *boolean* | — | A button that clears the choice, in place of the chevron while there is one. | | `show-trigger` | *boolean* | `true` | The chevron button that opens and closes the list. A multiple combobox has none. | | `auto-highlight` | *boolean* | — | Highlight the first match while typing, so Enter chooses it. | | `empty` | *string* | — | The text shown when no option matches. By default "No items found." | | `search-url` | *string* | — | Ask the server for the options as you type: a `GET` to this URL with the text as `q`, answered with the HTML of `sl:combobox-item`s (and groups and separators), which replace the options that are not chosen. Needs JavaScript; without it, only the options in the page can be chosen. | Every prop can also be set from an expression: `th:placeholder="${...}"`. Any other attribute passes through to the rendered element, and `class` is appended. ### sl:combobox-item Attributes of ``: An option in a `sl:combobox`: an `option`. `value` (or `th:value`) and `disabled` pass through; `th:field` on the combobox marks the bound one. The list shows its content, which may start with an icon, with a check mark while it is chosen; the input, the chips and the filter use its text, which is all an older browser keeps of it. `sl:combobox-item` declares no props; every attribute passes through. ### sl:combobox-group Attributes of ``: A group of `sl:combobox-item`s under a heading: an `optgroup`. The list hides the heading while none of its items match. | Attribute | Values | Default | Description | | --- | --- | --- | --- | | `label` | *string* | **required** | The group's heading. | Every prop can also be set from an expression: `th:label="${...}"`. Any other attribute passes through to the rendered element, and `class` is appended. ### sl:combobox-separator Attributes of ``: A line between items or groups of a `sl:combobox`: an `hr`. The list hides it while you type. `sl:combobox-separator` declares no props; every attribute passes through. ## JavaScript A small Alpine component, `slCombobox`, sits on the wrapper: `

`. - **It hides the `