# Select

Enhance authored trigger, value, and listbox anatomy. (Custom element.)

Reference: https://timeless.build/docs/components/select/

> **Choosing between components.** Select and [Combobox](/docs/components/combobox/) are the same ARIA pattern over the same option core; they differ only in where you type. A Select types into a `search` field inside its surface, or not at all; a Combobox types into the trigger and accepts free text. Both replace the native control and cost JavaScript, so if plain text options are enough, [Native Select](/docs/components/native-select/) is still the better default.

> **Markup you author.** The trigger carries `popovertarget` naming the surface, so it opens, light-dismisses, and closes on Escape before any script loads. Give the surface an explicit `id` for it to name. Focus stays on the trigger and the active option travels through `aria-activedescendant`; add `searchable` to move that focus into a `search` field inside the surface instead. A surface that holds a search field, a header, a footer, or a pager needs a `surface` part around the `listbox`, because a `role="listbox"` may own only options and groups.

## Markup

```html
<ui-select value="ready" name="status">
  <label id="release-status-label">Release status</label>
  <button class="ui-button" data-ui-part="trigger" type="button" popovertarget="release-status-listbox" aria-labelledby="release-status-label release-status-value">
    <span data-ui-part="value" id="release-status-value">Ready</span>
  </button>
  <div id="release-status-listbox" data-ui-part="listbox" role="listbox" popover="auto" aria-label="Release status">
    <div data-ui-part="option" role="option" data-ui-value="draft">Draft</div>
    <div data-ui-part="option" role="option" data-ui-value="ready">Ready</div>
    <div data-ui-part="option" role="option" data-ui-value="published">Published</div>
  </div>
</ui-select>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/options.css'
import '@timelessui/components/css/core/select.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/select.css'
import '@timelessui/components/css/themes/atmosphere/options.css'
import '@timelessui/components/register/ui-select'
```

A `register/` import is a side effect: it defines the element as the module evaluates, so it
has to run in code the browser loads. To register explicitly instead — to control the timing,
or to define into another window — call the function from the matching `define/` entry point,
which registers nothing on its own:

```js
import { defineSelectElement } from '@timelessui/components/define/ui-select'
defineSelectElement()
```

## Anatomy

Parts are authored in your own markup and identified by the selector below. Required parts
must be present for the component to work. Private `data-ui-internal-*` hooks are written by
the runtime and must never be authored.

| Part | Required | Selector | Purpose |
| --- | --- | --- | --- |
| `trigger` | Yes | `[data-ui-part~='trigger']` | Native button that opens the listbox. Timeless gives it `role="combobox"`, which the Select-Only Combobox pattern asks for; that role takes no name from its content, so give the trigger `aria-labelledby` or `aria-label` yourself. |
| `value` | No | `[data-ui-part~='value']` | Element inside the trigger that shows the selected label. Timeless writes its text and nothing else. |
| `search` | No | `[data-ui-part~='search']` | Text field inside the surface that filters the options under `searchable`. Left and Right move the caret rather than the highlight. |
| `surface` | No | `[data-ui-part~='surface']` | The popover the listbox sits in. Author it whenever the surface also holds a `search` field, a `header`, a `footer`, or a pager: a `role="listbox"` may own only options and groups, so those siblings belong beside the listbox rather than inside it. With none of them, the `listbox` is its own surface and this part is unnecessary. |
| `listbox` | Yes | `[role='listbox']` | The option container. |
| `option` | Yes | `[role='option']` | One option. Its value comes from `value`, then `data-ui-value`, then its text. Mark unavailable options `aria-disabled="true"`. |
| `option-indicator` | No | `[data-ui-part~='option-indicator']` | Decorative affordance inside an option showing that it is selected. Style it from `[aria-selected="true"]`; it is hidden from assistive technology. |
| `group` | No | `[data-ui-part~='group']` | A `role="group"` wrapper around related options. Options inside it stay navigable, and the group collapses when every option it holds is filtered out. |
| `group-label` | No | `[data-ui-part~='group-label']` | The label for a `group`, wired to it with `aria-labelledby`. |
| `separator` | No | `[role='separator']` | A visual divider between options. Navigation and typeahead skip it. |
| `empty` | No | `[data-ui-part~='empty']` | Shown when no option is visible. Hidden again as soon as one is. |
| `status` | No | `[data-ui-part~='status']` | A `role="status" aria-live="polite"` region for result counts, loading, and errors. |
| `header` | No | `[data-ui-part~='header']` | Optional content at the top of the surface. Excluded from arrow navigation and reachable with `Tab`. |
| `footer` | No | `[data-ui-part~='footer']` | Optional content at the bottom of the surface. Excluded from arrow navigation and reachable with `Tab`. |
| `pager` | No | `[data-ui-part~='pager']` | Wraps the page controls. Hidden unless `page-size` is set and the options span more than one page. |
| `page-previous` | No | `[data-ui-part~='page-previous']` | Moves to the previous page. Stays focusable at the first page and takes `aria-disabled`, so the boundary is discoverable rather than gone. |
| `page-next` | No | `[data-ui-part~='page-next']` | Moves to the next page, with the same boundary behavior. |
| `page-status` | No | `[data-ui-part~='page-status']` | A `role="status" aria-live="polite"` region announcing the current page. |
| `chips` | No | `[data-ui-part~='chips']` | Container the selected values are rendered into under `multiple`. |
| `chip-template` | No | `template[data-ui-part~='chip-template']` | A `<template>` holding the markup for one chip. Timeless clones it per selected value and fills it in, so every element and class in a chip is yours. Without it a `chips` container receives a plain comma-separated summary instead. |
| `chip` | No | `[data-ui-part~='chip']` | One selected value, authored inside `chip-template`. |
| `chip-label` | No | `[data-ui-part~='chip-label']` | Where the selected label is written inside a chip. Omit it only when the chip has no other content. |
| `chip-remove` | No | `[data-ui-part~='chip-remove']` | Removes its chip. Author it as a real button; Timeless writes the value it removes onto it as `data-ui-value` and gives it an accessible name naming that value, since one shared template cannot. An `aria-label` you author wins. |
| `clear` | No | `[data-ui-part~='clear']` | Empties the whole selection. Marked `aria-disabled="true"` while there is nothing to clear, rather than `disabled`, so activating it cannot disable the control that holds focus. |

