--- title: "Select" description: "A list of options in a popup, opened from a button: searchable, keyboard driven, and styled like an input." url: "https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/select" section: "Components" --- # Select A list of options in a popup, opened from a button: searchable, keyboard driven, and styled like an input. ```html

Country

Where the invoice is billed.

``` A select is a [dropdown](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/dropdown) that picks a value: the trigger takes the label's place in a [field](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/field), and the chosen option is what the form submits. Reach for it when the native `` that only needs styling, keep the [.select](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/input) input class. ## Markup - Wrap the trigger and the list in `.select` with `data-select`, like a dropdown. - The trigger is a `button` with `data-select-trigger`, `aria-haspopup="listbox"` and `aria-expanded="false"`. Its text goes in an empty `.select-value` span, with `data-placeholder` for the text shown until something is picked. Name the button after the field's label with `aria-labelledby`. - The list is a `.select-content` with `role="listbox"` that starts `hidden`. Each entry is a `.select-item` with `role="option"`, a `value`, and `aria-selected="true"` on the picked one. - Add `aria-disabled="true"` to an option the user can't pick: it is skipped by the keyboard and can't be clicked. - To submit the value, put a hidden field inside the select: ``. A preselected option fills it, and every choice rewrites it. - An option holding more than text (a flag, a badge) can carry `data-label`, the plain text the trigger shows. ## Keyboard | Key | Action | | --- | --- | | `↓` `↑` on the trigger | Open on the picked option, or the first / last | | `↓` `↑` `Home` `End` | Move between options | | `Enter` `Space` | Pick the focused option and close | | `Esc` | Close and return focus to the trigger | | `Tab`, click outside | Close | ## Searching Put an `.input` in a `.select-search` wrapper inside the list with `data-select-search`. Typing filters the options, `↓` moves into them, and a matching option can carry `aria-selected="true"` so it comes first. Add a `.select-empty` with `data-select-empty` for the "no matches" message: it stays hidden until a search finds nothing, and the filter resets when the list closes. ```html

``` ## Groups A `.select-label` heads a run of options and a `.select-separator` divides them. They are text, not options, so the keyboard skips them. ```html

``` ## Sizes and states `.select-sm` and `.select-lg` match `.input-sm` and `.input-lg`. `disabled` on the trigger, and `aria-invalid="true"` for an error, work as they do on an input. ```html

``` ## Alignment The list opens below the trigger, as wide as the trigger and aligned to its left edge. Add `.select-content-end` to align it to the right edge, or `.select-content-up` to open it upwards. ```html

``` ## With htmx Every choice fires a bubbling `select:change` with `detail.value` (the option's `value`), `detail.label` and `detail.option`. Trigger requests on it rather than on `click`, so they run once the value has been set. Inside a form, htmx posts the form's values — the hidden `[data-select-input]` among them — so the request carries the choice with no extra wiring: ```html

``` Outside a form, pass the value yourself with the event: `hx-vals='js:{region: event.detail.value}'`. ## Loading options with htmx Swap the option list in on `load`, or after a request elsewhere: the behaviour looks options up on every event, so a list that arrives from the server keeps filtering and navigating. Mark the picked one with `aria-selected="true"` and put the value in `[data-select-input]` in the swapped markup and the new list starts out in step. ## Nunjucks macro The `select` macro writes the trigger, the options and the hidden field from a list. Options are `[{value, label}]` pairs, or plain strings when the value is the label. ```jinja page.html {% from "components/select/select.html" import select %}

Country {{ select("country", json("data/countries.json"), value="nz", name="country", searchable=true, label="Country") }}

{{ select("plan", ["Free", "Pro"], value="Free", label="Plan") }} ``` ## Reference | Class / attribute | Description | | --- | --- | | `.select` | Positioning wrapper (relative, inline-block). | | `.select-trigger` | The button that opens the list. Looks like an .input. | | `.select-sm / .select-lg` | Trigger sizes, matching .input-sm / .input-lg. | | `.select-value` | The picked text. Empty, with data-placeholder, until something is picked. | | `.select-content` | The listbox. Opens below, as wide as the trigger. | | `.select-content-end / .select-content-up` | Align to the right edge / open above. | | `.select-search` | Sticky wrapper for a [data-select-search] filter input. | | `.select-item` | One option. aria-selected marks the picked one, aria-disabled an unavailable one. | | `.select-check` | Icon inside an option, shown only while it is picked. | | `.select-label / .select-separator` | Heading and divider inside the list. | | `.select-empty` | Shown by the behaviour when a search finds nothing. | | `[data-select] / [data-select-trigger]` | Behaviour: open/close, keyboard, filtering, and select:change { value, label, option }. | | `[data-select-input]` | Hidden field mirroring the picked value, so a form can submit it. |