# Listbox
Keyboard selection over authored options. (Custom element.)
Reference: https://timeless.build/docs/components/listbox/
> **Choosing between components.** Listbox is the inline core [Select](/docs/components/select/) and [Combobox](/docs/components/combobox/) compose: the same option semantics, selection, groups, typeahead, and paging, without a trigger or a popover. Use it directly when the choices should always be visible, and reach for one of the other two when they should not.
> **Markup you author.** The host carries `role="listbox"` and scrolls its own options. Add an `empty` region, a `status` region, or a pager and those cannot sit inside it — a listbox may own only options and groups — so wrap the options in an inner `listbox` part and let the host be the frame around it.
## Markup
```html
Draft
Ready
Published
```
## Install
```js
import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/listbox.css'
import '@timelessui/components/css/core/options.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/listbox.css'
import '@timelessui/components/css/themes/atmosphere/options.css'
import '@timelessui/components/register/ui-listbox'
```
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 { defineListboxElement } from '@timelessui/components/define/ui-listbox'
defineListboxElement()
```
## 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 |
| --- | --- | --- | --- |
| `listbox` | Yes | `[role='listbox']` | The option container, which is the host itself. |
| `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. |
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 |
| --- | --- | --- | --- |
| `multiple` | presence | absent | Present to allow more than one selected option, submitting one form entry per value under the same `name`. |
| `value` | any `string` | — | The option selected on load and after a form reset. Assign the `value` property for live changes; once the user commits a change the attribute stops applying, the way it does on a native input. |
| `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 `