These parts also accept per-item input of their own. No stylesheet selects these
attributes — the component reads them.

| Part | Attribute | Description |
| --- | --- | --- |
| `option` | `data-ui-value` | The value this option submits, when its text is not the value. `value` wins over it, and its own text is the fallback. |
| `option` | `data-ui-label` | The text filtering and typeahead match against, when the visible content is not what a reader would type. `label` wins over it, then this, then `aria-label`, then the option text. None of the four change the accessible name. |

## Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes
are presence-based: author the attribute with no value, or omit it.

| Attribute | Values | Default | Description |
| --- | --- | --- | --- |
| `open` | presence | absent | Present to render the listbox open on load. |
| `placement` | `bottom` · `top` · `right` · `left` | `bottom` | Preferred side of the trigger for the listbox surface. |
| `searchable` | presence | absent | Present to filter from a `search` field inside the surface. Focus moves into that field on open and stays there; the highlight travels through `aria-activedescendant`. |
| `value` | any `string` | — | The option selected on load and after a form reset. Once the user commits a change the attribute stops applying, the way it does on a native input. |
| `align` | `start` · `end` | `start` | Which edge of the trigger the surface aligns to. The surface is never narrower than the trigger. |
| `filter` | `contains` · `starts-with` · `off` | `contains` | How typed text narrows the options. `off` hands visibility to you: listen for `ui-input` and set `hidden` yourself, and navigation, the empty state, group collapse, and paging all follow. |
| `multiple` | presence | absent | Present to allow more than one selected option. Selected values render as chips and submit one form entry each under the same `name`. |
| `name` | any `string` | — | Form field name. The element submits its own value through `ElementInternals`. |
| `required` | presence | absent | Present to block submission while nothing is selected, with `valueMissing`. |
| `disabled` | presence | absent | Present to disable the control. A control inside a disabled `<fieldset>` is disabled too, and submits nothing either way. |
| `page-size` | any `number` | — | Options to render per page. Absent means unpaged, which is the default and adds no pager. The resolved number is available on the read-only `pageCount` property. |

## Element API

Attributes above are the authoring surface. These are the DOM properties and events the
registered element adds once it upgrades.

### `<ui-select>`

