An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 3 kind: component id: component:Selector authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-24 owners: [cixzhang, imdreamrunner] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/Selector/Selector.test.tsx, packages/core/src/Selector/Selector.openHighlight.test.tsx, packages/core/src/Selector/Selector.source-build.test.mjs, packages/core/src/Selector/tests/Selector.listbox.a11y.test.tsx, packages/core/src/Selector/tests/Listbox.a11y.chromium.spec.ts, packages/core/src/Selector/tests/Selector.combobox.a11y.test.tsx, packages/core/src/Selector/tests/Selector.combobox.a11y.chromium.spec.ts, packages/core/src/Selector/tests/SelectorListboxName.a11y.chromium.spec.ts, apps/storybook/stories/Selector.stories.tsx, .github/scripts/story-play-guard.js, ] modules: [] families: [family:input-fields] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:icon-resolution-and-component-slots, architecture:interaction-modality, architecture:layer-runtime, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-004/DEC-1, spec:AST-011/DEC-1]
Selector component contract
Intent
Selector lets a person choose one value from a moderate list while keeping the trigger usable as a form field or compact toolbar control. It owns single-value selection, option navigation, search within the supplied options, and the connection between the closed trigger and its selection surface.
Compatibility and migration
- Released defaults and behavior are unchanged except the
presentationdefault, which DEC-1 sets, andadaptive's compact test (below). indicatorPositiondefaults toend; a rendered selection mark occupies space at that logical edge, while an empty resolved indicator occupies none.presentationdefaults toadaptive(DEC-1): the modal bottom sheet on compact coarse-pointer screens and the anchored popover otherwise.popoverandbottom-sheetpin one surface on every device. The default is a stable-default change, so it ships as[breaking]in a scheduled minor underspec:AST-017; callers that need the anchored popover on every device passpopover.adaptive's compact test becomesspec:AST-012FR9 (width below the effectivemdpoint or height below 500) in place of the shipped(max-width: 768px)query: a coarse-pointer screen exactly 768 pixels wide and at least 500 tall opens the popover, and a coarse-pointer screen wider than 768 but under 500 tall opens the bottom sheet. Both surfaces keep selection working, so no caller must change source and the change is not breaking underspec:AST-017FR1;popoverandbottom-sheetpin one surface. It is pending until the shared resolver conforms; FR4 describes the shipped query.hasClearchanges the value contract to includenull; that distinction is already part of the public type.isReadOnlyis additive and defaults tofalse. It preserves the selected value, focus, and form participation while removing selection-surface and editing affordances.isDisabledtakes precedence when both are set.secondaryis an additive trigger variant.inputremains the default; existinginputandghostcallers keep their released behavior.spec:AST-004/DEC-1governs the state-derived indicator-space behavior in FR3.- 0.7.0 removes the
selector-clear-iconalias; the shared clear glyph remains available throughinput-clear-icon. - Migration decision: replace the removed theme key and CSS class with
input-clear-iconand.astryx-input-clear-icon, or runastryx upgrade --from 0.6.3 --apply --path ..
DEP-0011 — Deprecate the popover default presentation
| Field | Value |
|---|---|
| id | DEP-0011 |
| cleanup | CLN-0020 |
| package | @astryxdesign/core |
| surface | Default presentation of Selector, MultiSelector, and DropdownMenu with items (and MoreMenu, which forwards to it): the anchored popover on every device |
| old contract | With no presentation, the option or action list opens in an anchored, non-modal popover on every device |
| replacement | presentation="popover" keeps the anchored popover on every device; adaptive is released and already accepted |
| direct authority | component:Selector DEC-1. Owners: cixzhang, imdreamrunner. MultiSelector and DropdownMenu have no current contract that sets this default |
| warning | Consumer docs and the release notes name DEP-0011 and presentation="popover". No runtime warning (spec:AST-017 FR29) |
| migration | Mechanical where the popover is wanted on every device: add presentation="popover" |
| codemod | None by default: pinning popover everywhere would opt every caller out of the change. A preserving codemod is mechanical if an owner wants one |
| downstream | Guidance says to keep the default and pin popover only when product policy needs it |
| transition | no prior transition |
| state | proposed |
| open decision | Current authority for the MultiSelector and DropdownMenu defaults |
| target plan | CLN-0020 in the next minor release |
CLN-0020 — Selector, MultiSelector, and data-driven DropdownMenu default to adaptive
| Field | Value |
|---|---|
| id | CLN-0020 |
| lifecycle | DEP-0011 |
| delta | With no presentation, a compact coarse-pointer screen opens a modal bottom sheet (trigger aria-haspopup="dialog", focus moves in and returns on close); every other device keeps the anchored popover. Compound DropdownMenus are unchanged |
| rollback | Restore the popover default from the final-patch baseline |
| state | pending — lands in a declared minor with its [breaking] Changeset |
Ownership boundary
Owns
- Choosing one value from supplied options.
- Trigger, listbox, option, search, empty, loading, and disabled behavior.
- Keyboard navigation and announcements for that selection flow.
- Selector-specific composition of shared Field, Layer, adaptive presentation, and indicator behavior.
Does not own / non-goals
- Action or navigation menus; DropdownMenu owns those.
- Multi-value selection; MultiSelector owns it.
- The
SelectorOptioncontent row a caller returns fromrenderOptionorrenderValue— owned bycomponent:SelectorOption. - Product-specific option content or filtering performed outside the supplied option list.
- Family-wide input state display, behavior, appearance, size, end-control,
status-placement, and disabled-reason policy — owned by current
family:input-fields.
Public concepts
This table names semantic concepts reviewers need. Prop syntax, complete defaults,
and examples remain in Selector.doc.mjs.
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| trigger variant | input, secondary, ghost |
Form-field or button-aligned toolbar presentation | All trigger states | input |
Selector | released; secondary additive |
TypeScript rejects other values |
| size | sm, md, lg |
Trigger and option-row density | All presentations | md |
Selector | released | TypeScript rejects other values |
| selected-mark position | start, end |
Logical edge containing a rendered selection mark | Every option row | end |
Selector | released | TypeScript rejects other values |
| presentation | popover, bottom-sheet, adaptive |
Anchored pointer surface or modal compact-touch surface | All trigger variants | adaptive |
Selector | released | TypeScript rejects other values |
| popup semantics | listbox; modal dialog containing one |
Semantics follow the active presentation | Popover; bottom sheet | listbox |
Selector | released | No separate role prop is public |
| option-row state | selected, disabled |
Stable theming state on each option row | Every rendered option | neither | Selector | released | Unknown states are not emitted |
| read-only state | false, true |
Preserves and submits value without selection affordance | Closed trigger | false |
Caller | additive | Boolean normalization |
Behavioral and layout contract
These requirements describe shipped behavior on current main.
| ID | Shipped invariant | Evidence |
|---|---|---|
| FR1 | Selecting an enabled option updates the one selected value, closes the active presentation, and returns the trigger to its stable closed state. | Consumer docs and selection interaction tests |
| FR2 | Without explicit placement, a non-search popover aligns the selected row over the trigger and clamps it to the viewport, above any software keyboard (spec:AST-059 FR9); a keyboard that goes down while it is open does not move its top. Search popovers and explicit placement use normal Layer positioning. |
Consumer docs, implementation, and geometry tests |
| FR3 | An option whose resolved selection indicator draws no content reserves no mark-column space. Visible selected or themed replacement indicators remain in layout at indicatorPosition; the resulting state-dependent label position or available width is intentional, and row content keeps its existing overflow behavior. |
itemMarkColumn, focused indicator tests, and Chromium evidence stories |
| FR4 | popover uses an anchored Popover. bottom-sheet uses a modal BottomSheet. adaptive resolves to the modal bottom sheet on compact coarse-pointer screens and Popover otherwise. |
Presentation controller and adaptive-presentation tests |
| FR5 | While isLoading is true, the trigger exposes busy state and the listbox suppresses empty and no-results output. |
Loading, empty-state, and announcement tests |
| FR6 | While isReadOnly is true, the selected value remains focusable and form-submittable, while the selection surface, clear action, disclosure indicator, and every value-change path are unavailable. |
Read-only interaction, form, and accessibility tests |
| FR7 | The listbox carries data-astryx-menu-press and follows module:DropdownMenu/useMenuPress FR1–FR3, FR5 and AR2: the option under a pointer's release is the one selected, the highlight follows a held pointer through aria-activedescendant while DOM focus stays on the combobox, a mouse released outside closes the list and a finger leaves it open, and the browser's stray click never selects. Trigger opening, arrow clamping and closed-trigger typeahead are unchanged. |
module:DropdownMenu/useMenuPress; Selector.test.tsx press model suite |
| FR8 | Opening the closed list highlights the selected option when it is enabled. Otherwise ArrowUp highlights the last enabled option, and every other way of opening (ArrowDown, a press, Enter, Space) the first enabled option; with no enabled option nothing is highlighted. A disabled option is never highlighted on opening. A search list opened by a press, Enter or typing highlights nothing. | WAI-ARIA listbox and select-only combobox patterns; Selector.openHighlight.test.tsx |
| FR9 | In a search list, each change to the query clears the highlight, so aria-activedescendant never names an option of the previous list; ArrowDown then starts at the first enabled option, and Enter with nothing highlighted selects nothing. |
WAI-ARIA combobox pattern; Selector.searchHighlight.test.tsx |
| FR10 | The highlight follows its option by value: when options move or reload, the highlighted option stays highlighted while it remains in the list; if it leaves, the highlight moves to the next remaining option after it in list order, or the previous remaining option when none remains after it. A disabled option is never highlighted this way, and with no enabled option left nothing is highlighted. | WAI-ARIA listbox pattern; Selector.highlightFollowsValue.test.tsx |
Allowed variation
- AV1 — Indicator rendering. A theme may replace the check indicator. A replacement that draws in both selected and unselected states keeps its mark space in both states; only resolved empty output collapses.
- AV2 — Option content.
renderOptionmay replace visible option content, while Selector keeps row role, selection, disabled state, navigation, and theming state. - AV3 — Selected value content.
renderValuemay replace the closed value display without changing its combobox identity, whether editable or read-only.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| closed with no value | Label and placeholder identify the field | Consumer placeholder text |
| closed with a value | Selected option is represented in the trigger | Custom renderValue content |
| pointer / popover | Anchored surface exposes the listbox without modal-dialog semantics | Default or explicit placement |
| compact coarse pointer | BottomSheet exposes a modal dialog containing the listbox | Default or explicit adaptive, or explicit bottom-sheet |
| searching | Visible options, keyboard navigation, and announced result count use one filter | Consumer search and empty text |
| loading | Trigger is busy; empty and no-results output is suppressed | Consumer loading duration |
| disabled with reason | Trigger remains focusable (spec:AST-085) and exposes the reason; activation stays blocked |
Consumer reason text |
| read-only | Value stays focusable and submittable; menu, clear, and disclosure affordances are absent | Value rendering, status, and busy presentation |
| selected/unselected rows | Empty marks consume no width; visible marks retain space at the logical edge | State-dependent label position/width and themed indicators |
Transformation and precedence order
- ORD1 — Option normalization precedes filtering and selection. Strings and option objects become one option shape before search, keyboard matching, rendering, and value comparison.
- ORD2 — Caller-selected content wins deliberately.
startIcontakes precedence over a selected option's icon; explicit placement takes precedence over selected-item overlay alignment.
Performance and resources
- PR1 — Search does not add effect-driven result-count renders. The next filtered count is derived from the input change and announced once for that query.
- PR2 — Geometry work is scoped to the open popover. Selected-item alignment may read browser layout while opening; it does not impose document-wide or persistent observation while closed.
Accessibility contract
- AR1 — Semantics follow presentation. The anchored presentation exposes a
listbox through a Popover and the trigger uses
aria-haspopup="listbox". The touch presentation exposes a modal BottomSheet dialog containing the listbox and the trigger usesaria-haspopup="dialog". In every presentation the listbox's accessible name is the field's label (label), not the trigger's value. WithhasSearch, the editable trigger is a button, and the search input owns the combobox. The closed trigger's accessible name is its label followed by the selected value's text. With nothing selected, that text is the placeholder. A calleraria-labeltakes the label's place in that name, and a calleraria-labelledbyoutranks it, as on the combobox shape. - AR2 — Focus follows the active interaction model. The anchored presentation
keeps the combobox relationship at the trigger/search control. The modal touch
presentation moves focus into its search control or listbox. On close, focus
returns to the trigger only when focus would otherwise be lost (
family:overlay-dismissalFR9); a close caused by moving focus elsewhere leaves focus there. - AR3 — Keyboard selection matches the visible set. Arrow, Home/End, typeahead, search, Enter, Escape, and Tab behavior operate on the options a person can currently perceive.
- AR4 — Read-only semantics match availability. A read-only value stays
focusable, retains
role="combobox", and exposesaria-readonly="true"plusaria-expanded="false". Its rendered content remains the combobox value. It does not exposearia-controls,aria-activedescendant, or an active selection surface. The implicit listbox popup describes the widget's selection capability; read-only state communicates that its value cannot currently change. Chromium's button-hosted combobox mapping omits the ARIA read-only property, so a localized accessible description also announces that state. Search and non-search modes use the same read-only combobox semantics because neither exposes a search control in this state. - AR5 — Active option perception. After keyboard input the active option
draws the shared focus ring inside its edge; the ring's color meets 3:1
against the listbox in light and dark (
spec:AST-020FR1, WCAG 2.2 1.4.11). After pointer input the active option keeps the overlay fill alone, as a focused DropdownMenu row does (component:DropdownMenuItemAR4).
Design relationships
No current design spec is linked.
| Anatomy or state | Current representation requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| selected mark and option spacing | Empty resolved marks collapse; visible marks retain space, so row label geometry may vary by state | spec:AST-004/DEC-1 |
supporting | FR3 |
| trigger variants | input reads as a form field; secondary matches adjacent secondary Buttons; ghost matches adjacent ghost Buttons |
component:Selector/DD1 |
form or peer action control | Public concepts |
The first row implements the state-derived spacing decision in
spec:AST-004/DEC-1.
Design decisions
| ID | Decision | Intent or reason | Applies to | Allowed variation |
|---|---|---|---|---|
| DD1 | A secondary Selector matches the visual role of adjacent secondary Buttons. |
A mixed toolbar or navigation area reads as one action hierarchy instead of making the Selector look like a form field or a ghost action. | The secondary trigger at rest and through its states | Themes may choose exact tokens while preserving parity with their secondary Button treatment. |
Theming anatomy
{
"Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},
"Trigger": {"target": "selector"},
"Icon-rendered start icon": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Caller-rendered start content": {
"none": {
"reason": "intentional: Arbitrary ReactNode content is caller-owned and receives no Selector target."
}
},
"Trigger clear button": {
"delegatesTo": {
"owner": "component:Field",
"target": "input-clear-button"
}
},
"Status icon": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Indicator icon": {"target": "selector-indicator-icon"},
"Search row": {"target": "selector-search"},
"Search icon": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Search clear button": {
"delegatesTo": {
"owner": "component:Field",
"target": "input-clear-button"
}
},
"Option row": {"target": "selector-option-row"},
"SelectorOption-rendered content": {"target": "selector-option"},
"Bare caller-rendered option content": {
"none": {
"reason": "intentional: Bare custom renderOption content is caller-owned and does not receive the SelectorOption target."
}
},
"Option selection indicator": {"target": "selector-check"},
"Option divider": {
"delegatesTo": {"owner": "component:Divider", "target": "divider"}
},
"Section heading": {"target": "selector-section-heading"},
"Empty state": {"target": "selector-empty-state"},
"Pointer popup": {"target": "selector-popup"},
"Touch sheet heading": {
"delegatesTo": {"owner": "component:Text", "target": "heading"}
},
"Touch sheet": {
"delegatesTo": {
"owner": "component:BottomSheet",
"target": "bottom-sheet"
}
}
}
Field is conditional: standalone Selector renders it, while InputGroup owns
that surrounding shell. Pointer popup and the two touch-sheet parts are
alternative presentations of the same panel content, not simultaneous anatomy.
Icon-rendered start content delegates to Icon; arbitrary ReactNode start content
is caller-owned. The default renderer and custom renderOption functions that
return SelectorOption retain its target; only bare caller-rendered option
content stays outside that target, while the targeted option row remains.
input-clear-icon is the shared canonical target for the clear glyph.
This map records only shipped reachability. It does not treat the accepted,
unimplemented option-source behavior in spec:AST-001 as current runtime behavior.
spec:AST-004 governs FR3's shipped indicator-space behavior without adding a
new theming target.
Family and system relationships
- The current architecture links in frontmatter own public API, theming, icon resolution, interaction modality, and Layer behavior used by Selector.
spec:AST-004/DEC-1owns FR3's shipped indicator-space behavior.spec:AST-011/DEC-1owns the additive read-only state: caller-owned policy can preserve a focusable, submittable value without exposing selection controls.family:input-fieldsowns family-wide state display, behavior, appearance, size, end-control, disabled-reason, and status-placement policy. Selector keeps its DEC-1 standalone inline-size exception; this component contract owns selection behavior inside that boundary.module:DropdownMenu/useMenuPressowns the listbox press model FR7 adopts (release-to-select, pointer-following highlight, outside-release split, stray-click swallowing); Selector keeps arrow clamping and its combobox focus (module AR2).
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR2, AR3 | Selector.test.tsx selection, focus, and keyboard suites, including "leaves focus on the field a press moved it to" and "returns focus to the trigger when the press lands on nothing focusable" |
closed/open, search/non-search, disabled option | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests | audit:Selector/behavior |
| FR2 | placement and selected-item geometry tests; SelectorKeyboardInset.a11y.chromium.spec.ts |
default, explicit, RTL, transformed entry, keyboard up | Using the wrong positioning model fails the expected position-area or margin | audit:Selector/behavior |
| FR3, AV1 | Focused Selector.test.tsx computed-display checks plus guarded Chromium Storybook matrix and stable visual stories |
popover/bottom sheet, narrow/wide, start/end, LTR/RTL, selected/unselected, check/radio | Empty output reserves width, visible output collapses, logical placement flips incorrectly, or row content overflows | audit:Selector/design-rendered |
| FR4, AR1, AR2 | presentation tests plus aria-haspopup source review |
pointer, compact coarse pointer, search/non-search | Wrong Popover/dialog roles or focus destinations fail tests; aria-haspopup values require source/a11y review |
audit:Selector/accessibility |
| AR1, AV2 | Selector.listbox.a11y.test.tsx and Listbox.a11y.chromium.spec.ts against the shared Listbox contract; SelectorListboxName.a11y.chromium.spec.ts and Selector.test.tsx "names the listbox with the field label, not the trigger that shows the value" for the listbox name; Selector.test.tsx "Selector with hasSearch: the closed trigger names the selection" for the button trigger's name; SelectorListboxName.a11y.chromium.spec.ts "the closed searchable trigger is named by the label and the selected value" for the accessibility tree |
popover/sheet, flat/grouped, selected/unselected, disabled, search, loading, custom RTL | A new or wider loss of role, listbox/option name, state, or ownership gates | audit:Selector/accessibility |
| FR5, FR6, AR1, AR2 (anchored), AR4 | Selector.combobox.a11y.test.tsx and Selector.combobox.a11y.chromium.spec.ts against the shared Combobox contract |
closed, open with active option, read-only, busy, bottom-sheet open, search input with active option | The trigger or search input loses its role/name/state or popup kind, its open popup or active option relationship breaks, or read-only exposes a selection surface; the bottom-sheet trigger's aria-controls naming the inner listbox remains exact known debt |
audit:Selector/accessibility |
| FR5 | loading, empty-state, and live-region tests | empty options, unmatched search, loading | Empty/no-results output appears or is announced while loading | audit:Selector/behavior |
| FR6, AR4 | read-only interaction, form, ARIA, and theme-state tests | search/non-search, clearable, open→read-only, disabled precedence | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent | audit:Selector/accessibility |
| FR7 | Selector.test.tsx press model suite |
finger release over another option, finger/mouse release outside, listbox marker | The press option is selected, the listbox takes focus, a finger release outside closes the list, or the stray click selects | audit:Selector/behavior |
| FR8 | Selector.openHighlight.test.tsx |
selected, none selected, disabled first and last options, selected option disabled, none enabled; ArrowDown, ArrowUp, Enter | An opening highlight on a disabled option, or off the enabled selected option, fails. | audit:Selector/accessibility |
| FR9 | Selector.searchHighlight.test.tsx |
typing after arrowing (ArrowDown to Cherry, then ap), typing then ArrowDown, a disabled only match, reopening after a search |
A highlight that names an option of the previous list, an Enter that picks an option the user did not highlight, or an ArrowDown that lands on a disabled option fails. | audit:Selector/accessibility |
| FR10 | Selector.highlightFollowsValue.test.tsx |
options reordered while open; options reloaded as new objects; the highlighted option removed (the next one follows); the last option removed (the previous one follows); a disabled option in the way; no old option left | A highlight that names a different option after the options change, lands on a disabled option, or survives with no old option left fails. | audit:Selector/accessibility |
| AR5 | Selector.activeOption.test.tsx: the ring after keyboard input, no ring after pointer input, the ring again when keyboard input follows a pointer highlight; the active option's indicator measured against the listbox in light and dark |
keyboard-active option, pointer-active option | Removing the ring, or drawing it after pointer input, fails; an indicator under 3:1 against the listbox in either mode fails (the fill alone measures 1.09:1 light and 1.15:1 dark) | audit:Selector/accessibility |
| source-build contract | Selector.source-build.test.mjs |
package source compiled by consumer Babel | Moving evaluated StyleX values outside the supported source form fails compilation | audit:Selector/code-health |
Decision log
FR3 implements the system decision owned by spec:AST-004/DEC-1.
DEC-1 — Default presentation is adaptive
Reference: component:Selector/DEC-1
Decider: cixzhang, 2026-10-06
An omitted presentation resolves adaptive (FR4): the modal bottom sheet on
compact coarse-pointer screens and the anchored popover elsewhere, so
fine-pointer and large-screen output matches popover. adaptive resolves
through spec:AST-094 FR13: a coarse primary pointer and the spec:AST-012 FR9
compact definition.
Rejected: keeping popover as the default, because a phone then gets a
pointer-sized anchored list unless the caller opts in.
Open questions
None.
Content boundary
This file does not copy the full prop reference, examples, current audit score, family proposals, or future implementation steps. Those remain with their existing owners.