Listbox

Keyboard selection over authored options. Custom element

Choosing between components

Listbox is the inline core Select and 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.

Listbox

Copy this markup

<ui-listbox id="status-list" value="ready" name="status" role="listbox" aria-label="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>
</ui-listbox>

Install

Styles and registration

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:

Explicit registration

import { defineListboxElement } from '@timelessui/components/define/ui-listbox'
defineListboxElement()

Anatomy

Parts are authored in your own markup and identified by the selector below, so your CSS can target the same anatomy without loading Timeless styles. 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 <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-listbox>

Property	Type	Notes
multiple	boolean	Reflects the multiple attribute, documented above.
defaultValue	string	Reflects the value attribute, documented above.
value	string	Live value. Assigning it does not rewrite the authored default and does not dispatch transition events.
name	string	Reflects the name attribute, documented above.
required	boolean	Reflects the required attribute, documented above.
disabled	boolean	Reflects the disabled attribute, documented above.
pageSize	string	Reflects the page-size attribute, documented above.

Event	Detail	Description
ui-before-change	CustomEvent<ListboxChangeDetail>	Cancelable proposal dispatched before the selection changes. Call preventDefault() to reject the transition and keep the current value.
ui-change	CustomEvent<ListboxChangeDetail>	Dispatched after the selection has changed. Bubbles and is composed.
ui-page	CustomEvent<ListboxPageDetail>	Dispatched after the rendered page of a paged list changes.

State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through the selectors below rather than adding your own state classes.

State	Source	How to express it
selected	aria	aria-selected="true" on selected options.

Styling

Root identity: ui-listbox. Required stylesheets: tokens.css, core/listbox.css, core/options.css, themes/atmosphere/tokens.css, themes/atmosphere/listbox.css, themes/atmosphere/options.css.

Set these custom properties to restyle the component:

Custom property	Controls
--ui-collection-surface-inline-size	Minimum width of an option surface. On the anchored Select and Combobox surfaces the trigger width wins whenever it is larger.

Design tokens this component reads (15)

These are global Atmosphere tokens. Change them once at the theme level rather than per component.

--ui-accent · --ui-accent-soft · --ui-bg-surface · --ui-bg-surface-raised · --ui-disabled-opacity · --ui-fg · --ui-fg-muted · --ui-focus · --ui-line · --ui-radius-lg · --ui-radius-sm · --ui-shadow-floating · --ui-space-1 · --ui-space-2 · --ui-space-3

Accessibility

Keep the native elements, roles, and relationships shown in the example. 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 Listbox pattern from the ARIA Authoring Practices Guide.

Key	Action
Arrow keys	Move focus to the previous or next option, following the orientation and skipping disabled ones.
Home / End	Move focus to the first or last enabled option.
Enter / Space	Select the focused option, or toggle it when multiple is present.
Printable characters	Typeahead: jump to the next option whose text starts with what you typed.

Roving tabindex moves real focus between options, so selection follows aria-selected and never the focus ring. Options inside a group stay in one flat navigation order. header, footer, and the pager sit outside that order and are reached with Tab.

Verify in context

Automated checks cover axe WCAG 2.2 A and AA rules on every documented route. Keyboard, zoom, forced-colors, and screen-reader review still belong to your application.

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.

More examples

Open Listbox in StoryLite for variants, controls, and manual testing.