| Property | Type | Notes |
| --- | --- | --- |
| `open` | `boolean` | Reflects the `open` attribute |
| `placement` | `'bottom' | 'top' | 'right' | 'left'` | Reflects the `placement` attribute |
| `searchable` | `boolean` | Reflects the `searchable` attribute |
| `defaultValue` | `string` | Reflects the `value` attribute |
| `value` | `string` | Live value. Assigning it does not rewrite the authored default and does not dispatch transition events. |
| `align` | `'start' | 'end'` | Reflects the `align` attribute |
| `filter` | `'contains' | 'starts-with' | 'off'` | Reflects the `filter` attribute |
| `multiple` | `boolean` | Reflects the `multiple` attribute |
| `name` | `string` | Reflects the `name` attribute |
| `required` | `boolean` | Reflects the `required` attribute |
| `disabled` | `boolean` | Reflects the `disabled` attribute |
| `pageSize` | `string` | Reflects the `page-size` attribute |

| Event | Detail | Description |
| --- | --- | --- |
| `ui-before-change` | `CustomEvent<SelectChangeDetail>` | Cancelable proposal dispatched before the selected option changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<SelectChangeDetail>` | Dispatched after the selected option has changed. Bubbles and is composed. |
| `ui-open` | `CustomEvent<SelectToggleDetail>` | Dispatched after the listbox opens. |
| `ui-close` | `CustomEvent<SelectToggleDetail>` | Dispatched after the listbox closes. |
| `ui-input` | `CustomEvent<SelectInputDetail>` | Dispatched when the query text changes, before options are filtered. Under `filter="off"` this is where you set `hidden` yourself. |
| `ui-page` | `CustomEvent<SelectPageDetail>` | Dispatched after the rendered page of a paged list changes. |

## Styling

Root identity: `ui-select`.
Required stylesheets: `tokens.css`, `core/floating.css`, `core/options.css`, `core/select.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/select.css`, `themes/atmosphere/options.css`.

Set these custom properties to restyle the component:

| Custom property | Controls |
| --- | --- |
| `--ui-collection-surface-inline-size` | Minimum width of the listbox surface. The trigger width wins whenever it is larger. |
| `--ui-floating-offset` | Gap between the trigger and the surface. |

Design tokens this component reads (32), global and set at the theme level: `--ui-accent`, `--ui-accent-soft`, `--ui-bg-accent`, `--ui-bg-accent-active`, `--ui-bg-accent-hover`, `--ui-bg-control`, `--ui-bg-control-active`, `--ui-bg-control-hover`, `--ui-bg-control-muted`, `--ui-bg-danger`, `--ui-bg-danger-active`, `--ui-bg-danger-hover`, `--ui-bg-surface`, `--ui-bg-surface-raised`, `--ui-disabled-opacity`, `--ui-duration-fast`, `--ui-ease-standard`, `--ui-fg`, `--ui-fg-muted`, `--ui-focus`, `--ui-line`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-sm`, `--ui-shadow-control-accent`, `--ui-shadow-control-active`, `--ui-shadow-control-danger`, `--ui-shadow-floating`, `--ui-shadow-outline-control`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`.

## Accessibility

Keep the native elements, roles, and relationships shown in the markup. Timeless adds only the
state and keyboard coordination the platform does not already provide, and it never supplies
your accessible names — those depend on your content.

Follows the [Select-Only Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Enter / Space` | Open the listbox, or commit the active option when it is already open. |
| `Arrow keys` | Open the listbox from the closed trigger, or move the active option when it is already open. |
| `Home / End` | Move to the first or last option while the listbox is open. |
| `Escape` | Close the listbox without changing the value. |
| `Printable characters` | Typeahead over the option labels. On a closed Select this selects a match without opening, as the native control does. |
| `Backspace` | In an empty `search` field under `multiple`, removes the last chip. |

Timeless gives the trigger `role="combobox"`, which is what the Select-Only Combobox pattern asks for and what makes `aria-activedescendant` legal on it. Your own `role` wins over that, and the relationship follows the role: set one that cannot carry `aria-activedescendant`, such as `button`, and Timeless writes no relationship rather than an invalid one, while the active option is still highlighted — `checkMarkup` reports the role, because the degradation is otherwise silent. That role does not take its name from its content, so the trigger needs your `aria-labelledby` or `aria-label`; `checkMarkup` reports it when missing. Focus stays on the trigger and the active option is announced through `aria-activedescendant`; under `searchable` focus moves into the `search` field instead and the same mechanism carries the highlight. The trigger carries `popovertarget`, so it opens the surface before any script runs. Light dismiss and Escape come from the Popover API. `header`, `footer`, and the pager sit outside arrow navigation and are reached with `Tab`.

## Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.