Select

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

Choosing between components

Select and 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 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.

Select

Copy this markup

<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

Styles and registration

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:

Explicit registration

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

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
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, documented above.
placement	'bottom' | 'top' | 'right' | 'left'	Reflects the placement attribute, documented above.
searchable	boolean	Reflects the searchable 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.
align	'start' | 'end'	Reflects the align attribute, documented above.
filter	'contains' | 'starts-with' | 'off'	Reflects the filter attribute, documented above.
multiple	boolean	Reflects the multiple attribute, documented above.
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<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)

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

--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 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 Select-Only Combobox pattern 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.

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 Select in StoryLite for variants, controls, and manual testing.