# Combobox

Filter an authored listbox from a native text input. (Custom element.)

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

> **Choosing between components.** Combobox and [Select](/docs/components/select/) are the same ARIA pattern over the same option core, differing only in where you type. Reach for Combobox when the user should be able to type free text or filter from the control itself, and for a `searchable` Select when the trigger should stay a button that shows the chosen value.

> **Markup you author.** The input is both the trigger and the search field: Timeless wires `aria-expanded`, `aria-controls`, and `aria-activedescendant` onto it and leaves its editing behavior alone. Filtering sets `hidden` on non-matching options rather than removing them, which is also the extension point — set `filter="off"` and Timeless filters nothing, emits `ui-input` with the query, and lets you set `hidden` yourself. Navigation, the empty state, group collapse, and paging all keep working, because every one of them reads `hidden`.

## Markup

```html
<ui-combobox name="component">
  <label for="component-search">Component</label>
  <input id="component-search" role="combobox" type="text" aria-autocomplete="list" placeholder="Type to filter…">
  <div id="component-search-surface" data-ui-part="surface" popover="manual">
    <div id="component-search-listbox" data-ui-part="listbox" role="listbox" aria-label="Component">
      <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>
    <p data-ui-part="empty" hidden>No component matches that filter.</p>
  </div>
</ui-combobox>
```

## Install

```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/combobox.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/options.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/combobox.css'
import '@timelessui/components/css/themes/atmosphere/options.css'
import '@timelessui/components/register/ui-combobox'
```

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 { defineComboboxElement } from '@timelessui/components/define/ui-combobox'
defineComboboxElement()
```

## 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 | `input[role='combobox']` | The native text input. It is both the trigger and the search field: Timeless wires `aria-expanded`, `aria-controls`, and `aria-activedescendant` onto it and leaves its editing behavior alone. |
| `surface` | No | `[data-ui-part~='surface']` | The popover the listbox sits in. Author it whenever the surface also holds a `header`, a `footer`, or a pager: a `role="listbox"` may own only options and groups. 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 |
| --- | --- | --- | --- |
| `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-combobox>`

| Property | Type | Notes |
| --- | --- | --- |
| `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<ComboboxChangeDetail>` | Cancelable proposal dispatched before the selected option changes. Call `preventDefault()` to reject the transition and keep the current value. |
| `ui-change` | `CustomEvent<ComboboxChangeDetail>` | Dispatched after the selected option has changed. Bubbles and is composed. |
| `ui-open` | `CustomEvent<ComboboxToggleDetail>` | Dispatched after the listbox opens. |
| `ui-close` | `CustomEvent<ComboboxToggleDetail>` | Dispatched after the listbox closes. |
| `ui-input` | `CustomEvent<ComboboxInputDetail>` | Dispatched when the query text changes, before options are filtered. Under `filter="off"` this is where you set `hidden` yourself. |
| `ui-page` | `CustomEvent<ComboboxPageDetail>` | Dispatched after the rendered page of a paged list changes. |

## Styling

Root identity: `ui-combobox`.
Required stylesheets: `tokens.css`, `core/combobox.css`, `core/floating.css`, `core/options.css`, `core/button.css`, `themes/atmosphere/tokens.css`, `themes/atmosphere/button.css`, `themes/atmosphere/combobox.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 input width wins whenever it is larger. |
| `--ui-floating-offset` | Gap between the input and the surface. |

Design tokens this component reads (34), 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-line-strong`, `--ui-radius-control`, `--ui-radius-lg`, `--ui-radius-md`, `--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 [Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) from the ARIA Authoring Practices Guide.

| Key | Action |
| --- | --- |
| `Arrow Down / Arrow Up` | Open the listbox, then move the active option. |
| `Home / End` | Move to the first or last matching option. |
| `Arrow Left / Arrow Right` | Move the text caret. They never move the highlight. |
| `Enter` | Commit the active option. |
| `Escape` | Close the listbox, then clear the filter on a second press. |
| `Backspace` | In an empty input under `multiple`, removes the last chip. |

Focus stays in the text input at all times; the active option is exposed with `aria-activedescendant`. Filtering hides non-matching options rather than removing them, so find-in-page and the DOM still show the full authored list. `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.