Skip to content
menu palettetanreidark_modetranslate

Color mode

Contrast

Design system

Showcase systems imitate other design systems to show how far Tanrei can go. They are examples, not designs Tanrei supports.

Copy linkEdit theme
palettetanrei

Color mode

Contrast

Design system

Showcase systems imitate other design systems to show how far Tanrei can go. They are examples, not designs Tanrei supports.

Copy linkEdit theme
Getting startedWebReactSwiftUIJetpack ComposeFlutterReact NativePresetsYour own design systemUsing Tanrei with AI agentsBrandDesign tokensDesign systems and customizationTheme StudioColorTypographyIconsShapeElevationMotionInteraction statesBehaviourLayoutSize and densityAccessibilityWordsColor tokensTypescale tokensShape tokensElevation tokensMotion tokensState tokensSpace and measure tokensComponentsButtonMain action buttonSegmented buttonShipped by cupertino, m3-likeButton groupButton with menuToolbarCopy buttonCheckboxRadio buttonSwitchChipMenuSliderSlider fieldCalendarDateTimePickerField groupRadio groupCheckbox groupSelectSelect fieldMenubarFile uploadFile picker AdvancedDrop zoneRatingText input AdvancedText fieldChip fieldFieldComboboxCombobox fieldNumber input AdvancedNumber fieldColor input AdvancedColor fieldOne-time-code input AdvancedOne-time-code fieldEmbedded text input AdvancedChat composerCardDividerModal layer AdvancedDialogListList rowBottom sheetSide sheetCarouselCode blockTablePopoverStepsAccordionDescription listFigureApp shellPage headerTree viewTimelineImage previewHandleResizable frameSplit viewScroll areaSize transitionBadgeProgress indicatorMeterNumber tickerLoading indicatorSnackbarTooltipKeyboard shortcutTagInline codeCalloutAvatarEmpty stateTag groupSkeletonFile itemSwatchMarquee textTabsTab viewApp barNavigation barNavigation drawerSearchLinkPaginationPrevious and next linksStepperBreadcrumbsTable of contentsLink cardFAB menuShipped by m3-likeStatusHow Tanrei is builtContributingLicense and attribution
HomeComponentsCombobox

Combobox

The box people type in to find one value or several, and the list of options it opens — without a label row, help or error text of its own. For a place whose label stands elsewhere, or inside a field a product composes itself.

content_copyView as Markdown

Advanced

Most products place Combobox field, which this component is a part of.

Category
Text inputs
Tokens
comp.combobox
Level
Base

Overview

Web
tanrei-combobox
schedule
SwiftUI
TanreiCombobox
radio_button_unchecked
Jetpack Compose
TanreiCombobox
radio_button_unchecked
Flutter
TanreiCombobox
radio_button_unchecked
React Native
Combobox
radio_button_unchecked
Variants not shipped in
tanrei: filled, outlined

Generated from docs/status/status.json, specs/combobox.spec.json

Bare: a filter in a toolbar, and a row whose label stands beside its combobox

searchprimarysecondarysurface
Time zoneTokyoLisbonBerlin

A combobox is the control of a combobox field, alone: the box, the text typed in it, the leading glyph, the clear button and the chevron, and the list with its options, groups and status row. It has no label row above it, and no help and no error text below it.

Use it bare where the label a person reads stands somewhere else:

Where The label a person reads The combobox’s label
A filter in a toolbar The placeholder and the glyph say what it does What it finds: “Find a token”
A cell of a table The column’s header The column and the row: “Assignee, release notes”
A row whose label stands beside the box The text beside it The same words

Bare, the combobox needs a label of its own. It is the accessible name, of the input and of the list. A stacked combobox never draws it; a filled or an outlined one draws it as the label that floats in the box.

It is an advanced component: the bare control, for a product that composes its own. Most forms want the combobox field, which is this combobox inside a field, ready to use.

Used in the combobox field. To frame it yourself, put it in a field, which names it, describes it, marks it required and puts it in its error condition.

It is a block as wide as the place it is put in, bare and framed alike. It has no width of its own, and its width never follows its options or its value: for a narrower box, give it a narrower place.

On the web it is <tanrei-combobox> with <tanrei-option> children, the elements a select holds. The other platforms have not implemented it yet.

Usage

<!-- A filter in a toolbar: the toolbar gives it its width. No chevron: its suggestions exist only for what was typed. -->
<tanrei-combobox id="token" label="Find a token" placeholder="Find a token" no-chevron filter="none"
  style="inline-size: 16rem">
  <span slot="leading-icon">search</span>
</tanrei-combobox>

<!-- A cell of a table: the column's header is the visible label. -->
<td>
  <tanrei-combobox name="assignee-release-notes" label="Assignee, release notes" value="aiko">
    <tanrei-option value="aiko">Aiko Tanaka</tanrei-option>
    <tanrei-option value="bao">Bao Nguyen</tanrei-option>
  </tanrei-combobox>
</td>

<script type="module">
  import '@tanrei/web/components/combobox';

  const token = document.querySelector('#token');
  // The person changed the text: you filter, and give the options back.
  token.addEventListener('input', async () => {
    const found = await find(token.inputValue);
    token.replaceChildren(token.querySelector('[slot="leading-icon"]'), ...found.map(option));
  });
  // The committed value changed. The value is already the new one.
  token.addEventListener('change', (e) => open(e.detail.value));
</script>
// An advanced component — a building block of others — is imported from the advanced entry.
import { Combobox, Option } from '@tanrei/react/advanced';

<Combobox label="Assignee, release notes" value={assignee} onChange={(event) => setAssignee(event.detail.value)}>
  <Option value="aiko">Aiko Tanaka</Option>
  <Option value="bao">Bao Nguyen</Option>
</Combobox>

What happens in the box and in the list is the same bare, framed and in a combobox field, and is described once, on the combobox field’s page: the list, and typing, moving and choosing.

In a field, by hand

A field around a combobox is a combobox field written out. Leave the combobox’s own label empty: the field names it. label, error, disabled and the requirement are said on the field; name, value, the options and everything about typing on the combobox.

<tanrei-field label="City" required required-text="Required"
  supporting-text="Where the order is sent.">
  <tanrei-combobox name="city" value="tokyo">
    <tanrei-option value="kyoto">Kyoto</tanrei-option>
    <tanrei-option value="tokyo">Tokyo</tanrei-option>
  </tanrei-combobox>
</tanrei-field>

A field with a combobox in it: the same picture as a combobox field

KyotoTokyo

The combobox tells its field what only it knows. Its help starts where the text starts, past the padding and a leading glyph. A filled or an outlined combobox draws the field’s label itself, floating in the box, so the field draws no label row. And while its list is open it is drawn focused, so the field’s label and help are drawn focused with it, whether or not the input has focus.

A press on the field’s label moves focus to the input and opens nothing. While the list is open the label is outside the combobox: the press closes the list, and focus stays in the input.

Several values

Set selection to multiple and the combobox holds values: any number of its options, in the order they were chosen. Each chosen value stands in the box as a chip, before the text, and the box grows by whole lines as the chips wrap. None is hidden behind a count. The text is then only what the person types to find an option.

Several values: the chosen cities as chips, and a list that still filters

KyotoLisbonNairobiTokyoToronto
<tanrei-field label="Cities">
  <tanrei-combobox name="cities" selection="multiple" values='["kyoto", "lisbon"]'
    remove-label="Remove {entry}" added-text="{entry} added" removed-text="{entry} removed">
    <tanrei-option value="kyoto">Kyoto</tanrei-option>
    <tanrei-option value="lisbon">Lisbon</tanrei-option>
    <tanrei-option value="nairobi">Nairobi</tanrei-option>
    <tanrei-option value="tokyo">Tokyo</tanrei-option>
    <tanrei-option value="toronto">Toronto</tanrei-option>
  </tanrei-combobox>
</tanrei-field>

<script type="module">
  const cities = document.querySelector('[name="cities"]');
  // A value was added or removed. `values` is already the new array.
  cities.addEventListener('change', (e) => save(e.detail.values));
</script>
The person What happens
Presses an option, or presses Enter on the active one Its value is added at the end, or taken out where it is already chosen. The text empties, every option shows again, and the list stays open for the next choice.
Types an option’s whole label and presses Enter That option is added. With allowCustomValue, any other text becomes a value of its own.
Presses Backspace, or the arrow toward the start of the line, with the caret at the start of the text Focus moves to the last chip. Nothing is removed yet.
On a chip, presses an arrow, Home or End Focus moves among the chips; past the last, back to the text. Escape and Tab go back to the text.
On a chip, presses Backspace or Delete, or its remove button That value is removed, and focus moves to the chip beside it, or to the text.
Presses a chip Focus goes to the text, and the list opens on that chip’s option.
Leaves the field, or presses Escape while the list is closed The typed text empties. Nothing is chosen, and no value is removed.

The list stays open after a choice, because a person who chooses several usually chooses them in a row. It closes with Escape, with the chevron, with a press outside, or when focus leaves. Backspace moves to the last chip before it removes anything, as in the chip field: the key does the same in both fields, and nothing is removed that the person has not seen first.

In a form it submits one entry for each value under its name, as a <select multiple> does, and none while nothing is chosen. A required field around it asks for at least one value.

The chips are chips of the input kind, drawn from the chip’s tokens. The space between them is comp.combobox.entries.*, which follows the text input’s entries unless a design system sets it apart.

Specs

Bare comboboxes: in error, disabled, read-only, clearable, and large

NairobiTokyoNairobiTokyoNairobiTokyoNairobiTokyoNairobiTokyo

Filled and outlined bare: the combobox's own label floats in the box

NairobiTokyoNairobiTokyo
Under m3-like

What is the combobox’s, and what is the field’s

Aspect The combobox The field around it
Draws The box, the text, the placeholder, the leading glyph, the clear button and the chevron, the list with its options, groups and status row, and the label that floats in a filled or an outlined box The label row above a stacked combobox, the required or optional mark, the help, the error text
Holds The value, the text, whether the list is open, its place in a form, the events Nothing
Says to assistive technology That it is a combobox with a list, expanded or not, and which option is active The name, the help or the error text, required, invalid, disabled

The three variants and the three sizes, small (32), medium (40) and large (56), are the text input’s: a combobox and a text input side by side share every line. The default system ships stacked only.

Bare, without a field

  • The name is label. labelHidden stops a filled or an outlined combobox from drawing it.
  • An error is error, which you set: the box is drawn in its error condition and exposed as invalid. The combobox has no error text. Say what is wrong in words beside it, or frame it.
  • Required is a field’s to say. A bare combobox has no requirement setting: where the form needs an answer, validate it yourself.
  • A text that names no option is given up when the person leaves, unless allowCustomValue is set. It is never an error of the combobox’s own.

Moving through the list

The arrow keys go round at the ends of the list: Down Arrow on the last option goes to the first, and Up Arrow on the first to the last. With allowCustomValue the text itself is a stop between them, where no option is active and Enter keeps what was typed. Set wrap to false to stop the keys at the ends. The page keys never go round.

Glyphs in the list

An option’s glyph stands in a column before its label. iconSpace says where that column is kept in an option without a glyph. auto (the default) keeps it in a section where another option has a glyph, so that the labels of the section start on one line, and keeps none in a section without glyphs; a section is a group, or a run of options outside any group. always keeps it in every option, and never only in an option that has a glyph. The menu has the same iconSpace, with the same values and default. Only the options the filter shows count.

The options take the combobox’s size. A small combobox opens small options (36 high with 20 glyphs, the menu’s small row), and a medium or large one medium options, at the control height (40 high in the default system). The text keeps its size, and an option is never lower than the target.

Anatomy

Anatomy

Drawn over the fixture stacked-empty, as the web package draws it.
Part Description
1 container The combobox's box: it holds the leading glyph, the input, the clear button and the chevron on one line, and while selection is multiple the chosen values before the input, in lines that wrap. It measures and is drawn as the text input's container of the same variant and size, carries the hover state layer and shows focus by its edge. It is the list's anchor.
2 outline · optional The border of an outlined combobox, which opens a gap where the floated label crosses it; in a stacked one, the line drawn inside the container's edge while it is focused or in error, which takes no layout space.
3 active-indicator · optional The line along the bottom of a filled combobox; its focused state is thicker and colored.
4 label · optional In a filled or outlined combobox, its name drawn inside the box: it rests in the input line while the input is empty and not focused, and floats otherwise. A stacked combobox draws none: the label above it is the row of the Field that frames it.
5 required-asterisk · optional After the floating label's text, an asterisk, where the Field that frames the combobox says the control is required and marks it (CMB-7). Kept from assistive technology.
6 entry · optional While selection is multiple: one chosen value, drawn as an input Chip — its label and its remove action — in the container before the input, the entries and the input standing in lines that wrap.
7 input The text, in the platform's native text element: what the person types to find an option, and, when they are not typing, the chosen option's label or the custom value. While selection is multiple it holds only what the person types.
8 placeholder · optional A hint shown while the input is empty; never a label and never a value.
9 leading-icon · optional A glyph at the start of the container: the one the product gives the combobox, or else the chosen option's own.
10 clear-button · optional An icon-only Button of the text variant showing close, before the chevron, that empties the text and the value. Drawn while clearable is true and the text is not empty.
11 chevron · optional The glyph expand_more at the end of the container: it says that the field has a list that can be looked through, and a press on it opens and closes the list. Drawn from the trailing-icon part of the tokens; it does not turn, is never mirrored and is not a focus stop.
12 list The floating surface that holds the options: the sheet a menu and a select's list are drawn on, placed under the container, exactly as wide as it, scrolling when its rows do not fit.
13 option One choice: a row of the list. It carries hover, the active highlight and press and, while it is the chosen one, the quiet selection's fill.
14 option-label The option's text, its accessible name and what the input shows once the option is chosen. The part of it that matched the typed text is drawn heavier.
15 option-supporting-text · optional A line below an option's label that says more about the choice. It is shown in the list only and is not searched.
16 option-leading-icon · optional A glyph before an option's label. Its column is kept in every row of a list where any shown option has one.
17 mark · optional The glyph check at the end of the chosen option's row, in a box kept at the end of every row. With the row's fill it shows the choice; the fill never shows it alone.
18 group · optional A run of related options (an option group), optionally under a title, separated from what is next to it by a divider or by a gap.
19 group-title · optional The heading above a group's options. It names the group, takes no focus, is not a choice and is not searched.
20 divider · optional The hairline between two groups while the separation is divider. Under gap there is none.
21 status · optional A row after the options that says what the product's source is doing — a loading indicator, a count, a failure — or, where the component filters, that nothing matched. Not an option.
22 focus-ring Gap-then-ring indicator inside an option's row while the option is the active one by the keyboard. The container itself draws no ring: its focused edge is its focus indicator.
23 caret The text cursor, colored by the caret part of the variant.

Measurements

Measurements

Length Token Value (px)
container padding-inline tanrei.comp.input-box.container.padding-inline.medium 16
container height tanrei.comp.input-box.container.height.medium 40
option height tanrei.comp.combobox.option.height.medium 40
Drawn over the fixture stacked-empty, as the web package draws it.

Properties

Property Type Default Description
variant stacked | filled | outlined "stacked" The text input's three looks, so that a combobox is drawn as the text inputs beside it: stacked is a filled box that shows focus and error with a line inside its edge and draws no label of its own; filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values.
size small | medium | large "medium" Minimum height of the container: stacked 36 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them; all under the default system, and never drawn below sys.target.minimum. These are the text input's three sizes, small for a bar, a toolbar or a dense row of controls. The size the box is drawn at, its own or its container's, is also the size of the options of the list it opens (CMB-68): a small box opens small rows, and a medium or a large box medium ones. The hit area always meets the minimum target. A design system may add values. While it is not set the combobox draws the size its nearest container sets — a toolbar's size — and medium where none does (CMB-83); setting it, to medium too, makes it the combobox's own.
selection single | multiple "single" Whether one value is chosen or any number. single: one value, held in value and shown as the text of the input; a choice closes the list. multiple: any number, held in values in the order they were chosen and each drawn as an input Chip in the box before the input, which then holds only what the person types; a choice adds or removes one and the list stays open (CMB-70, CMB-71).
value string "" The committed choice while selection is single: the chosen option's value, or, with allowCustomValue, a text the person typed that names no option. Empty while nothing is chosen. Ignored while selection is multiple, whose chosen values are values.
values strings The chosen values while selection is multiple, in the order they were chosen: each an option's value or, while allowCustomValue is true, a text the person committed that names no option; no two are the same. A list of strings (the platforms take an ordered list). The combobox writes it as the person chooses and removes, and emits change; the product may also set it. Ignored while selection is single.
inputValue string "" The text in the input. The combobox writes it as the person types and, while selection is single, when a value is chosen or restored; while selection is multiple it is only what the person types to find an option, emptied by each choice. The product may set it, and reads it from input to load options.
label string "" Names the combobox, its list and its chevron's button for assistive technology where no Field frames it; a filled or outlined combobox also draws it, as the label that floats in its box. Inside a Field leave it empty: the Field's label names the combobox, and is what floats.
labelHidden boolean false Does not draw the floating label of a filled or outlined combobox, which stays the accessible name. Inside a Field, hide the label on the Field. A stacked combobox draws no label, so this changes nothing there.
placeholder string "" A hint shown while the input is empty and no label is in the input line. Never a replacement for a name. Not shown while selection is multiple and a value is chosen (CMB-80).
error boolean false Draws the combobox in its error condition and exposes it as invalid. A Field sets it from its own error; set it here only where no Field frames the combobox. What a value means is the product's to validate; the combobox never sets this itself, for a missing required value either.
disabled boolean false Prevents focus, editing and form submission. Inside a Field, disable the Field, so that its label follows.
readOnly boolean false The value is shown, can be focused, selected and copied, and is submitted, but cannot be changed: the list does not open and neither the chevron nor the clear button is drawn.
open boolean false Whether the list is shown. The combobox opens and closes itself and emits toggle; the product may also set it (to open on focus, for one). Ignored while the combobox is disabled or read-only or has nothing to show.
allowCustomValue boolean false False: the value is always one of the options, and a text that names none is given up when the person leaves. True: the options are suggestions, and a text that names none becomes the value as typed (a font family, a tag, an address).
filter contains | none "contains" Who decides which options answer the text. contains: the combobox shows the options whose label contains what was typed, ignoring case, and marks the match. none: the combobox shows every option it is given and the product filters — on input, from its own data or a server — and says what it is doing with status.
wrap boolean true Whether the arrow keys go round at the ends of the list: Down Arrow on the last option to the first, Up Arrow on the first to the last — with allowCustomValue true, through the text itself, where no option is active (CMB-26). False stops them at the ends.
chevron boolean true Draws the chevron that opens the whole list without typing. False for a field whose suggestions exist only for what was typed (a remote search): there is no list to look through.
clearable boolean false Draws a clear button while the text is not empty, for a combobox whose value may be none. Without it, emptying the text and leaving the field clears the value. While selection is multiple it also removes every chosen value, and is drawn while the text or values is not empty (CMB-77).
clearLabel string "" The clear button's accessible name, in the product's language ("Clear"). Required while clearable is true.
status idle | loading | error "idle" What the product's source of options is doing, which the product sets: idle (the options given are final), loading (options are on their way: the status row shows a loading indicator), error (the source failed: the status row shows statusText in the error color).
statusText string "" The status row's text, in the product's language, announced to assistive technology when it changes: a count ("12 of 340 shown"), that loading failed, or, while status is loading, the loading indicator's name ("Loading options").
emptyText string "" Shown in the list while the text names nothing the combobox can show, allowCustomValue is false and no status is set, in the product's language ("No matches"). The product's: Tanrei has no words for it. Empty reads the product's words; with neither, no such row is drawn and it is reported (CMB-32).
separation auto | divider | gap "auto" How a group of options is told from what is next to it. divider: a line between them. gap: empty space and no line. Auto takes comp.combobox.separation, which follows the design system's choice.
iconSpace auto | always | never "auto" Whether a shown option keeps the room of the leading icon column where it has no icon, so that the labels of a section start on one line — a section being the shown options of a group, or a run of adjacent shown options outside any group. auto: an option keeps the column while another shown option of its section has a leading icon; an option the filter hides does not count. always: every option keeps it. never: only an option that has an icon has the column. The menu's and the select's iconSpace, with the same values and default (CMB-67).
removeLabel string "" While selection is multiple, the accessible name of each chosen value's remove action. The product writes the whole name in its own language and marks one place in it, {entry}, which the combobox fills with that value's label ("Remove {entry}", "{entry}を削除"), because two remove actions must be told apart (CHP-18). Empty reads the product's words. Required while a value is chosen: with neither, the action is drawn, works, has no name, and that is reported (CMB-79).
addedText string "" While selection is multiple, the sentence assistive technology is told when the person chooses a value, with the place {entry} filled by its label ("{entry} added", "{entry}を追加しました"). Empty reads the product's words; with neither, nothing is said and that is reported (CMB-79).
removedText string "" While selection is multiple, the sentence assistive technology is told when the person removes a chosen value, with the place {entry} filled by its label ("{entry} removed"). Empty reads the product's words; with neither, nothing is said and that is reported (CMB-79).

Slots

Slot Description
leading-icon A glyph at the start of the container that stands for the combobox whatever is chosen (a magnifier before a field that searches people). It takes the place of the chosen option's own glyph.

Events

Event Description
input The person changed the text (typing, deleting, pasting, dictating, the clear button, Escape restoring or, while selection is multiple, emptying it); carries the new text. Not emitted when the product sets inputValue, value or values, when a choice writes its label or, while selection is multiple, empties the text, or when leaving empties it. It is the product's cue to load options; the combobox does not delay or drop it.
change The committed value changed by the person: an option was chosen, a custom text was committed, or the value was cleared; carries the new value and the text now shown. While selection is multiple: a value was added or removed — by an option, a committed text, an entry's removal or the clear button — and it carries the new values. Not emitted when the product sets value or values, when the chosen option is chosen again while selection is single, or while the person only types or moves through the list.
toggle The list was opened or closed by the person or by having nothing left to show; carries the new open and, for a close, the reason: select, commit, escape, back, outside, press, tab, focus-out, anchor-hidden or empty (in the platform's casing). After a choice it follows change. While selection is multiple a choice does not close the list, and no toggle follows it.
action The person pressed Enter with no option active and the text was committed; emitted after any change it caused. On the web it is followed by the form's submission unless cancelled. While selection is multiple only an Enter on an empty text commits nothing and emits it (CMB-72).

Items

The kinds of item the component repeats. A fixture lists its items in order; each platform names each kind in its own idiom.

option

One choice of the combobox: a label, the value it stands for, and optionally a supporting line and a glyph. The same kind a select holds.

Property Type Default Description
label string "" The option's text and its accessible name: what the filter searches and what the input shows once the option is chosen. Required.
value string "" Identifies the choice: the option is the chosen one while the combobox's value equals it. Unique within the combobox and not empty: the empty value means that nothing is chosen.
supportingText string "" A line below the label that says more about the choice. Shown in the list, not in the input; not searched.
leadingIcon string "" The name of an icon (a glyph of the system's icon set) before the label; the container shows it too while the option is chosen and the combobox has no leading icon of its own.
disabled boolean false Prevents the option from being chosen. It stays reachable with the arrow keys.
Spec Web SwiftUI Jetpack Compose Flutter React Native
Item tanrei-option TanreiComboboxOption TanreiComboboxOption TanreiComboboxOption ComboboxOption
label · Property label title text label label
value · Property value tag value value value
supportingText · Property supportingText supportingText supportingText supportingText supportingText
leadingIcon · Property leadingIcon leadingIcon leadingIcon leadingIcon leadingIcon
disabled · Property disabled disabled enabled enabled disabled
Notes <tanrei-option value="tokyo">Tokyo</tanrei-option>: the element a select holds, and the same data: the label is the label attribute or, without one, the element's text. Attributes supporting-text, leading-icon, disabled. data-mirror (auto, the default; always; never) on an option is the product's word on mirroring the glyph its leading-icon names, in the list and in the container (CMB-54), as on a glyph the product places itself. It draws nothing itself. tanrei-option and tanrei-option-group are one pair of elements for the select and the combobox, defined once; an option with the empty value is refused by the combobox (CMB-17, CMB-57), not by the element, because a select allows it. TanreiComboboxOption(_ title:, supportingText:, leadingIcon:).tag(value); disabled follows .disabled(_:). TanreiComboboxOption(text, value, supportingText, leadingIcon, enabled), called in the combobox's content lambda. TanreiComboboxOption<String>(value:, label:, supportingText:, leadingIcon:, enabled:), in the combobox's options list, as DropdownMenuEntry. { label, value, supportingText?, leadingIcon?, disabled? }: an element of the options array.

option-group · group — holds items

A run of related options, optionally titled. The combobox separates a group from what is next to it by a divider or a gap, and draws neither a group nor its title while the filter leaves it empty.

Property Type Default Description
title string "" A short heading drawn above the group's options, which also names the group; empty draws none and leaves the group unnamed.
Spec Web SwiftUI Jetpack Compose Flutter React Native
Item tanrei-option-group TanreiComboboxSection TanreiComboboxGroup TanreiComboboxGroup ComboboxOptionGroup
title · Property label title title title title
Notes The title is the label attribute, as <optgroup label>: a title attribute would also draw the browser's tooltip. TanreiComboboxSection(_ title:) { … }, as Section. TanreiComboboxGroup(title) { … }. TanreiComboboxGroup(title:, options: […]), in the same list. { kind: 'group', title?, options: ComboboxOption[] } in the same array.

States

Behavior

Requirements in EARS form. Every platform implementation is tested against these ids.

ID Requirement
CMB-1 THE combobox SHALL draw its container at least comp.input-box.stacked.container.height.medium tall WHILE variant is stacked (or a variant a design system adds, which is drawn as a stacked box) and at least comp.input-box.container.height.medium tall WHILE variant is filled or outlined, for size medium (and so on for each size), with a stacked or outlined combobox's four corners and a filled one's top corners rounded by comp.input-box.container.shape, a filled one's bottom corners by comp.input-box.container.shape-bottom, all eased by sys.shape.corner-smoothing, and SHALL lay out in it one row, centred vertically: the leading glyph where there is one (CMB-18), the input taking the remaining width (CMB-16, CMB-17), then the clear button WHILE it is shown (CMB-20) and the chevron WHILE it is drawn (CMB-19), comp.combobox.container.action-gap apart, the first of those two comp.input-box.container.gap.medium after the input and the leading glyph that far before it (and so on for each size). Text SHALL be comp.input-box.container.padding-inline.medium from the container's edge and a glyph comp.input-box.container.padding-inline-with-icon.medium, and the input line SHALL have at least comp.input-box.stacked.container.padding-block.medium above and below it in a stacked box and comp.input-box.container.padding-block.medium in a filled or an outlined one (and so on for each size).
CMB-2 THE combobox SHALL measure as the text input of the same variant and size measures (TXI-16): the same container height, paddings and corners, and the same text style and start edge for its input text, so that a combobox and a text input side by side share every horizontal line and a combobox below a text input shares its start edges; framed by a Field each, they share the label row and the supporting row as well, because those rows are the same Field's (FLD-1, FLD-26). THE combobox SHALL be drawn, in every state, plain and in error, with the colors the text input of the same variant has for the parts of the same name. The two are drawn from one set of tokens (CMB-63): what a layer changes of the box, it changes for both.
CMB-7 WHERE variant is filled or outlined, WHILE the floating label is drawn (CMB-8) and the Field that frames the combobox gives it an asterisk as its required mark (FLD-25) THE combobox SHALL draw the character "*" after the label's text, comp.input-box.requirement.asterisk-gap from it, in the label's text style and at the label's place, resting and floated with it, in the required-asterisk color of its variant (comp.input-box.outlined.required-asterisk.color for an outlined combobox; comp.input-box.outlined.error.required-asterisk.color WHILE the combobox is in error), and SHALL keep it from assistive technology, because the required state already says it (CMB-12). It SHALL draw no tag and no optional label: which mark a required control gets is the Field's to say (FLD-6), and a tag named there reaches a floating label as the asterisk. WHILE no Field frames it, or the Field gives no mark, or the label is not drawn, THE combobox SHALL draw no mark.
CMB-8 WHERE variant is filled or outlined and the label is drawn THE combobox SHALL rest the label in the input line, in comp.input-box.label.typescale.medium for size medium (and so on), WHILE the input is empty and not focused, and otherwise float it as the text input of that variant floats its label (TXI-13): to the top of a filled container, above the input line, or onto an outlined container's top edge with a gap of comp.input-box.outline.notch-padding in the outline on each side of it, in comp.input-box.label.floated-typescale.medium for size medium (and so on); a filled combobox that draws its label SHALL be at least twice comp.input-box.container.padding-block-with-label.medium plus one line of each of those two text styles tall (and so on for each size), so that it does not change height when the label floats. WHEN the label floats or rests THE combobox SHALL move and resize it over comp.input-box.motion.label-duration with comp.input-box.motion.label-easing, and at once where motion is reduced. The label SHALL wrap rather than be cut and SHALL never be drawn over the input text. The label it floats SHALL be its accessible name (CMB-12): the label of the Field that frames it, or its own label where none does. WHILE labelHidden is true — its own, or that Field's (FLD-25) — or it has no name THE combobox SHALL draw no label. WHERE variant is stacked, or a variant laid out as stacked (CMB-56), THE combobox SHALL draw no label at all: the label above it is the Field's row (FLD-2). WHILE the input is empty THE combobox SHALL show placeholder, in the placeholder color of its variant (comp.input-box.stacked.placeholder.color), only while no label is in the input line — the label is floated, is not drawn, or stands above in the Field's row — so that the two never overlap.
CMB-10 WHILE error is true — set by the product, or by the Field that frames it (FLD-8) — THE combobox SHALL draw every part of its container, in every state, from the error parts of its variant (comp.input-box.stacked.error.outline.color and the other error. parts), so that the box itself is marked and not only a text below it: a stacked combobox draws, at rest, a line of comp.input-box.outline.width in comp.input-box.stacked.error.outline.color inside its container's edge, following its corners and taking no layout space, and a filled or outlined one draws its floating label from its error part as well. It SHALL expose itself as invalid to assistive technology. Its list and its options SHALL stay as they are drawn. THE combobox SHALL never set error itself — what a value means is the product's to validate — and SHALL show no error text of its own: the words that say what is wrong are the errorText of the Field that frames it, which that Field draws and gives the combobox as its description (FLD-7, FLD-11).
CMB-12 THE combobox SHALL take its name, its description and its required state from the Field that frames it, as every control a Field frames does (FLD-10, FLD-11): the Field's label is the accessible name of its input, whether or not any label is drawn, and the Field's supporting text with, in error, the error text after it its description. WHILE label is not empty THE combobox SHALL use it as the accessible name instead, for a combobox no Field frames or one whose visible label is elsewhere. It SHALL never use placeholder as the name, WHILE it has either name THE combobox SHALL expose that one alone, over a name the product gives it on the element (aria-label or aria-labelledby); and WHILE it has neither name and the product gives it a name of its own on the element — aria-label, or aria-labelledby naming an element — THE combobox SHALL expose that name as its accessible name; IF it has none of the three it SHALL still render and work, and in debug builds SHALL report that it has no accessible name. The same name SHALL name its list and its chevron's button (CMB-19, CMB-48). WHILE its Field says it is required THE combobox SHALL expose the required state to assistive technology (and, on the web, a missing value to the form's constraint validation, CMB-59), whichever mark is drawn and where none is; it has no requirement setting of its own and SHALL NOT validate because of one.
CMB-14 WHEN the user presses its floating label, a decorative leading glyph or the container's padding THE combobox SHALL move focus to its input and do nothing else: it SHALL NOT open its list or change its value, and SHALL draw no press answer, because a press on a field is not an action; a press on the label row of the Field that frames it does the same by FLD-12. WHERE the container is shorter than the minimum target THE combobox SHALL extend its hit area vertically to sys.target.touch for touch input and sys.target.pointer for fine pointers, without changing its visual size; a platform that cannot tell the input type SHALL use sys.target.touch. THE combobox SHALL add one stop to the focus order, its input; the clear button, while it is shown, is a second (CMB-20), and the chevron and the options are none.
CMB-15 WHILE hovered or focused THE combobox SHALL render its container, active indicator, outline, floating label and the asterisk after it, input, placeholder, leading glyph and chevron, caret and opacity, and the widths of its outline and active indicator, from the component tokens of the highest-precedence active state, with precedence focused over hovered (their error parts WHILE error is true); unlike a button, focus gained by pointer or touch SHALL select the focused state, because a field shows where typing will go however it was focused; WHILE its list is open THE combobox SHALL stay in the focused state. THE combobox SHALL show focus by its focused tokens and SHALL NOT draw the focus ring: the focused active indicator or outline is its focus indicator, and a stacked combobox draws it as a line of its focused outline width, in the focused outline color of its variant, inside the container's edge, following its corners and taking no layout space, so that nothing in the container moves as the line appears, thickens or goes; WHERE sys.behavior.focus-style is glow it SHALL also draw the glow around the container while focused. A hovered stacked combobox SHALL show the state layer on its container and draw no edge. Selected text in the input SHALL be highlighted in comp.input-box.selection.color and drawn in comp.input-box.selection.content.color in every variant and state. WHEN its state, error or disabled changes THE combobox SHALL change its colors and widths over the state duration of its size (comp.input-box.motion.state-duration.small, .medium or .large) with comp.input-box.motion.state-easing, and at once WHERE motion is reduced. The rows of the Field that frames it are drawn focused with it — while focus is inside, and for as long as its list is open (FLD-13, CMB-61).
CMB-16 THE combobox SHALL take what the person types in the platform's native text element, on one line, with a general keyboard and without autocorrection, and SHALL follow the text input's rules for it: WHEN the person changes the text — by typing, deleting, pasting, cutting, dictating or an input method committing text — it SHALL emit input once per change with the new text, and none WHEN the product sets inputValue or value or WHEN the combobox itself writes the text of a choice (TXI-1). WHILE an input method is composing THE combobox SHALL leave the composition to the native element (TXI-4): it SHALL NOT write into the element, SHALL NOT choose, commit or clear, and SHALL leave Enter, Escape, the arrow keys and the page keys to the input method, whose own candidates they move through and confirm; it SHALL filter by the text the element reports during a composition (CMB-25) and SHALL make no option active because of it (CMB-26). THE combobox SHALL draw the text in comp.input-box.input.typescale.medium for size medium (and so on) and the input color of its variant (comp.input-box.stacked.input.color), scrolling it sideways inside the input when it is longer, and its caret in the caret color of its variant (comp.input-box.stacked.caret.color).
CMB-17 THE combobox SHALL hold two things and never confuse them: value, the committed choice, and inputValue, the text in the input. WHILE the person is not editing — the text was not changed since the last commit — THE combobox SHALL show as its text the label of the option whose value equals value; WHILE value names no option it SHALL show value itself WHERE allowCustomValue is true and an empty input otherwise, in which the placeholder shows as CMB-8 says. An option whose value is the empty string cannot be chosen: the empty value means that nothing is chosen. THE combobox SHALL change value only by a choice (CMB-27), a commit (CMB-28, CMB-29) or the clear button (CMB-20), never while the person only types or moves through the list.
CMB-18 WHILE the leading-icon slot holds a glyph, or WHILE it holds none and the chosen option has a leadingIcon and the person is not editing, THE combobox SHALL draw that glyph at the start of its container at comp.input-box.icon.size.medium for size medium (and so on), with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, in the leading-icon color of its variant (comp.input-box.stacked.leading-icon.color), hidden from assistive technology. The slot's glyph stands for the field whatever is chosen and takes the place of an option's own.
CMB-19 WHILE chevron is true and readOnly is false THE combobox SHALL draw the glyph expand_more of the system's icon set at the end of its container, at comp.input-box.icon.size.medium for size medium (and so on), in the trailing-icon color of its variant (comp.input-box.stacked.trailing-icon.color; comp.input-box.stacked.error.trailing-icon.color WHILE error is true): it says that the field has a list that can be looked through without typing. The chevron SHALL NOT turn while the list is open and SHALL never be mirrored. Its hit area SHALL reach from the container's end edge to the input's end and over the container's whole height, and be at least sys.target.touch wide for touch input and sys.target.pointer for fine pointers; WHEN the person presses it THE combobox SHALL open its list WHILE it is closed (CMB-21) and close it WHILE it is open (CMB-30), keep or move focus to the input, and draw no press answer, because the press is answered by what it opens. The chevron SHALL NOT be a focus stop — Down Arrow does its work — and SHALL be exposed to assistive technology as a button named as the combobox is (CMB-12), with its expanded state. WHILE chevron is false THE combobox SHALL draw none and its list SHALL open by typing and by the arrow keys alone: the form for a field whose suggestions exist only for what was typed.
CMB-20 WHILE clearable is true, the input's text is not empty, and the combobox is neither disabled nor read-only THE combobox SHALL draw a clear button before the chevron: an icon-only Tanrei Button of the text variant at Button's small size showing the glyph close of the system's icon set, not mirrored, named by clearLabel, a Button in every respect — its own tokens, its press, focus ring and target (BTN-5, BTN-8, BTN-9, BTN-10) — and a focus stop after the input. WHEN it is activated THE combobox SHALL empty the text and the value, emit input once with the empty text and change once with the empty value WHILE the value was not empty, move focus to the input, and leave its list as it is, open or closed, showing every option WHILE open. WHILE clearable is false THE combobox SHALL draw none: emptying the text and leaving the field clears the value (CMB-29). WHILE clearLabel is empty THE combobox SHALL still draw the button and in debug builds report that it has no accessible name.
CMB-21 WHEN the person changes the text, presses Down Arrow or Up Arrow in the input (with or without Alt), or presses the chevron, WHILE the list is closed, the combobox is neither disabled nor read-only and there is something to show — an option after filtering (CMB-25), a status row or the empty text (CMB-32) — THE combobox SHALL set open to true, emit toggle once with open true, and present its list (CMB-22). Opened by an arrow key or the chevron the list SHALL show every option, whatever the input holds, until the person edits the text. THE combobox SHALL NOT open WHEN focus reaches the input by Tab, by a press on the input or on the container, by a press on the label row of the Field that frames it (FLD-12), or returns to it; a press in the input places the caret and nothing else, so that tabbing through a form opens no list over the fields below and a touch raises the keyboard without a list on top of it. A product that wants the list on focus sets open itself. THE combobox SHALL NOT change value by opening. WHEN the list closes after an input method's composition has ended and before the input that closes the composition arrives (TXI-4) — Escape pressed in that gap, say — THE combobox SHALL NOT open the list on that input: a list the person closed opens again only on what they do next. A composition that left the text as it was when it began closes with no input at all (TXI-4, CMB-16).
CMB-22 WHILE open is true THE combobox SHALL present its list in the platform's overlay layer as an anchored surface (POP-1), anchored to its container and placed bottom-start: comp.combobox.list.offset below the container with the start edges aligned, flipped above the container where the room below, within comp.combobox.list.viewport-margin of the edge of the visible part of the window, above the on-screen keyboard while one is shown, is less than the list needs and the room above is more, shifted along the container to stay within that margin, following the container while it moves or changes size, and closed with the reason anchor-hidden WHEN the container goes wholly out of sight (POP-2 to POP-5). It SHALL make the list exactly as wide as the container (POP-7, the anchor width), fill it with comp.combobox.list.color, raise it by comp.combobox.list.elevation, round it by comp.combobox.list.shape eased by sys.shape.corner-smoothing, clip its rows to that shape and inset them by comp.combobox.list.padding-block and comp.combobox.list.padding-inline. The list SHALL have no placement prop: the list of a field has one natural place.
CMB-23 THE combobox SHALL make its list as tall as its rows, no taller than comp.combobox.list.max-height and no taller than the room on the side it is placed (POP-8), and SHALL scroll the options and the group titles beyond that, vertically only, in the list box itself, the list's paddings scrolling with them. The status row (CMB-32) is not part of the list box, which holds options and groups only: it SHALL stand outside the region that scrolls, under it and inside the list's surface, and SHALL stay in view while the options scroll, so that the region that scrolls is the list box the arrow keys move through and a status row is never scrolled out of sight. WHEN the list opens showing the chosen option THE combobox SHALL scroll it so that the whole of that option is in view. A long list MAY draw only the rows near its scroll position and the active option with its neighbours, each row it does not draw keeping its height so that every option is reached by scrolling and by the keys; such a list SHALL state each drawn option's position among all the options shown and their number (CMB-48). A label, a supporting text or a title wider than the list SHALL wrap (CMB-34); the list SHALL NOT grow wider than the container for it.
CMB-24 WHILE the list is open THE combobox SHALL keep focus in its input (POP-19, with the anchor as the element that keeps focus), because the list is an operated overlay whose focus is the field it belongs to, as the search's docked view is (SRC-8): it SHALL NOT move focus into the list, trap focus, make anything inert or draw a scrim, and a press on an option, on a group title, on the status row or on the list's surface SHALL NOT take focus from the input, so that typing goes on editing the text. At most one option at a time SHALL be the active option, which Enter chooses and assistive technology is told of (CMB-48).
CMB-25 WHILE filter is contains THE combobox SHALL show, of the options it was given and in their order, those whose label contains the text the person has typed since the list opened or since the last commit, compared without regard to case, to the width of a character or to the marks on a letter, as the label's language compares; an empty text SHALL show every option, and a group left without an option SHALL be drawn neither with its title nor with its separation (CMB-43, CMB-44). WHILE filter is none THE combobox SHALL show every option it was given, in the order given, and hide none: which options answer the text is then the product's, decided on input (CMB-16) and given back as options and a status (CMB-32). THE combobox SHALL NOT fetch, wait, debounce, cache, sort or rank anything itself, and SHALL NOT filter by an option's supporting text or value.
CMB-26 WHEN the person changes the text WHILE allowCustomValue is false THE combobox SHALL make active the first shown option that is not disabled, so that Enter chooses what the typing found; WHILE allowCustomValue is true, or WHILE an input method is composing, a change of the text SHALL leave no option active, so that Enter keeps what was typed. WHEN the list opens by an arrow key or the chevron THE combobox SHALL make the chosen option active, or the first shown option that is not disabled WHILE none is chosen or shown. WHILE the list is open THE combobox SHALL make active the next shown option with Down Arrow and the previous one with Up Arrow, in order and across groups; WHILE allowCustomValue is true the text itself is the place before the first option in that order, where no option is active and Enter keeps what was typed: Down Arrow there SHALL make the first option active, and Up Arrow on the first option SHALL leave none active, which gives Enter back to the text. WHILE wrap is true the arrow keys SHALL go round at the ends: Down Arrow on the last option SHALL go to the first place — the first option, or the text WHILE allowCustomValue is true — and Up Arrow on the first place to the last option, as a web search and most lists do; WHILE wrap is false they SHALL do nothing at the ends. WHILE allowCustomValue is false and no option is active, Down Arrow SHALL make the first option active and Up Arrow the last. Page Down and Page Up SHALL move the active option by ten, or to the last or the first where fewer remain, and never go round. THE combobox SHALL leave Home, End, Left Arrow and Right Arrow to the text, where they move the caret, whether or not the list is open. A disabled option SHALL be reached like any other, so that people learn it exists; a group title, a divider and the status row are never active. WHEN a pointer moves onto an option THE combobox SHALL make it the active one, render it hovered and show no focus ring; WHILE a pointer is at rest THE combobox SHALL NOT take the options that a scroll of the list or of the page carries under it for a pointer that moves onto them, so that the option a key made active stays active; WHILE an option is active by the keyboard it SHALL render it in the focused state and show the focus ring inside its row, without animation. Making an option active SHALL change neither value nor the text. WHEN an option becomes active while part of it is scrolled out of view THE combobox SHALL scroll it into view. WHEN the options change while the list is open THE combobox SHALL keep the active option where an option of the same value is still shown and otherwise apply the first sentence of this requirement.
CMB-27 WHEN the person presses an option that is not disabled by pointer or touch, or presses Enter while such an option is active and no input method is composing, THE combobox SHALL, WHEN that option's value differs from value, set value to it and emit change once with the new value; it SHALL write the option's label into the input with the caret at its end, without emitting input, and then close the list, set open to false and emit toggle once with open false and the reason select, so that toggle follows change. Choosing the option that is already chosen SHALL emit no change and still write its label and close the list. An Enter that chooses SHALL do nothing else: it SHALL NOT emit action and SHALL NOT submit a form. THE combobox SHALL NOT emit change when the product sets value.
CMB-28 WHEN the person presses Enter in the input while no option is active and no input method is composing THE combobox SHALL commit its text as CMB-29 says, and WHILE its list is open close it with the reason commit; WHILE allowCustomValue is false and the text was not resolved — it is not empty and names no option — THE combobox SHALL instead keep the text and keep or open its list, which then shows what matches or the empty text (CMB-32), and do nothing more. After an Enter that committed THE combobox SHALL emit action, after any change it caused, and on the web, inside a form, SHALL then request the form's submission as a native input does unless action was cancelled. The submission SHALL be requested through the form's default button (BTN-30): WHILE the form has a submit button — the platform's own or a Button of type submit — the first of them in document order SHALL be pressed, so that its click is emitted and its name and value are sent, and WHILE that button is disabled nothing SHALL be submitted; only a form with no submit button is asked directly.
CMB-29 WHEN focus leaves the combobox — the input and, WHILE it is shown, the clear button — by Tab, Shift+Tab, a press elsewhere or the product, or WHEN CMB-28 commits, THE combobox SHALL resolve its text: an empty text makes the value empty; a text equal to the label of an option that is not disabled — the whole label, compared as CMB-25 compares and ignoring spaces around it — chooses the first such option; any other text, WHILE allowCustomValue is true, becomes the value as it was typed, and WHILE allowCustomValue is false is given up: THE combobox SHALL write the text of the committed value back (CMB-17) and keep the value. It SHALL then emit change once WHILE the value differs from the one last committed, and close an open list with the reason tab or focus-out. THE combobox SHALL NOT choose the active option because focus left: an option made active by typing or by a resting pointer was not confirmed, as an open select chooses nothing on Tab.
CMB-30 WHEN the person presses Escape or the platform's back while the list is open THE combobox SHALL close the list, choosing nothing and keeping the text as typed, set open to false and emit toggle once with open false and that reason (escape or back), and the key SHALL go no further, so that a dialog the combobox stands in stays open (POP-23). WHEN the person presses Escape WHILE the list is closed and the text was changed since the last commit THE combobox SHALL write the text of the committed value back, emit input once with it, and stop the key; WHILE the list is closed and the text is the committed value's Escape is not the combobox's and SHALL pass on. Escape SHALL never empty a committed value: a value is an answer, not a query. WHEN the person presses outside the list and the container, or presses the chevron, while the list is open THE combobox SHALL close it with the reason outside or press, choosing nothing; a press outside that also takes focus resolves the text as CMB-29 says. Whether a press outside also reaches the element under it SHALL follow the platform and be stated in its README, as for the menu (MNU-5). WHEN the list closes because nothing is left to show — the filter left no option WHILE allowCustomValue is true, or the product emptied the options and the status — it SHALL close with the reason empty, and SHALL open again by CMB-21 when there is.
CMB-31 WHEN the product sets value THE combobox SHALL show its text as CMB-17 says and SHALL NOT emit change, input or toggle, and WHILE the list is open SHALL move the fill and the check to the new chosen option. WHEN the product sets inputValue THE combobox SHALL show that text, filter by it as by typed text WHILE the list is open (CMB-25), and SHALL NOT emit input or change value; a text set during an input method's composition SHALL be applied when the composition ends (TXI-4). WHEN the product sets open THE combobox SHALL show or remove its list without emitting toggle. WHEN the options change THE combobox SHALL change neither value nor the text the person is editing: options that arrive while a person types are an answer to the typing, not a new choice. WHEN the combobox becomes disabled or read-only while its list is open THE combobox SHALL close the list without emitting toggle.
CMB-32 WHILE the list is open and statusText is not empty or status is loading THE combobox SHALL draw, after the last option, a status row, under the region that scrolls and always in view (CMB-23): inset by comp.combobox.option.padding-inline.medium at the sides and padded by comp.combobox.option.padding-block.medium above and below, taking no input, no state and never the active option. WHILE status is idle it SHALL draw statusText, wrapping, in comp.combobox.status.typescale and comp.combobox.status.color; WHILE status is error it SHALL draw it in comp.combobox.status.error.color; WHILE status is loading it SHALL draw, in the text's place and at the row's start, one Tanrei loading indicator of size small named by statusText, which waits its own show delay and enters as the loading indicator does (LDG-11 to LDG-14), and no text, and the row SHALL keep the height of one line of text whether or not the indicator is shown yet. The options the product leaves in the list WHILE status is loading SHALL stay drawn and usable. WHILE the list would show no option, status is idle, statusText is empty, allowCustomValue is false and the text is not empty THE combobox SHALL draw emptyText in the status row's place and style, so that a person who typed something no option holds is told so instead of facing a list that closed; WHILE emptyText is empty and the product's words give none it SHALL draw no such row and in debug builds report it.
CMB-33 THE combobox SHALL expose the status row as a live region that is present while the list is shown and holds nothing while it is closed: WHEN the list has been shown, and WHILE it is open WHEN statusText changes or emptyText appears, THE combobox SHALL have assistive technology read the row's text — politely, after what it is saying, WHILE status is idle (the status role on the web), and at once WHILE status is error (the alert role) — so that what the row already says as the list opens is read as well as what it comes to say, focus staying in the input (CMB-22). WHILE status is loading it SHALL announce nothing — the loading indicator does not announce itself (LDG-6) — and SHALL mark the list as busy (aria-busy on the web) until status leaves loading. THE combobox SHALL NOT compose, count or translate a text: the number of options is already exposed by the list (CMB-48), and the words are the product's.
CMB-34 THE combobox SHALL lay out an option as one row: comp.combobox.option.padding-inline.medium from each edge, the leading icon column (as CMB-67 says), the label with the supporting text below it taking the remaining width, and at the end a box of side comp.combobox.option.mark.size.medium for the check (CMB-36), each comp.combobox.option.gap.medium from the next; the box of the check SHALL keep its width in every row so that labels wrap alike. It SHALL make the row at least comp.combobox.option.height.medium tall, and at least sys.target.touch tall for touch input and at least sys.target.pointer tall for fine pointers, drawn so, at every size (CMB-68), because rows that touch cannot extend a hit area over each other (a platform that cannot tell the input type SHALL use sys.target.touch); pad its content by comp.combobox.option.padding-block.medium above and below; draw the label in comp.combobox.option.label.typescale and the supporting text in comp.combobox.option.supporting-text.typescale, both wrapping and growing the row rather than being cut; and make the whole row the option's target.
CMB-35 THE combobox SHALL draw an option from the condition it is in — selected-option for the chosen option, option for every other — and from the state it is in, with precedence pressed over focused over hovered: its row filled with the container color of that condition and state within the corners comp.combobox.option.shape gives, eased by sys.shape.corner-smoothing, over comp.combobox.list.color and under the row's content; its label, supporting text and leading icon in that condition's colors (comp.combobox.stacked.option.label.color, comp.combobox.stacked.selected-option.label.color and so on for a stacked combobox). The option parts hold the same values under every variant: a list does not change with the look of its field. WHEN the colors of an option change between states THE combobox SHALL animate them over comp.combobox.motion.state-duration with comp.combobox.motion.state-easing, and SHALL change the active option's focus ring without animation.
CMB-36 WHILE an option is the chosen one — its value equals value — THE combobox SHALL fill its row with the selected-option container color of its state (comp.combobox.stacked.selected-option.container.color at rest for a stacked combobox) and SHALL draw the glyph check of the system's icon set centred in the box at the end of the row, in the mark color of that condition and state (comp.combobox.stacked.selected-option.mark.color at rest), with sys.icon.family.selected, sys.icon.fill.selected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max; it SHALL draw nothing in that box for any other option, SHALL NOT mirror the check in a right-to-left layout, and SHALL draw no mark of its own. THE combobox SHALL NOT show the choice by the fill alone: the check is always drawn with it. The chosen option SHALL stay marked while the list is filtered and it is among the options shown.
CMB-37 THE combobox SHALL draw an option's leadingIcon at comp.combobox.option.leading-icon.size.medium through the icon helper, with the family and fill of the option's condition (sys.icon.family.selected and sys.icon.fill.selected for the chosen option, otherwise sys.icon.family.unselected and sys.icon.fill.unselected), sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, in the leading-icon color of its condition and state, hidden from assistive technology; an empty name SHALL draw nothing.
CMB-38 WHILE filter is contains and the person has typed a text that is not empty THE combobox SHALL draw, in the label of each shown option, the first run of the label that matched the text (CMB-25) as the search marks a match (SRC-43): in comp.combobox.option.match.color with its weight raised by comp.combobox.option.match.emphasis over the weight of comp.combobox.option.label.typescale, over a fill of comp.combobox.option.match.container.color that covers the run's own line boxes, with square corners and no padding; in the selected option in comp.combobox.option.match.selected.color over comp.combobox.option.match.selected.container.color, so that the fill stands apart from the selected option's own; and in a disabled option in the label's disabled color — so that a row says why it is still there by more than color, and in every script, also where the reader's font has no weight between regular and bold. The run SHALL wrap with the label as one text. It SHALL expose the label to assistive technology as one text, read without a pause or an announcement at the run. WHILE filter is none THE combobox SHALL mark nothing, because how the product matched is not known to it.
CMB-39 WHILE an option's disabled is true THE combobox SHALL NOT choose it by any input, on a press or on Enter or when its label is typed in full (CMB-29), SHALL leave the list open when it is pressed or when Enter is pressed on it, SHALL expose its disabled state to assistive technology, and SHALL render its container, label, supporting text, leading icon, mark and opacity from the disabled component tokens of its condition. A disabled option whose value equals value is still the chosen one: the input shows its label, and its row draws the fill and the check from the disabled tokens.
CMB-40 WHEN the option is pressed by pointer, touch or Enter THE option SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner.
CMB-41 WHILE pressed THE option SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; label, supporting text, leading icon, mark, opacity and shape still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.combobox.motion.feedback-duration with comp.combobox.motion.state-easing, fades over comp.combobox.motion.state-duration with comp.combobox.motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced.
CMB-42 THE option SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show its keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README.
CMB-43 WHILE a group's title is not empty and the group shows at least one option THE combobox SHALL draw the title above the group's options in comp.combobox.group-title.typescale and comp.combobox.group-title.color, starting comp.combobox.group-title.padding-inline.medium from the rows' start edge and ending comp.combobox.group-title.padding-inline.medium from their end edge, with comp.combobox.option.padding-block.medium above and below, wrapping and growing with enlarged text rather than clipping. The title SHALL take no focus, SHALL never be the active option, SHALL NOT be matched by the filter and SHALL scroll with its options. WHEN a group holds another group THE combobox SHALL draw the inner group's options as the outer group's, with no title or separation of the inner group's own, and in debug builds report it.
CMB-44 THE combobox SHALL separate a shown group from an adjacent shown group or an adjacent shown option outside any group as its separation names: WHILE separation is auto, as comp.combobox.separation names, which follows the design system's choice unless a system sets it apart; WHILE separation is divider or gap, as that value names, whatever the tokens say. Under divider it SHALL draw a line of comp.combobox.divider.thickness in comp.combobox.divider.color across the list's inner width, inside comp.combobox.list.padding-inline on each side, with comp.combobox.divider.space above and below it, exposed as a separator that takes no focus; under gap it SHALL leave comp.combobox.group.gap of empty space, draw no line and expose no separator. It SHALL draw neither before the first nor after the last element of the list, and neither between the options and the status row. WHEN separation names a value the combobox does not define THE combobox SHALL treat it as auto and in debug builds report it.
CMB-45 WHEN the list opens THE combobox SHALL make it appear as a popover's container appears (POP-26) — from where that appearance starts it, grown from the middle of the edge that faces the container — over comp.combobox.motion.open-duration with comp.combobox.motion.open-easing, and WHEN it closes take it back the same way over comp.combobox.motion.close-duration with comp.combobox.motion.close-easing; WHERE motion is reduced it SHALL only fade in and out, over sys.motion.role.reduced. A motion interrupted SHALL turn round from where it is, and a closing list SHALL take no input (POP-27, MOT-7). WHEN the options shown change while the list is open THE combobox SHALL change the list's height at once, without a motion of its own. Focus, the text and the value SHALL change when the list closes, not when its motion ends.
CMB-46 WHILE disabled is true — set by the product, or by the Field that frames it (FLD-14) — THE combobox SHALL NOT be focusable or editable, SHALL NOT open, SHALL NOT emit input, change, action or toggle, SHALL expose the disabled state to assistive technology, SHALL be left out of form submission on the web, SHALL draw no clear button, and SHALL render every part of its box, the chevron and a floating label included, from the disabled component tokens of its variant (of its error parts WHILE error is true).
CMB-47 WHILE readOnly is true and disabled is false THE combobox SHALL stay focusable and show its value, selectable and copyable, SHALL NOT let the person change the text or the value, SHALL NOT open by any input, SHALL draw neither the chevron nor the clear button (CMB-19, CMB-20), SHALL NOT emit input, change or toggle, SHALL expose the read-only state to assistive technology, SHALL be submitted with its form on the web, and SHALL render as an enabled combobox, including its hovered and focused states.
CMB-48 THE combobox SHALL expose its input, on the web, as an editable combobox: named as CMB-12 says, with the text as its value, aria-autocomplete list, aria-haspopup listbox, aria-expanded, aria-controls naming the list box while the list is open and absent while it is closed, so that the input never names an element that is not exposed — WHILE the list is open THE combobox SHALL keep the list box in the accessibility tree, also WHERE no option is shown and the list shows its status row or emptyText alone (CMB-32): an empty list box that takes no room, is no focus or pointer target and holds nothing to read —, and aria-activedescendant naming the active option while there is one and absent otherwise — at once WHEN the list opens with it, an arrow key or a page key moves to it or a pointer makes it active, and WHEN typing made it active (CMB-26) only once it has stayed active for 500 milliseconds with nothing typed, each change of the text taking the active descendant away until then, as the search announces the row it makes current (SRC-24), so that a screen reader reads the character typed first and then the option Enter would choose, and not an option after every key —; and the list as a listbox of the same name whose options are named by their label and described by their supporting text, each with its selected state — true for the chosen option alone — its disabled state, its position and the number of options shown, counted among all the options shown also where a long list draws only some of their rows (CMB-23), and whose groups are groups named by their title. On the other platforms THE combobox SHALL expose the input as the platform's text field that offers a list of choices (a combo box, an editable drop-down) of that name with its text and its expanded state, and the options as selectable items of a list with the same names, states and positions; WHERE a platform's assistive technology cannot follow an active option while focus stays in the text, THE combobox SHALL announce the active option's label, politely, each time it changes — after the same pause for an option typing made active —, and state that in its README. The leading glyphs, the check and the dividers SHALL be hidden from assistive technology; the chevron is a button (CMB-19) and the clear button a Button (CMB-20).
CMB-49 THE combobox SHALL be block-level, framed and bare alike: exactly as wide as the place it stands in — the width its layout gives it, which inside a Field is the Field's whole width (FLD-1), so that the box fills its Field — with no width of its own and never the platform's default width for a text element, as the text input is (TXI-63). Its width SHALL NOT follow its options or its value, because a person types into it before any option is known. A product that wants a narrower box gives it a narrower place.
CMB-50 WHILE the text size is enlarged THE combobox SHALL grow with its texts: the container grows with the input's line and with a floating label that wraps (CMB-8), keeping the height of its size as a minimum; the text stays on one line and scrolls inside its input, the glyphs keep their sizes, the options, their supporting texts, the group titles and the status row wrap rather than cut, and the list scrolls where the taller rows no longer fit. At 200% no text SHALL be lost, lie over another part or need scrolling in two directions.
CMB-51 WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE combobox SHALL draw its floating label and the asterisk after it in the platform's text color, SHALL draw an edge comp.input-box.outline.width wide in the platform's control text color around its container in every variant, and that edge in the platform's highlight color at the focused width while focused, and SHALL rely on no color of its own to show an error: the error is carried by the invalid state (CMB-10) and by the words its Field shows. It SHALL draw an edge in the platform's text color around its list, the active option in the platform's highlight colors, the matched run of a label in the platform's colors for marked text (the web's Mark and MarkText), its weight raised, and a disabled combobox and a disabled option in the platform's disabled text color; the chosen option SHALL then be shown by its check alone.
CMB-52 WHERE the layout direction is right-to-left THE combobox SHALL mirror its layout: the leading glyph at the right of its container, the clear button and the chevron at its left with the chevron nearest the edge, a floating label resting and floated from the right, the list aligned to the container's edges as before, and in each option the leading icon at the right and the check at the left, all paddings applied by logical start and end (POP-34 for the list's placement).
CMB-53 THE combobox SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the combobox is shown THE combobox SHALL draw itself for the new direction at once, without a motion of its own, keeping its value, its text, its caret, its open state, its active option and its focus, the list placed again by the new direction (CMB-22).
CMB-54 WHERE the layout direction is right-to-left THE combobox SHALL draw the glyph of its leading-icon slot and an option's leadingIcon mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size, color and fill nor the order CMB-52 gives. THE combobox SHALL NOT mirror a glyph itself. The chevron's expand_more, the clear button's close and the check are not marked and are never mirrored.
CMB-55 THE combobox SHALL lay out its floating label, its placeholder, an option's label and supporting text, a group's title and the status row's text as text of its own direction, isolated from the text around it: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE combobox SHALL still place each and align its lines by the layout direction, not by the text's own. It SHALL lay out the text in its input by that text's own direction and, WHILE the input is empty or holds no strong character, by the layout direction, so that the caret of an empty combobox and its placeholder stand at its start edge (TXI-24).
CMB-56 WHEN variant or size names a value that the active design system does not have THE combobox SHALL render with the default value's tokens, and in debug builds report the unknown value; WHEN variant names a value the active system has but the combobox does not know by name (one a layer added) it SHALL draw no label of its own and draw its edge as a stacked combobox does (CMB-8, CMB-15), with that value's own tokens; WHEN filter names a value the combobox does not know it SHALL behave as contains, and WHEN status names one, as idle, each reported in debug builds.
CMB-57 WHILE the combobox holds no option, no status and nothing to say THE combobox SHALL draw its field as it is, SHALL stay focusable and editable, and SHALL NOT open by any input or because open is true: it SHALL draw no empty list. IF two options have the same value THE combobox SHALL treat the first of them, in order, as the one that value names and in debug builds report the repeated value; IF an option's label is empty THE combobox SHALL still render it and in debug builds report that it has no accessible name; IF an option's value is the empty string THE combobox SHALL render it, SHALL NOT choose it (CMB-17), and in debug builds report it.
CMB-58 THE combobox SHALL keep its list an anchored list at every window size, as a popover does whose initialFocus is anchor (POP-43) — a list of options is the menu's kind of surface, which Tanrei's rule for compact windows leaves beside its control, and focus stays in the field the person is typing in: in a narrow window the list narrows with its container, shortens to the room it has and scrolls, and SHALL NOT turn into a sheet or a dialog by itself. WHILE an on-screen keyboard is shown THE combobox SHALL count the keyboard's top edge as the window's edge when it places and sizes the list (POP-36), so that the options stay in view above the keyboard or flip above the field.
CMB-59 WHERE the platform has forms (the web) THE combobox SHALL take part in them as a native input does: it takes name, submits value — the chosen option's value, or the custom value — and never the text of an edit that was not committed, restores it on navigation, resets to the value it was first given, and reports to the form's constraint validation a missing value WHILE the Field that frames it says it is required (CMB-12) and value is empty.
CMB-60 THE combobox SHALL have no words of its own: it SHALL take emptyText and clearLabel from the instance's prop and, WHILE that is empty, from the product's words of the same name — the words a product sets once for all its components — and from nowhere else. WHILE neither gives emptyText the row is as CMB-32 says: not drawn, and reported once in debug builds. WHILE neither gives clearLabel the clear button is as CMB-20 says: drawn, working and reported. The words of a requirement are not the combobox's: they are the Field's (FLD-24).
CMB-61 THE combobox SHALL say to the Field that frames it what only the combobox knows, and SHALL say it again WHEN it changes: that it draws the label itself WHILE its variant floats one (CMB-8), so that the Field draws no label row (FLD-25); and how far its input text stands from its own start edge — its inline padding and, beside a leading glyph, that glyph and its gap (CMB-1, CMB-18) — and the padding it keeps at its end edge (CMB-1), so that the Field's supporting row starts and ends there (FLD-26); and that it is drawn focused, for as long as its list is open, whether or not it has focus (CMB-15), so that the Field's rows are drawn focused with it (FLD-13). It SHALL take from that Field its name, its description and its required, invalid and disabled states (CMB-10, CMB-12, CMB-46), whether the label is hidden (CMB-8) and whether an asterisk follows it (CMB-7), so that a Field and a combobox placed by hand are drawn, named, described and marked exactly as a combobox field is. It keeps no count and reports no refusal of an entry (FLD-27, FLD-28): a text that names no option is given up, not kept as an error (CMB-29).
CMB-62 THE combobox SHALL draw no label row above itself, no requirement tag, no help and no error text: those are the rows of the Field that frames it (FLD-2 to FLD-7). WHILE no Field frames it THE combobox SHALL be complete as a bare control — its box, the label that floats in it where its variant floats one, the text typed in it, its list and its options, its states and its events — named by its own label (CMB-12), as wide as its layout gives it (CMB-49) and exactly as tall as its container.
CMB-63 THE combobox SHALL draw its box from the one set of tokens every input box is drawn from, the group comp.input-box (comp.input-box.container.shape, comp.input-box.container.height.medium, and so on): its container, its corners, its edges and their widths, the label that floats in it and the asterisk after it, the typed text and the placeholder, the leading glyph and the chevron, the caret and the highlight of selected text, the paddings, the gaps and the least height of its size (a stacked box's from comp.input-box.stacked.container.height.medium and comp.input-box.stacked.container.padding-block.medium for size medium, as tall as a Button of the same size, and a filled or an outlined box's from comp.input-box.container.height.medium and comp.input-box.container.padding-block.medium, and so on), and the colors of each of these in its look, at rest, hovered, focused and disabled, plain and in error. It SHALL have no token of its own for any of them: the tokens of its own group are those of its list, of its status row and of the gap between its clear button and its chevron (CMB-23, CMB-34 to CMB-41). WHEN a design system or a product sets a token of the box THE combobox SHALL follow it, as the text input, the select, the number input and the color input do, which read the same tokens; no token is held equal to another for this. WHERE one combobox is to differ from the other boxes of a product, the token is set for that instance — on its element or on a subtree that holds it, in each platform's way of setting a token for a subtree — and THE combobox SHALL draw itself from the value it finds there.
CMB-67 THE combobox SHALL decide the leading icon column for each section of its list as it is shown — the shown options of a group, with the options of a group inside it (CMB-43), or a run of adjacent shown options outside any group: the parts CMB-44 separates. WHILE iconSpace is auto a shown option SHALL keep the column, empty where it has no icon, WHERE a shown option of its section has a leading icon, so that the labels of a section start on one line, and a section where no shown option has one SHALL keep no column, its labels starting at the row's content start; an option the filter hides SHALL NOT count, so that no row keeps room for an icon that is not drawn. WHILE iconSpace is always every shown option SHALL keep the column, whether or not any option has an icon; WHILE iconSpace is never an option SHALL have the column only where it has a leading icon itself. The column kept is comp.combobox.option.leading-icon.size.medium wide with comp.combobox.option.gap.medium after it, draws nothing and is nothing to assistive technology. A group's title SHALL keep its own place whatever the column of its section is (CMB-43). WHEN the shown options change — the filter's text, an option added or removed, an option's leadingIcon — THE combobox SHALL decide the sections again; WHEN iconSpace names a value the combobox does not define THE combobox SHALL treat it as auto and in debug builds report the unknown value.
CMB-68 THE combobox SHALL draw the options and the group titles of its list at the size its box is drawn at — its own size, or WHILE it sets none the size a container around it gives it (CMB-83): small WHILE the box is drawn small, and medium WHILE it is drawn medium or large, a size the options lack being taken as the nearest one they have, the larger on a tie, as a container's size is; the list SHALL take a container's size only through its box, because it stands in the top layer, apart from the controls around the box, and belongs to the box that opens it. WHILE it draws medium they SHALL take the medium value of every token of the option-size axis this spec names (comp.combobox.option.height.medium, comp.combobox.option.padding-block.medium, comp.combobox.option.padding-inline.medium, comp.combobox.option.gap.medium, comp.combobox.option.leading-icon.size.medium, comp.combobox.option.mark.size.medium, comp.combobox.group-title.padding-inline.medium); WHILE it draws small they SHALL take the small value of each in its place (comp.combobox.option.height.small, comp.combobox.option.padding-block.small, comp.combobox.option.padding-inline.small, comp.combobox.option.gap.small, comp.combobox.option.leading-icon.size.small, comp.combobox.option.mark.size.small, comp.combobox.group-title.padding-inline.small), so that a small option is lower, set in less from its edges and draws smaller glyphs, the room kept for an empty leading icon column (CMB-67) shrinking with them; the heights follow the system's height ladder at either size. The text styles, the list's surface and its paddings, the dividers, the group gap and the status row SHALL be the same at both. WHEN the size the box is drawn at names a value the active design system's options do not have and that is not one of the ladder's (extra-small, small, medium, large, extra-large) THE combobox SHALL draw the default size's rows and in debug builds report the unknown value; a size a design system added to the options SHALL be drawn from that size's tokens, as the core values are. WHEN the size the box is drawn at changes while the list is open — its own size set, changed or removed, or the size a container gives it — THE combobox SHALL draw the new rows at once, without a motion, keeping the active option.
CMB-69 WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE combobox SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the combobox is invalid — except those the combobox owns (aria-haspopup, aria-expanded, aria-controls, aria-disabled), which it SHALL move and not expose. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE combobox SHALL take it off that element. WHEN the product sets an aria- attribute the combobox owns THE combobox SHALL report it in debug builds.
CMB-70 WHILE selection is multiple THE combobox SHALL hold values — the chosen values in the order they were chosen, no two the same — in place of value, which it SHALL keep as it is and ignore, and its input SHALL hold only the text the person types to find an option: it SHALL never write a chosen option's label into it, SHALL draw no chosen option's own glyph at its start (CMB-18), and the committed text it restores (CMB-17) SHALL be the empty text. WHILE selection is single THE combobox SHALL ignore values. WHEN the product changes selection THE combobox SHALL keep value and values as they are, emit nothing, and from then on show the one the new selection names.
CMB-71 WHEN the person presses an option that is not disabled by pointer or touch, or presses Enter while such an option is active and no input method is composing, WHILE selection is multiple THE combobox SHALL add the option's value at the end of values WHILE values does not hold it, and take it out of values WHILE it does; it SHALL then empty the text without emitting input, show every option again, keep the list open with that option still the active one, keep focus in the input, emit change once with the new values and announce the change (CMB-79). Such an Enter SHALL do nothing else: it SHALL NOT emit action and SHALL NOT submit a form. The list stays open so that several values can be chosen in a row; it closes by Escape, by the chevron, by a press outside or by leaving (CMB-30, CMB-73).
CMB-72 WHEN the person presses Enter while selection is multiple, no option is active and no input method is composing THE combobox SHALL resolve the text without the white space at its ends. An empty text SHALL commit nothing, and THE combobox SHALL emit action and request the form's submission as CMB-28 says. A text equal to the whole label of an option that is not disabled, compared as CMB-29 compares, SHALL add that option's value as CMB-71 does WHILE values does not hold it, and only empty the text WHILE it does. Any other text SHALL, WHILE allowCustomValue is true, be added at the end of values as it is written, without its white space at both ends, WHILE values does not hold the same text, and the text SHALL be emptied either way; WHILE allowCustomValue is false it SHALL be kept, and the list kept or opened showing what matches or the empty text (CMB-32). An Enter on a text that is not empty SHALL NOT emit action and SHALL NOT submit a form.
CMB-73 WHILE selection is multiple: WHEN focus leaves the combobox — its input, its entries and its clear button — for another part of the product THE combobox SHALL close its list with the reason tab or focus-out (CMB-29), choose nothing — neither the active option nor what was typed — and empty the text without emitting input; WHEN the person presses Escape while the list is open THE combobox SHALL close it as CMB-30 says, keeping the text; WHEN they press Escape while the list is closed and the text is not empty it SHALL empty the text, emit input once and stop the key. Leaving and Escape SHALL never remove a chosen value. A choice is a deliberate act in a list of several: leaving the field is not one.
CMB-74 WHILE selection is multiple and values is not empty THE combobox SHALL draw each value as a Chip of kind input, size small and the Chip's default variant, in the order of values, inside its container between the leading glyph and the clear button and the chevron, before the input: its label SHALL be the label of the first option whose value it is, or the value itself where it names none, and its remove action SHALL be named by removeLabel with the place {entry} filled by that label. The entries and the input SHALL stand in lines from the start edge, each entry comp.combobox.entries.gap after the one before, a line comp.combobox.entries.row-gap below the one above, every item centred on its line, an entry that does not fit going whole to the next line and none wider than a line, cut as the Chip says; the input SHALL follow the last entry on its line WHILE at least comp.combobox.entries.typing-min-width is left there and start the next line otherwise. THE combobox SHALL show every entry: it SHALL NOT hide one, stand a count in the place of some, scroll its lines or limit its height. The first line SHALL stand where the input line of a combobox with no entry stands, the container SHALL grow by whole lines from the height of its size, the leading glyph, the clear button and the chevron SHALL stay centred on it, and the list SHALL stay anchored below it as it grows (CMB-22).
CMB-75 WHILE selection is multiple THE combobox SHALL be one stop in the focus order — its input — and every entry's Chip SHALL be out of the Tab order and stay focusable by the keys, by pointer and by assistive technology. WHEN the person presses Backspace, or the arrow that points to where the line starts, in the input with the caret at the start of the text and nothing selected, and the key is not a repeat of a held key, THE combobox SHALL move focus to the last entry and remove nothing. On an entry: the arrow that points along the line SHALL move focus to the next or the previous entry, past the last to the input with its caret at the start; Home and End SHALL move it to the first and the last entry; Up and Down Arrow SHALL do nothing; Escape and Tab SHALL move it to the input, and Shift+Tab SHALL leave backward as the platform has it; a printable character SHALL move it to the input, where it is typed. WHEN the person presses Backspace or Delete on an entry, or activates its remove action, THE combobox SHALL take that value out of values, emit change once with the new values and announce the removal (CMB-79), having moved focus first — after Backspace to the entry before, or to the one after where it was the first; after Delete or the remove action to the entry after — and to the input where there is none. WHEN the person activates an entry's Chip itself THE combobox SHALL move focus to the input and open its list with that entry's option active where it is shown, removing nothing. These are the chip field's keys (CHF-11 to CHF-14), so that a person who uses both meets the same keys.
CMB-76 WHILE selection is multiple THE combobox SHALL draw every shown option whose value values holds as the chosen one is drawn (CMB-36) — the fill and the check — and expose it as selected and every other option as not selected, and SHALL expose its list as a listbox in which several options can be selected. A list opened by an arrow key or the chevron SHALL have the first shown option whose value values holds active, or the first that is not disabled where it holds none.
CMB-77 WHEN the product sets values THE combobox SHALL draw exactly those entries in that order, a repeated value once, mark the options they name WHILE the list is open, and SHALL NOT emit change or input or announce anything; a value that names no option SHALL be drawn with the value as its label whatever allowCustomValue is. WHILE selection is multiple and clearable is true THE combobox SHALL draw its clear button (CMB-20) WHILE the text or values is not empty and it is neither disabled nor read-only; WHEN it is activated THE combobox SHALL empty the text and values, emit input once with the empty text and change once with the empty values WHILE values was not empty, announce nothing, move focus to the input and leave its list as it is.
CMB-78 WHERE the platform has forms that collect named values (the web's form) and WHILE selection is multiple THE combobox SHALL take part in one as a native select that allows several values does: it SHALL submit one entry for each value, in the order of values, each under its name, none WHILE values is empty, and never the typed text; it SHALL reset to the values it was first given, restore them on navigation, and report a missing value WHILE the Field that frames it says it is required and values is empty, whatever text is typed (CMB-59).
CMB-79 WHILE selection is multiple and values is not empty THE combobox SHALL expose its entries, before its input, as one list named by the combobox's accessible name, each entry an item that holds its Chip — a button named by the entry's label — and that Chip's remove action, named by removeLabel. THE combobox SHALL hold one polite live region of its own, empty at rest and not drawn: WHEN the person adds a value it SHALL put addedText into it with the place {entry} filled by the value's label, and WHEN the person removes one, removedText likewise, the label put in as text of its own direction isolated from the sentence; a later sentence SHALL replace what the region holds. It SHALL announce nothing when the product sets values or when the clear button empties them. THE combobox SHALL take removeLabel, addedText and removedText from the instance's prop and, WHILE that is empty, from the product's words under entryRemoveLabel, entryAddedText and entryRemovedText — the chip field's keys, so that a product writes them once for both — and from nowhere else. WHILE neither gives removeLabel every remove action SHALL still be drawn and work, and debug builds SHALL report that it has no name; WHILE neither gives addedText or removedText nothing SHALL be said, and debug builds SHALL report it.
CMB-80 WHILE selection is multiple and values is not empty THE combobox SHALL show no placeholder, so that a hint for the first choice does not stand after the last, and SHALL treat itself as not empty for its label, so that a filled or an outlined combobox floats it (CMB-8).
CMB-81 WHILE selection is multiple and the combobox is disabled (CMB-46) THE combobox SHALL draw every entry as a disabled Chip, which takes no focus and cannot be removed, still drawn and exposed. WHILE it is read-only (CMB-47) and not disabled THE combobox SHALL draw every entry as an input Chip without a remove action, reached by the keys of CMB-75, which then remove nothing, and SHALL submit values.
CMB-82 WHERE the layout direction is right-to-left THE combobox SHALL lay its entries out from the right: every line starts at the right edge, the input follows the last entry to its left, and the order of values, of focus and of reading stays the order the values were chosen in; the arrow keys of CMB-75 move the way they point. WHILE the text size is enlarged the entries SHALL grow with it, every one still shown, each on a line of its own where two no longer fit, and the input SHALL stay at least comp.combobox.entries.typing-min-width wide.
CMB-83 WHILE size is not set and a container around the combobox sets a size for what it holds — a toolbar's size (TBR-31), or another container that passes its size to a Button (BTN-48), the nearest such container where several do — THE combobox SHALL draw its box at that size, its height following the system's height ladder as at a size of its own, and at its nearest size where it has none of that name, in the order extra-small, small, medium, large, extra-large, the larger of two as near; a container whose size is not set SHALL pass none. WHILE size is set THE combobox SHALL be drawn at its own size, whatever a container sets. WHEN the size it takes changes — a container's size set, changed or removed, its own size set or removed, or the combobox moved into or out of such a container — THE combobox SHALL be drawn at the size it now takes at once. It takes a container's size as a Button does because a stacked box and a Button of one size stand as tall as each other: in a small toolbar the box stands as tall as the small Buttons beside it. The options of the list it opens are drawn at the size the box is drawn at (CMB-68): in a small toolbar a combobox without a size opens small rows.
CMB-84 WHEN the control height (dial.control.height) is N THE combobox's default row SHALL be N tall: an option of a medium or large combobox SHALL be drawn at comp.combobox.option.height.medium, which is sys.control.height.medium held at sys.target.minimum, and an option of a small combobox at comp.combobox.option.height.small, a small menu item's, so that its options stand as tall as a menu's items and as the field that opens them; the option's block padding SHALL give up half of what its height loses below the control height's reference, so that its line still fits, and the pointer and touch targets SHALL still hold the row up where they are taller (CMB-34).
CMB-85 WHEN the control height (dial.control.height) is N THE combobox's default box SHALL be N tall in every look: a medium combobox SHALL be drawn at comp.input-box.stacked.container.height.medium WHILE it is stacked and at comp.input-box.container.height.medium WHILE it is outlined or filled, each sys.control.height.medium held at sys.target.minimum, so that it stands as tall as the Buttons beside it; the box's block paddings SHALL give up half of what its height loses below the control height's reference, so that one line of its value still fits, and the pointer and touch targets SHALL still reach beyond a box that is lower than they are. WHILE a filled combobox draws its label it holds the floated label above the value's line and SHALL be as tall as CMB-1 gives where that is more than N.

Platform name mapping

Parity does not mean identical APIs. Each platform uses its own idiom for the same contract.

Spec Web SwiftUI Jetpack Compose Flutter React Native
Component tanrei-combobox TanreiCombobox TanreiCombobox TanreiCombobox Combobox
variant · Property variant variant variant variant variant
size · Property size size size size size
selection · Property selection selection selectionMode selectionMode selectionMode
value · Property value selection value value value
values · Property values selection values values values
inputValue · Property inputValue text inputValue controller inputValue
label · Property label label label labelText label
labelHidden · Property labelHidden labelsHidden labelHidden labelHidden labelHidden
placeholder · Property placeholder prompt placeholder hintText placeholder
error · Property error error isError isError error
disabled · Property disabled disabled enabled enabled disabled
readOnly · Property readOnly readOnly readOnly readOnly readOnly
open · Property open isPresented expanded menuController open
allowCustomValue · Property allowCustomValue allowCustomValue allowCustomValue allowCustomValue allowCustomValue
filter · Property filter filter filter filter filter
wrap · Property noWrap wrap wrap wrap wrap
chevron · Property noChevron chevron chevron chevron chevron
clearable · Property clearable clearable clearable clearable clearable
clearLabel · Property clearLabel clearLabel clearContentDescription clearSemanticLabel clearAccessibilityLabel
status · Property status status status status status
statusText · Property statusText statusText statusText statusText statusText
emptyText · Property emptyText emptyText emptyText emptyText emptyText
separation · Property separation separation separation separation separation
iconSpace · Property iconSpace iconSpace iconSpace iconSpace iconSpace
removeLabel · Property removeLabel removeLabel removeLabel removeLabel removeLabel
addedText · Property addedText addedText addedText addedText addedText
removedText · Property removedText removedText removedText removedText removedText
input · Event input text onInputValueChange onInputChanged onInputValueChange
change · Event change selection onValueChange onChanged onValueChange
toggle · Event toggle isPresented onExpandedChange onOpenChanged onOpenChange
action · Event action onSubmit keyboardActions onSubmitted onSubmitEditing
Notes Lagging: the element in the repository still draws its own label row, requirement mark and supporting row and has the ten props of a frame; the bare control without them is not built on this platform yet. As specified: tanrei-combobox, class TanreiCombobox, React Combobox. A form-associated custom element (static formAssociated = true): it takes name, submits value (never the uncommitted text), restores it on navigation, resets to the value attribute, follows <fieldset disabled> and reports valueMissing while its Field says it is required (CMB-59); its two calls on ElementInternals and its form for Enter go through the shared composing primitives, so that a composed element that holds it can be the form's control in its place. The options are <tanrei-option> and <tanrei-option-group> children, observed for changes; the combobox reads them and renders the rows itself in its shadow root, so that the <input role="combobox">, its aria-controls listbox and its aria-activedescendant option are in one tree. **Options through a slot**: a <slot> element among its children stands for the elements assigned to it, flattened (assignedElements({ flatten: true })), in the slot's place among the other children; the combobox reads them as its own options, reads again on that slot's slotchange, and observes each assigned element as it observes a child. This is readOptions() and OptionsController in primitives/option-list.ts, shared with the select, and it is how a composed element gives the combobox the product's options without moving or copying an element. The input carries aria-autocomplete="list", aria-expanded, aria-haspopup="listbox" and aria-readonly, with autocomplete="off", autocapitalize="none" and spellcheck="false"; its name, its description and its invalid and required states are values — its own label, or what the Field's connection gives (packages/web/src/primitives/field.ts) — written on the input as aria-label, aria-description, aria-invalid and aria-required, because an id cannot be referenced across a shadow root. To that connection the combobox says that it draws the label (a filled or outlined variant) and its inset (CMB-61), and takes from it labelHidden and the required mark besides. Composition is read from compositionstart / compositionend and event.isComposing (and keyCode 229), and keys are ignored while it lasts. The chevron is a <button tabindex="-1" aria-label aria-expanded> and the clear button a <tanrei-button variant="text" size="small">; pointerdown on a row, the chevron or the list calls preventDefault so that focus stays in the input. The list is a manual popover in the top layer, placed with CSS anchor positioning and a script fallback, sized to the anchor's width and followed with the FollowController the menu uses, with the combobox's own light dismiss so that toggle carries a reason; the element itself is the opener, so a press on the label row of a Field around it is a press outside (CMB-30). On a touch device visualViewport gives the keyboard's edge. The match is a <mark> with background: none and a heavier font-weight, inside the option's one text node sequence, which assistive technology reads as one label. input is the native composed event (the text is inputValue); the combobox sets its own value before firing change (a composed, bubbling CustomEvent whose detail holds value and inputValue) and its own open before firing toggle (detail holds open and reason), a CustomEvent that is composed and does not bubble, as the platform's own toggle does not. The element in the repository fires a toggle that is neither yet, and an event that is not composed never leaves the shadow root of an element that holds the combobox. Attributes are kebab-case (input-value, label-hidden, allow-custom-value, clear-label, status-text, empty-text) except readonly; a boolean attribute cannot default to true, so the web names the inverse of chevron: no-chevron, and of wrap: no-wrap, and each property has its attribute's name (noChevron, noWrap). An option typing made active is named by aria-activedescendant 500 ms after it became active, from a timer each change of the text restarts. The leading-icon slot is a named slot. The inline attribute draws an open list in place under the box, for the fixtures. Parts: container, outline, active-indicator, label and requirement-label (the floating label and its asterisk), input, leading-icon, clear-button, chevron, list, option, option-label, option-supporting-text, option-leading-icon, mark, group, group-title, divider, status. Before the element is defined its options are running text: a page hides them with tanrei-combobox:not(:defined) > * { display: none } and gives the tag a block size. A <datalist> is not used: its list takes no token, no supporting text, no group and no status, and browsers disagree on how it filters. Words: the element has no words of its own. empty-text and clear-label left empty read the product's words, set once with setWords() from @tanrei/web; the element draws again when they change. **Several values**: selection="multiple" with values — a property that takes an array, and an attribute read as a JSON array or as words (values='["kyoto","tokyo"]', values="kyoto tokyo") that is also what a form reset returns to. Each value is a <tanrei-chip kind="input" size="small" tabindex="-1"> in a role="list" element in the container, before the input; the chips' parts leave under entry-container, entry-label and entry-remove, and the chip itself is the part entry. The listbox carries aria-multiselectable="true". The form value is a FormData with one entry per value under name. change's detail then holds values (the new array) beside value and inputValue. A hidden aria-live="polite" region says what was added or removed. The bare control: it draws no label row and no message, and TanreiComboboxField is the Field around it. TanreiCombobox("City", selection: $city, text: $query) { TanreiComboboxOption("Tokyo").tag("tokyo") … }: two bindings, as a text field with suggestions has (TextField with .textInputSuggestions, .searchable(text:suggestions:), AppKit's combo box); text is optional and kept by the component when left out. The first argument is its name, floated in a filled or outlined look; labelHidden follows .labelsHidden(), disabled follows .disabled(_:), action is onSubmit:. Built on TextField; composition is the marked text of the field, during which the component handles no key. The list is Tanrei's, presented as TanreiMenu's surface is, without taking focus. VoiceOver does not follow an active option while focus stays in the text on iOS, so the active option's label is posted as an announcement (CMB-48). The product's words are read from the \.tanreiWords environment value. Several values: TanreiCombobox("Cities", selection: $cities, text: $query) with cities a [String] binding, as List(selection:) takes a set; the type of the binding is the selection prop. The bare control: it draws no label row and no message, and TanreiComboboxField is the Field around it. Compose idiom, as an exposed dropdown menu with an editable field (ExposedDropdownMenuBox): TanreiCombobox(value, onValueChange, label = "City") { TanreiComboboxOption("Tokyo", "tokyo") … }; the caller keeps value (state hoisting), and inputValue / onInputValueChange and expanded / onExpandedChange are optional pairs the component keeps itself when left out. enabled is the inverse flag and isError keeps Compose's name. Built on BasicTextField; a composition is TextFieldValue.composition, during which no key is handled. The list is a non-focusable Popup, so focus stays in the field, placed as TanreiMenu places its surface and inset by WindowInsets.ime. Semantics: the field has Role.DropdownList, its expanded state and a live stateDescription that names the active option, because TalkBack does not follow an active descendant. The product's words are read from LocalTanreiWords. The bare control: it draws no label row and no message, and TanreiComboboxField is the Field around it. Flutter idiom, as Autocomplete / RawAutocomplete and DropdownMenu with enableFilter: TanreiCombobox(value:, onChanged:, labelText:, options: […]), the text in a TextEditingController (an internal one when none is given), with labelText, hintText and enabled keeping InputDecoration's names, enabled the inverse flag. A composition is TextEditingValue.composing, during which no key is handled. The list is shown in the Overlay with OverlayPortal, linked to the field with a CompositedTransformFollower and kept above MediaQuery.viewInsets; it takes no focus. The active option is announced with SemanticsService.announce where the platform cannot follow it. The product's words are read from the TanreiWords inherited widget, which the app fills from its own localizations. The bare control: it draws no label row and no message, and ComboboxField is the Field around it. <Combobox label="City" value={city} onValueChange={setCity} options={[…]} />: options is an array of options and groups, as Select's. inputValue / onInputValueChange and open / onOpenChange are optional pairs. React Native has no control of this kind on either platform, so the box is drawn on the platform's TextInput and the list is Tanrei's, on the overlay layer that TanreiProvider renders, placed by measuring the field and the keyboard (Keyboard events), with keyboardShouldPersistTaps="handled" so that a press on a row does not dismiss the keyboard first. JavaScript gets no signal that a composition is in progress, so the component never writes the text back while the field is focused and chooses on a row press or the keyboard's action key only (CMB-16). accessibilityRole="combobox", accessibilityState={{ expanded, disabled }}; the active option is announced with AccessibilityInfo.announceForAccessibility. Follows the app's direction where an ancestor's is not known. The product's words are read from the TanreiWordsProvider context.

Tokens

Token Aliases Resolved (light)
--tanrei-comp-combobox-container-action-gap — 6px
--tanrei-comp-combobox-disabled-opacity — 1
--tanrei-comp-combobox-divider-color sys.color.outline-variant #000000 · 8%
--tanrei-comp-combobox-divider-space sys.space.space50 4px
--tanrei-comp-combobox-divider-thickness sys.border.hairline 1px
--tanrei-comp-combobox-entries-gap comp.text-input.entries.gap 8px
--tanrei-comp-combobox-entries-row-gap comp.text-input.entries.row-gap 8px
--tanrei-comp-combobox-entries-typing-min-width comp.text-input.entries.typing-min-width 72px
--tanrei-comp-combobox-filled-disabled-option-container-color — #000000 · 0%
--tanrei-comp-combobox-filled-disabled-option-label-color — #1b1b1b · 38%
--tanrei-comp-combobox-filled-disabled-option-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-combobox-filled-disabled-option-state-layer-color — #1b1b1b · 38%
--tanrei-comp-combobox-filled-disabled-option-supporting-text-color — #1b1b1b · 38%
--tanrei-comp-combobox-filled-disabled-selected-option-container-color — #1b1b1b · 0%
--tanrei-comp-combobox-filled-disabled-selected-option-label-color — #1b1b1b · 38%
--tanrei-comp-combobox-filled-disabled-selected-option-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-combobox-filled-disabled-selected-option-mark-color — #1b1b1b · 38%
--tanrei-comp-combobox-filled-disabled-selected-option-state-layer-color — #1b1b1b · 38%
--tanrei-comp-combobox-filled-disabled-selected-option-supporting-text-color — #1b1b1b · 38%
--tanrei-comp-combobox-filled-focused-option-container-color — #1b1b1b · 10%
--tanrei-comp-combobox-filled-focused-option-label-color — #1b1b1b
--tanrei-comp-combobox-filled-focused-option-leading-icon-color — #4b4b4b
--tanrei-comp-combobox-filled-focused-option-state-layer-color — #1b1b1b
--tanrei-comp-combobox-filled-focused-option-supporting-text-color — #4b4b4b
--tanrei-comp-combobox-filled-focused-selected-option-container-color — #262626 · 10%
--tanrei-comp-combobox-filled-focused-selected-option-label-color — #262626
--tanrei-comp-combobox-filled-focused-selected-option-leading-icon-color — #262626
--tanrei-comp-combobox-filled-focused-selected-option-mark-color — #1b1b1b
--tanrei-comp-combobox-filled-focused-selected-option-state-layer-color — #262626
--tanrei-comp-combobox-filled-focused-selected-option-supporting-text-color — #262626
--tanrei-comp-combobox-filled-hovered-option-container-color — #1b1b1b · 8%
--tanrei-comp-combobox-filled-hovered-option-label-color — #1b1b1b
--tanrei-comp-combobox-filled-hovered-option-leading-icon-color — #4b4b4b
--tanrei-comp-combobox-filled-hovered-option-state-layer-color — #1b1b1b
--tanrei-comp-combobox-filled-hovered-option-supporting-text-color — #4b4b4b
--tanrei-comp-combobox-filled-hovered-selected-option-container-color — #262626 · 8%
--tanrei-comp-combobox-filled-hovered-selected-option-label-color — #262626
--tanrei-comp-combobox-filled-hovered-selected-option-leading-icon-color — #262626
--tanrei-comp-combobox-filled-hovered-selected-option-mark-color — #1b1b1b
--tanrei-comp-combobox-filled-hovered-selected-option-state-layer-color — #262626
--tanrei-comp-combobox-filled-hovered-selected-option-supporting-text-color — #262626
--tanrei-comp-combobox-filled-option-container-color — #000000 · 0%
--tanrei-comp-combobox-filled-option-label-color sys.color.on-surface #1b1b1b
--tanrei-comp-combobox-filled-option-leading-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-combobox-filled-option-state-layer-color comp.combobox.filled.option.label.color #1b1b1b
--tanrei-comp-combobox-filled-option-supporting-text-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-combobox-filled-pressed-option-container-color — #1b1b1b · 10%
--tanrei-comp-combobox-filled-pressed-option-label-color — #1b1b1b
--tanrei-comp-combobox-filled-pressed-option-leading-icon-color — #4b4b4b
--tanrei-comp-combobox-filled-pressed-option-state-layer-color — #1b1b1b
--tanrei-comp-combobox-filled-pressed-option-supporting-text-color — #4b4b4b
--tanrei-comp-combobox-filled-pressed-selected-option-container-color — #262626 · 10%
--tanrei-comp-combobox-filled-pressed-selected-option-label-color — #262626
--tanrei-comp-combobox-filled-pressed-selected-option-leading-icon-color — #262626
--tanrei-comp-combobox-filled-pressed-selected-option-mark-color — #1b1b1b
--tanrei-comp-combobox-filled-pressed-selected-option-state-layer-color — #262626
--tanrei-comp-combobox-filled-pressed-selected-option-supporting-text-color — #262626
--tanrei-comp-combobox-filled-selected-option-container-color sys.color.secondary-container #262626 · 0%
--tanrei-comp-combobox-filled-selected-option-label-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-filled-selected-option-leading-icon-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-filled-selected-option-mark-color sys.color.primary #1b1b1b
--tanrei-comp-combobox-filled-selected-option-state-layer-color comp.combobox.filled.selected-option.label.color #262626
--tanrei-comp-combobox-filled-selected-option-supporting-text-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-focused-opacity — 1
--tanrei-comp-combobox-group-title-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-combobox-group-title-padding-inline-medium comp.combobox.option.padding-inline.medium 12px
--tanrei-comp-combobox-group-title-padding-inline-small comp.combobox.option.padding-inline.small 8px
--tanrei-comp-combobox-group-gap sys.space.space200 16px
--tanrei-comp-combobox-hovered-opacity — 1
--tanrei-comp-combobox-list-color sys.color.surface-bright #ffffff
--tanrei-comp-combobox-list-elevation sys.elevation.level2 0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 2px 0px rgb(0 0 0 / 0.04)
--tanrei-comp-combobox-list-max-height — 320px
--tanrei-comp-combobox-list-offset sys.space.space50 4px
--tanrei-comp-combobox-list-padding-block sys.space.space50 4px
--tanrei-comp-combobox-list-padding-inline sys.space.space50 4px
--tanrei-comp-combobox-list-shape sys.shape.corner.medium 8px
--tanrei-comp-combobox-list-viewport-margin sys.space.space100 8px
--tanrei-comp-combobox-motion-close-duration sys.motion.role.appear.anchored.exit 250ms
--tanrei-comp-combobox-motion-close-easing sys.motion.easing.exit cubic-bezier(0.3, 0, 1, 1)
--tanrei-comp-combobox-motion-feedback-duration sys.motion.role.feedback 450ms
--tanrei-comp-combobox-motion-open-duration sys.motion.role.appear.anchored.enter 300ms
--tanrei-comp-combobox-motion-open-easing sys.motion.easing.enter cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-combobox-motion-state-duration sys.motion.role.state.default 250ms
--tanrei-comp-combobox-motion-state-easing sys.motion.easing.state cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-combobox-option-gap-medium sys.space.space150 12px
--tanrei-comp-combobox-option-gap-small comp.menu.container.gap.small 8px
--tanrei-comp-combobox-option-height-medium — 40px
--tanrei-comp-combobox-option-height-small comp.menu.container.height.small 36px
--tanrei-comp-combobox-option-leading-icon-size-medium sys.icon.medium 24px
--tanrei-comp-combobox-option-leading-icon-size-small comp.menu.leading-icon.size.small 20px
--tanrei-comp-combobox-option-mark-size-medium sys.icon.medium 24px
--tanrei-comp-combobox-option-mark-size-small comp.menu.mark.size.small 20px
--tanrei-comp-combobox-option-match-color sys.color.on-surface #1b1b1b
--tanrei-comp-combobox-option-match-container-color sys.color.secondary-container #eeeeee
--tanrei-comp-combobox-option-match-emphasis sys.typescale.emphasis.label 100
--tanrei-comp-combobox-option-match-selected-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-option-match-selected-container-color sys.color.surface #ffffff
--tanrei-comp-combobox-option-padding-block-medium — 8px
--tanrei-comp-combobox-option-padding-block-small comp.menu.container.padding-block.small 8px
--tanrei-comp-combobox-option-padding-inline-medium sys.space.space150 12px
--tanrei-comp-combobox-option-padding-inline-small comp.menu.container.padding-inline.small 8px
--tanrei-comp-combobox-option-shape — 4px
--tanrei-comp-combobox-outlined-disabled-option-container-color — #000000 · 0%
--tanrei-comp-combobox-outlined-disabled-option-label-color — #1b1b1b · 38%
--tanrei-comp-combobox-outlined-disabled-option-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-combobox-outlined-disabled-option-state-layer-color — #1b1b1b · 38%
--tanrei-comp-combobox-outlined-disabled-option-supporting-text-color — #1b1b1b · 38%
--tanrei-comp-combobox-outlined-disabled-selected-option-container-color — #1b1b1b · 0%
--tanrei-comp-combobox-outlined-disabled-selected-option-label-color — #1b1b1b · 38%
--tanrei-comp-combobox-outlined-disabled-selected-option-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-combobox-outlined-disabled-selected-option-mark-color — #1b1b1b · 38%
--tanrei-comp-combobox-outlined-disabled-selected-option-state-layer-color — #1b1b1b · 38%
--tanrei-comp-combobox-outlined-disabled-selected-option-supporting-text-color — #1b1b1b · 38%
--tanrei-comp-combobox-outlined-focused-option-container-color — #1b1b1b · 10%
--tanrei-comp-combobox-outlined-focused-option-label-color — #1b1b1b
--tanrei-comp-combobox-outlined-focused-option-leading-icon-color — #4b4b4b
--tanrei-comp-combobox-outlined-focused-option-state-layer-color — #1b1b1b
--tanrei-comp-combobox-outlined-focused-option-supporting-text-color — #4b4b4b
--tanrei-comp-combobox-outlined-focused-selected-option-container-color — #262626 · 10%
--tanrei-comp-combobox-outlined-focused-selected-option-label-color — #262626
--tanrei-comp-combobox-outlined-focused-selected-option-leading-icon-color — #262626
--tanrei-comp-combobox-outlined-focused-selected-option-mark-color — #1b1b1b
--tanrei-comp-combobox-outlined-focused-selected-option-state-layer-color — #262626
--tanrei-comp-combobox-outlined-focused-selected-option-supporting-text-color — #262626
--tanrei-comp-combobox-outlined-hovered-option-container-color — #1b1b1b · 8%
--tanrei-comp-combobox-outlined-hovered-option-label-color — #1b1b1b
--tanrei-comp-combobox-outlined-hovered-option-leading-icon-color — #4b4b4b
--tanrei-comp-combobox-outlined-hovered-option-state-layer-color — #1b1b1b
--tanrei-comp-combobox-outlined-hovered-option-supporting-text-color — #4b4b4b
--tanrei-comp-combobox-outlined-hovered-selected-option-container-color — #262626 · 8%
--tanrei-comp-combobox-outlined-hovered-selected-option-label-color — #262626
--tanrei-comp-combobox-outlined-hovered-selected-option-leading-icon-color — #262626
--tanrei-comp-combobox-outlined-hovered-selected-option-mark-color — #1b1b1b
--tanrei-comp-combobox-outlined-hovered-selected-option-state-layer-color — #262626
--tanrei-comp-combobox-outlined-hovered-selected-option-supporting-text-color — #262626
--tanrei-comp-combobox-outlined-option-container-color — #000000 · 0%
--tanrei-comp-combobox-outlined-option-label-color sys.color.on-surface #1b1b1b
--tanrei-comp-combobox-outlined-option-leading-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-combobox-outlined-option-state-layer-color comp.combobox.outlined.option.label.color #1b1b1b
--tanrei-comp-combobox-outlined-option-supporting-text-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-combobox-outlined-pressed-option-container-color — #1b1b1b · 10%
--tanrei-comp-combobox-outlined-pressed-option-label-color — #1b1b1b
--tanrei-comp-combobox-outlined-pressed-option-leading-icon-color — #4b4b4b
--tanrei-comp-combobox-outlined-pressed-option-state-layer-color — #1b1b1b
--tanrei-comp-combobox-outlined-pressed-option-supporting-text-color — #4b4b4b
--tanrei-comp-combobox-outlined-pressed-selected-option-container-color — #262626 · 10%
--tanrei-comp-combobox-outlined-pressed-selected-option-label-color — #262626
--tanrei-comp-combobox-outlined-pressed-selected-option-leading-icon-color — #262626
--tanrei-comp-combobox-outlined-pressed-selected-option-mark-color — #1b1b1b
--tanrei-comp-combobox-outlined-pressed-selected-option-state-layer-color — #262626
--tanrei-comp-combobox-outlined-pressed-selected-option-supporting-text-color — #262626
--tanrei-comp-combobox-outlined-selected-option-container-color sys.color.secondary-container #262626 · 0%
--tanrei-comp-combobox-outlined-selected-option-label-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-outlined-selected-option-leading-icon-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-outlined-selected-option-mark-color sys.color.primary #1b1b1b
--tanrei-comp-combobox-outlined-selected-option-state-layer-color comp.combobox.outlined.selected-option.label.color #262626
--tanrei-comp-combobox-outlined-selected-option-supporting-text-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-pressed-opacity — 1
--tanrei-comp-combobox-separation sys.behavior.separation 0
--tanrei-comp-combobox-stacked-disabled-option-container-color — #000000 · 0%
--tanrei-comp-combobox-stacked-disabled-option-label-color — #1b1b1b · 38%
--tanrei-comp-combobox-stacked-disabled-option-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-combobox-stacked-disabled-option-state-layer-color — #1b1b1b · 38%
--tanrei-comp-combobox-stacked-disabled-option-supporting-text-color — #1b1b1b · 38%
--tanrei-comp-combobox-stacked-disabled-selected-option-container-color — #1b1b1b · 0%
--tanrei-comp-combobox-stacked-disabled-selected-option-label-color — #1b1b1b · 38%
--tanrei-comp-combobox-stacked-disabled-selected-option-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-combobox-stacked-disabled-selected-option-mark-color — #1b1b1b · 38%
--tanrei-comp-combobox-stacked-disabled-selected-option-state-layer-color — #1b1b1b · 38%
--tanrei-comp-combobox-stacked-disabled-selected-option-supporting-text-color — #1b1b1b · 38%
--tanrei-comp-combobox-stacked-focused-option-container-color — #1b1b1b · 10%
--tanrei-comp-combobox-stacked-focused-option-label-color — #1b1b1b
--tanrei-comp-combobox-stacked-focused-option-leading-icon-color — #4b4b4b
--tanrei-comp-combobox-stacked-focused-option-state-layer-color — #1b1b1b
--tanrei-comp-combobox-stacked-focused-option-supporting-text-color — #4b4b4b
--tanrei-comp-combobox-stacked-focused-selected-option-container-color — #262626 · 10%
--tanrei-comp-combobox-stacked-focused-selected-option-label-color — #262626
--tanrei-comp-combobox-stacked-focused-selected-option-leading-icon-color — #262626
--tanrei-comp-combobox-stacked-focused-selected-option-mark-color — #1b1b1b
--tanrei-comp-combobox-stacked-focused-selected-option-state-layer-color — #262626
--tanrei-comp-combobox-stacked-focused-selected-option-supporting-text-color — #262626
--tanrei-comp-combobox-stacked-hovered-option-container-color — #1b1b1b · 8%
--tanrei-comp-combobox-stacked-hovered-option-label-color — #1b1b1b
--tanrei-comp-combobox-stacked-hovered-option-leading-icon-color — #4b4b4b
--tanrei-comp-combobox-stacked-hovered-option-state-layer-color — #1b1b1b
--tanrei-comp-combobox-stacked-hovered-option-supporting-text-color — #4b4b4b
--tanrei-comp-combobox-stacked-hovered-selected-option-container-color — #262626 · 8%
--tanrei-comp-combobox-stacked-hovered-selected-option-label-color — #262626
--tanrei-comp-combobox-stacked-hovered-selected-option-leading-icon-color — #262626
--tanrei-comp-combobox-stacked-hovered-selected-option-mark-color — #1b1b1b
--tanrei-comp-combobox-stacked-hovered-selected-option-state-layer-color — #262626
--tanrei-comp-combobox-stacked-hovered-selected-option-supporting-text-color — #262626
--tanrei-comp-combobox-stacked-option-container-color — #000000 · 0%
--tanrei-comp-combobox-stacked-option-label-color sys.color.on-surface #1b1b1b
--tanrei-comp-combobox-stacked-option-leading-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-combobox-stacked-option-state-layer-color comp.combobox.stacked.option.label.color #1b1b1b
--tanrei-comp-combobox-stacked-option-supporting-text-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-combobox-stacked-pressed-option-container-color — #1b1b1b · 10%
--tanrei-comp-combobox-stacked-pressed-option-label-color — #1b1b1b
--tanrei-comp-combobox-stacked-pressed-option-leading-icon-color — #4b4b4b
--tanrei-comp-combobox-stacked-pressed-option-state-layer-color — #1b1b1b
--tanrei-comp-combobox-stacked-pressed-option-supporting-text-color — #4b4b4b
--tanrei-comp-combobox-stacked-pressed-selected-option-container-color — #262626 · 10%
--tanrei-comp-combobox-stacked-pressed-selected-option-label-color — #262626
--tanrei-comp-combobox-stacked-pressed-selected-option-leading-icon-color — #262626
--tanrei-comp-combobox-stacked-pressed-selected-option-mark-color — #1b1b1b
--tanrei-comp-combobox-stacked-pressed-selected-option-state-layer-color — #262626
--tanrei-comp-combobox-stacked-pressed-selected-option-supporting-text-color — #262626
--tanrei-comp-combobox-stacked-selected-option-container-color sys.color.secondary-container #262626 · 0%
--tanrei-comp-combobox-stacked-selected-option-label-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-stacked-selected-option-leading-icon-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-stacked-selected-option-mark-color sys.color.primary #1b1b1b
--tanrei-comp-combobox-stacked-selected-option-state-layer-color comp.combobox.stacked.selected-option.label.color #262626
--tanrei-comp-combobox-stacked-selected-option-supporting-text-color sys.color.on-secondary-container #262626
--tanrei-comp-combobox-status-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-combobox-status-error-color sys.color.error #cd262f
--tanrei-comp-input-box-active-indicator-width sys.border.hairline 1px
--tanrei-comp-input-box-affix-gap sys.space.space25 2px
--tanrei-comp-input-box-container-gap-large sys.space.space200 16px
--tanrei-comp-input-box-container-gap-medium sys.space.space200 16px
--tanrei-comp-input-box-container-gap-small sys.space.space100 8px
--tanrei-comp-input-box-container-height-large — 56px
--tanrei-comp-input-box-container-height-medium — 40px
--tanrei-comp-input-box-container-height-small — 36px
--tanrei-comp-input-box-container-padding-block-with-label-large — 4px
--tanrei-comp-input-box-container-padding-block-with-label-medium — 4px
--tanrei-comp-input-box-container-padding-block-with-label-small — 2px
--tanrei-comp-input-box-container-padding-block-large — 14px
--tanrei-comp-input-box-container-padding-block-medium — 6px
--tanrei-comp-input-box-container-padding-block-small — 6px
--tanrei-comp-input-box-container-padding-inline-with-icon-large sys.space.space150 12px
--tanrei-comp-input-box-container-padding-inline-with-icon-medium sys.space.space150 12px
--tanrei-comp-input-box-container-padding-inline-with-icon-small sys.space.space100 8px
--tanrei-comp-input-box-container-padding-inline-large sys.space.space200 16px
--tanrei-comp-input-box-container-padding-inline-medium sys.space.space200 16px
--tanrei-comp-input-box-container-padding-inline-small sys.space.space150 12px
--tanrei-comp-input-box-container-shape sys.shape.corner.small 6px
--tanrei-comp-input-box-container-shape-bottom sys.shape.corner.none 0px
--tanrei-comp-input-box-disabled-active-indicator-width — 1px
--tanrei-comp-input-box-disabled-opacity — 1
--tanrei-comp-input-box-disabled-outline-width — 1px
--tanrei-comp-input-box-filled-active-indicator-color sys.color.outline #848484
--tanrei-comp-input-box-filled-affix-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-filled-caret-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-filled-container-color sys.color.surface-container-highest #eeeeee
--tanrei-comp-input-box-filled-disabled-active-indicator-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-affix-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-caret-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-container-color — #eeeeee
--tanrei-comp-input-box-filled-disabled-error-active-indicator-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-error-affix-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-error-caret-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-error-container-color — #eeeeee
--tanrei-comp-input-box-filled-disabled-error-input-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-error-label-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-error-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-error-outline-color — #000000 · 0%
--tanrei-comp-input-box-filled-disabled-error-placeholder-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-error-required-asterisk-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-error-state-layer-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-error-trailing-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-input-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-label-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-outline-color — #000000 · 0%
--tanrei-comp-input-box-filled-disabled-placeholder-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-required-asterisk-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-state-layer-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-disabled-trailing-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-filled-error-active-indicator-color sys.color.error #cd262f
--tanrei-comp-input-box-filled-error-affix-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-filled-error-caret-color sys.color.error #cd262f
--tanrei-comp-input-box-filled-error-container-color sys.color.surface-container-highest #eeeeee
--tanrei-comp-input-box-filled-error-input-color sys.color.on-surface #1b1b1b
--tanrei-comp-input-box-filled-error-label-color sys.color.error #cd262f
--tanrei-comp-input-box-filled-error-leading-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-filled-error-outline-color — #000000 · 0%
--tanrei-comp-input-box-filled-error-placeholder-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-filled-error-required-asterisk-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-filled-error-state-layer-color comp.input-box.filled.error.input.color #1b1b1b
--tanrei-comp-input-box-filled-error-trailing-icon-color sys.color.error #cd262f
--tanrei-comp-input-box-filled-focused-active-indicator-color — #0070ac
--tanrei-comp-input-box-filled-focused-affix-color — #4b4b4b
--tanrei-comp-input-box-filled-focused-caret-color — #1b1b1b
--tanrei-comp-input-box-filled-focused-container-color — #eeeeee
--tanrei-comp-input-box-filled-focused-error-active-indicator-color — #cd262f
--tanrei-comp-input-box-filled-focused-error-affix-color — #4b4b4b
--tanrei-comp-input-box-filled-focused-error-caret-color — #cd262f
--tanrei-comp-input-box-filled-focused-error-container-color — #eeeeee
--tanrei-comp-input-box-filled-focused-error-input-color — #1b1b1b
--tanrei-comp-input-box-filled-focused-error-label-color — #cd262f
--tanrei-comp-input-box-filled-focused-error-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-filled-focused-error-outline-color — #000000 · 0%
--tanrei-comp-input-box-filled-focused-error-placeholder-color — #4b4b4b
--tanrei-comp-input-box-filled-focused-error-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-filled-focused-error-state-layer-color — #1b1b1b
--tanrei-comp-input-box-filled-focused-error-trailing-icon-color — #cd262f
--tanrei-comp-input-box-filled-focused-input-color — #1b1b1b
--tanrei-comp-input-box-filled-focused-label-color — #1b1b1b
--tanrei-comp-input-box-filled-focused-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-filled-focused-outline-color — #000000 · 0%
--tanrei-comp-input-box-filled-focused-placeholder-color — #4b4b4b
--tanrei-comp-input-box-filled-focused-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-filled-focused-state-layer-color — #1b1b1b
--tanrei-comp-input-box-filled-focused-trailing-icon-color — #4b4b4b
--tanrei-comp-input-box-filled-hovered-active-indicator-color — #1b1b1b
--tanrei-comp-input-box-filled-hovered-affix-color — #4b4b4b
--tanrei-comp-input-box-filled-hovered-caret-color — #1b1b1b
--tanrei-comp-input-box-filled-hovered-container-color — #dddddd
--tanrei-comp-input-box-filled-hovered-error-active-indicator-color — #cd262f
--tanrei-comp-input-box-filled-hovered-error-affix-color — #4b4b4b
--tanrei-comp-input-box-filled-hovered-error-caret-color — #cd262f
--tanrei-comp-input-box-filled-hovered-error-container-color — #dddddd
--tanrei-comp-input-box-filled-hovered-error-input-color — #1b1b1b
--tanrei-comp-input-box-filled-hovered-error-label-color — #cd262f
--tanrei-comp-input-box-filled-hovered-error-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-filled-hovered-error-outline-color — #000000 · 0%
--tanrei-comp-input-box-filled-hovered-error-placeholder-color — #4b4b4b
--tanrei-comp-input-box-filled-hovered-error-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-filled-hovered-error-state-layer-color — #1b1b1b
--tanrei-comp-input-box-filled-hovered-error-trailing-icon-color — #cd262f
--tanrei-comp-input-box-filled-hovered-input-color — #1b1b1b
--tanrei-comp-input-box-filled-hovered-label-color — #4b4b4b
--tanrei-comp-input-box-filled-hovered-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-filled-hovered-outline-color — #000000 · 0%
--tanrei-comp-input-box-filled-hovered-placeholder-color — #4b4b4b
--tanrei-comp-input-box-filled-hovered-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-filled-hovered-state-layer-color — #1b1b1b
--tanrei-comp-input-box-filled-hovered-trailing-icon-color — #4b4b4b
--tanrei-comp-input-box-filled-input-color sys.color.on-surface #1b1b1b
--tanrei-comp-input-box-filled-label-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-filled-leading-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-filled-outline-color — #000000 · 0%
--tanrei-comp-input-box-filled-placeholder-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-filled-required-asterisk-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-filled-state-layer-color comp.input-box.filled.input.color #1b1b1b
--tanrei-comp-input-box-filled-trailing-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-focused-active-indicator-width — 2px
--tanrei-comp-input-box-focused-opacity — 1
--tanrei-comp-input-box-focused-outline-width — 2px
--tanrei-comp-input-box-hovered-active-indicator-width — 1px
--tanrei-comp-input-box-hovered-opacity — 1
--tanrei-comp-input-box-hovered-outline-width — 1px
--tanrei-comp-input-box-icon-size-large sys.icon.medium 24px
--tanrei-comp-input-box-icon-size-medium sys.icon.medium 24px
--tanrei-comp-input-box-icon-size-small sys.icon.small 20px
--tanrei-comp-input-box-motion-label-duration sys.motion.role.state.default 250ms
--tanrei-comp-input-box-motion-label-easing sys.motion.easing.state cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-input-box-motion-state-duration-large sys.motion.role.state.default 250ms
--tanrei-comp-input-box-motion-state-duration-medium sys.motion.role.state.default 250ms
--tanrei-comp-input-box-motion-state-duration-small sys.motion.role.state.compact 200ms
--tanrei-comp-input-box-motion-state-easing sys.motion.easing.state cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-input-box-outline-notch-padding sys.space.space50 4px
--tanrei-comp-input-box-outline-width sys.border.hairline 1px
--tanrei-comp-input-box-outlined-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-outlined-affix-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-outlined-caret-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-outlined-container-color — #000000 · 0%
--tanrei-comp-input-box-outlined-disabled-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-outlined-disabled-affix-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-caret-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-container-color — #000000 · 0%
--tanrei-comp-input-box-outlined-disabled-error-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-outlined-disabled-error-affix-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-error-caret-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-error-container-color — #000000 · 0%
--tanrei-comp-input-box-outlined-disabled-error-input-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-error-label-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-error-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-error-outline-color — #1b1b1b · 12%
--tanrei-comp-input-box-outlined-disabled-error-placeholder-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-error-required-asterisk-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-error-state-layer-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-error-trailing-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-input-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-label-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-outline-color — #1b1b1b · 12%
--tanrei-comp-input-box-outlined-disabled-placeholder-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-required-asterisk-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-state-layer-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-disabled-trailing-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-outlined-error-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-outlined-error-affix-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-outlined-error-caret-color sys.color.error #cd262f
--tanrei-comp-input-box-outlined-error-container-color — #000000 · 0%
--tanrei-comp-input-box-outlined-error-input-color sys.color.on-surface #1b1b1b
--tanrei-comp-input-box-outlined-error-label-color sys.color.error #cd262f
--tanrei-comp-input-box-outlined-error-leading-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-outlined-error-outline-color sys.color.error #cd262f
--tanrei-comp-input-box-outlined-error-placeholder-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-outlined-error-required-asterisk-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-outlined-error-state-layer-color comp.input-box.outlined.error.input.color #1b1b1b
--tanrei-comp-input-box-outlined-error-trailing-icon-color sys.color.error #cd262f
--tanrei-comp-input-box-outlined-focused-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-outlined-focused-affix-color — #4b4b4b
--tanrei-comp-input-box-outlined-focused-caret-color — #1b1b1b
--tanrei-comp-input-box-outlined-focused-container-color — #000000 · 0%
--tanrei-comp-input-box-outlined-focused-error-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-outlined-focused-error-affix-color — #4b4b4b
--tanrei-comp-input-box-outlined-focused-error-caret-color — #cd262f
--tanrei-comp-input-box-outlined-focused-error-container-color — #000000 · 0%
--tanrei-comp-input-box-outlined-focused-error-input-color — #1b1b1b
--tanrei-comp-input-box-outlined-focused-error-label-color — #cd262f
--tanrei-comp-input-box-outlined-focused-error-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-outlined-focused-error-outline-color — #cd262f
--tanrei-comp-input-box-outlined-focused-error-placeholder-color — #4b4b4b
--tanrei-comp-input-box-outlined-focused-error-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-outlined-focused-error-state-layer-color — #1b1b1b
--tanrei-comp-input-box-outlined-focused-error-trailing-icon-color — #cd262f
--tanrei-comp-input-box-outlined-focused-input-color — #1b1b1b
--tanrei-comp-input-box-outlined-focused-label-color — #1b1b1b
--tanrei-comp-input-box-outlined-focused-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-outlined-focused-outline-color — #0070ac
--tanrei-comp-input-box-outlined-focused-placeholder-color — #4b4b4b
--tanrei-comp-input-box-outlined-focused-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-outlined-focused-state-layer-color — #1b1b1b
--tanrei-comp-input-box-outlined-focused-trailing-icon-color — #4b4b4b
--tanrei-comp-input-box-outlined-hovered-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-outlined-hovered-affix-color — #4b4b4b
--tanrei-comp-input-box-outlined-hovered-caret-color — #1b1b1b
--tanrei-comp-input-box-outlined-hovered-container-color — #000000 · 0%
--tanrei-comp-input-box-outlined-hovered-error-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-outlined-hovered-error-affix-color — #4b4b4b
--tanrei-comp-input-box-outlined-hovered-error-caret-color — #cd262f
--tanrei-comp-input-box-outlined-hovered-error-container-color — #000000 · 0%
--tanrei-comp-input-box-outlined-hovered-error-input-color — #1b1b1b
--tanrei-comp-input-box-outlined-hovered-error-label-color — #cd262f
--tanrei-comp-input-box-outlined-hovered-error-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-outlined-hovered-error-outline-color — #cd262f
--tanrei-comp-input-box-outlined-hovered-error-placeholder-color — #4b4b4b
--tanrei-comp-input-box-outlined-hovered-error-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-outlined-hovered-error-state-layer-color — #1b1b1b
--tanrei-comp-input-box-outlined-hovered-error-trailing-icon-color — #cd262f
--tanrei-comp-input-box-outlined-hovered-input-color — #1b1b1b
--tanrei-comp-input-box-outlined-hovered-label-color — #4b4b4b
--tanrei-comp-input-box-outlined-hovered-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-outlined-hovered-outline-color — #1b1b1b
--tanrei-comp-input-box-outlined-hovered-placeholder-color — #4b4b4b
--tanrei-comp-input-box-outlined-hovered-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-outlined-hovered-state-layer-color — #1b1b1b
--tanrei-comp-input-box-outlined-hovered-trailing-icon-color — #4b4b4b
--tanrei-comp-input-box-outlined-input-color sys.color.on-surface #1b1b1b
--tanrei-comp-input-box-outlined-label-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-outlined-leading-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-outlined-outline-color sys.color.outline #848484
--tanrei-comp-input-box-outlined-placeholder-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-outlined-required-asterisk-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-outlined-state-layer-color comp.input-box.outlined.input.color #1b1b1b
--tanrei-comp-input-box-outlined-trailing-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-requirement-asterisk-gap sys.space.space25 2px
--tanrei-comp-input-box-selection-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-selection-content-color sys.color.on-primary #ffffff
--tanrei-comp-input-box-stacked-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-stacked-affix-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-stacked-caret-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-stacked-container-color sys.color.surface-container-highest #eeeeee
--tanrei-comp-input-box-stacked-container-height-large comp.button.container.height.large 56px
--tanrei-comp-input-box-stacked-container-height-medium comp.button.container.height.medium 40px
--tanrei-comp-input-box-stacked-container-height-small comp.button.container.height.small 36px
--tanrei-comp-input-box-stacked-container-padding-block-large — 14px
--tanrei-comp-input-box-stacked-container-padding-block-medium — 6px
--tanrei-comp-input-box-stacked-container-padding-block-small — 6px
--tanrei-comp-input-box-stacked-disabled-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-stacked-disabled-affix-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-caret-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-container-color — #eeeeee
--tanrei-comp-input-box-stacked-disabled-error-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-stacked-disabled-error-affix-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-error-caret-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-error-container-color — #eeeeee
--tanrei-comp-input-box-stacked-disabled-error-input-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-error-label-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-error-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-error-outline-color — #000000 · 0%
--tanrei-comp-input-box-stacked-disabled-error-placeholder-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-error-required-asterisk-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-error-state-layer-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-error-trailing-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-input-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-label-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-leading-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-outline-color — #000000 · 0%
--tanrei-comp-input-box-stacked-disabled-placeholder-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-required-asterisk-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-state-layer-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-disabled-trailing-icon-color — #1b1b1b · 38%
--tanrei-comp-input-box-stacked-error-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-stacked-error-affix-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-stacked-error-caret-color sys.color.error #cd262f
--tanrei-comp-input-box-stacked-error-container-color sys.color.surface-container-highest #eeeeee
--tanrei-comp-input-box-stacked-error-input-color sys.color.on-surface #1b1b1b
--tanrei-comp-input-box-stacked-error-label-color sys.color.on-surface #1b1b1b
--tanrei-comp-input-box-stacked-error-leading-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-stacked-error-outline-color sys.color.error #cd262f
--tanrei-comp-input-box-stacked-error-placeholder-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-stacked-error-required-asterisk-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-stacked-error-state-layer-color comp.input-box.stacked.error.input.color #1b1b1b
--tanrei-comp-input-box-stacked-error-trailing-icon-color sys.color.error #cd262f
--tanrei-comp-input-box-stacked-focused-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-stacked-focused-affix-color — #4b4b4b
--tanrei-comp-input-box-stacked-focused-caret-color — #1b1b1b
--tanrei-comp-input-box-stacked-focused-container-color — #eeeeee
--tanrei-comp-input-box-stacked-focused-error-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-stacked-focused-error-affix-color — #4b4b4b
--tanrei-comp-input-box-stacked-focused-error-caret-color — #cd262f
--tanrei-comp-input-box-stacked-focused-error-container-color — #eeeeee
--tanrei-comp-input-box-stacked-focused-error-input-color — #1b1b1b
--tanrei-comp-input-box-stacked-focused-error-label-color — #1b1b1b
--tanrei-comp-input-box-stacked-focused-error-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-stacked-focused-error-outline-color — #cd262f
--tanrei-comp-input-box-stacked-focused-error-placeholder-color — #4b4b4b
--tanrei-comp-input-box-stacked-focused-error-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-stacked-focused-error-state-layer-color — #1b1b1b
--tanrei-comp-input-box-stacked-focused-error-trailing-icon-color — #cd262f
--tanrei-comp-input-box-stacked-focused-input-color — #1b1b1b
--tanrei-comp-input-box-stacked-focused-label-color — #1b1b1b
--tanrei-comp-input-box-stacked-focused-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-stacked-focused-outline-color — #0070ac
--tanrei-comp-input-box-stacked-focused-placeholder-color — #4b4b4b
--tanrei-comp-input-box-stacked-focused-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-stacked-focused-state-layer-color — #1b1b1b
--tanrei-comp-input-box-stacked-focused-trailing-icon-color — #4b4b4b
--tanrei-comp-input-box-stacked-hovered-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-stacked-hovered-affix-color — #4b4b4b
--tanrei-comp-input-box-stacked-hovered-caret-color — #1b1b1b
--tanrei-comp-input-box-stacked-hovered-container-color — #dddddd
--tanrei-comp-input-box-stacked-hovered-error-active-indicator-color — #000000 · 0%
--tanrei-comp-input-box-stacked-hovered-error-affix-color — #4b4b4b
--tanrei-comp-input-box-stacked-hovered-error-caret-color — #cd262f
--tanrei-comp-input-box-stacked-hovered-error-container-color — #dddddd
--tanrei-comp-input-box-stacked-hovered-error-input-color — #1b1b1b
--tanrei-comp-input-box-stacked-hovered-error-label-color — #1b1b1b
--tanrei-comp-input-box-stacked-hovered-error-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-stacked-hovered-error-outline-color — #cd262f
--tanrei-comp-input-box-stacked-hovered-error-placeholder-color — #4b4b4b
--tanrei-comp-input-box-stacked-hovered-error-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-stacked-hovered-error-state-layer-color — #1b1b1b
--tanrei-comp-input-box-stacked-hovered-error-trailing-icon-color — #cd262f
--tanrei-comp-input-box-stacked-hovered-input-color — #1b1b1b
--tanrei-comp-input-box-stacked-hovered-label-color — #1b1b1b
--tanrei-comp-input-box-stacked-hovered-leading-icon-color — #4b4b4b
--tanrei-comp-input-box-stacked-hovered-outline-color — #000000 · 0%
--tanrei-comp-input-box-stacked-hovered-placeholder-color — #4b4b4b
--tanrei-comp-input-box-stacked-hovered-required-asterisk-color — #1b1b1b
--tanrei-comp-input-box-stacked-hovered-state-layer-color — #1b1b1b
--tanrei-comp-input-box-stacked-hovered-trailing-icon-color — #4b4b4b
--tanrei-comp-input-box-stacked-input-color sys.color.on-surface #1b1b1b
--tanrei-comp-input-box-stacked-label-color sys.color.on-surface #1b1b1b
--tanrei-comp-input-box-stacked-leading-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-stacked-outline-color — #000000 · 0%
--tanrei-comp-input-box-stacked-placeholder-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-input-box-stacked-required-asterisk-color sys.color.primary #1b1b1b
--tanrei-comp-input-box-stacked-state-layer-color comp.input-box.stacked.input.color #1b1b1b
--tanrei-comp-input-box-stacked-trailing-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-combobox-group-title-typescale sys.typescale.label-small 500 12px/1.3333
--tanrei-comp-combobox-option-label-typescale sys.typescale.label 500 14px/1.4286
--tanrei-comp-combobox-option-supporting-text-typescale sys.typescale.body-small 400 13px/1.5385
--tanrei-comp-combobox-status-typescale sys.typescale.body-small 400 13px/1.5385
--tanrei-comp-input-box-input-typescale-large sys.typescale.body-large 400 16px/1.625
--tanrei-comp-input-box-input-typescale-medium sys.typescale.body-large 400 16px/1.625
--tanrei-comp-input-box-input-typescale-small sys.typescale.body 400 14px/1.5714
--tanrei-comp-input-box-label-floated-typescale-large sys.typescale.label-small 500 12px/1.3333
--tanrei-comp-input-box-label-floated-typescale-medium sys.typescale.label-small 500 12px/1.3333
--tanrei-comp-input-box-label-floated-typescale-small sys.typescale.label-small 500 12px/1.3333
--tanrei-comp-input-box-label-typescale-large sys.typescale.label 500 14px/1.4286
--tanrei-comp-input-box-label-typescale-medium sys.typescale.label 500 14px/1.4286
--tanrei-comp-input-box-label-typescale-small sys.typescale.label 500 14px/1.4286

Fixtures

Canonical renderings. Every platform snapshots each fixture under the same id so the results can be compared.

Generated from specs/combobox.spec.json, tokens/comp/combobox.tokens.json, tokens/comp/input-box.tokens.json, design/tokens/

What the web draws differently

  • <tanrei-option> and <tanrei-option-group> are data: they draw nothing. They are the elements a select holds. An option whose value is the empty string is drawn and cannot be chosen, because the empty value means that nothing is chosen.
  • A <slot> element among the combobox’s children stands for the elements assigned to it. An element of your own that holds a combobox in its shadow root passes its own children on as the options this way, and they are read again whenever they change.
  • The element is form-associated. With a name it submits value and never the text of an edit that was not committed, resets to its value attribute, is restored on navigation, follows a disabled <fieldset>, and reports a missing value while its field says it is required.
  • The element is a block. focus() goes to the input, and a press anywhere on the box outside a button focuses it.
  • chevron and wrap are the inverse attributes no-chevron and no-wrap, and readOnly is readonly.
  • input is the native event of the text element. change and action are composed CustomEvents that carry detail.value and detail.inputValue; cancel action to keep Enter from submitting the form. toggle carries detail.open and, for a close, detail.reason; it is composed and does not bubble.
  • The list is a popover="manual" element in the top layer. A press outside closes it and also reaches the element under it.
  • Parts: container, outline, active-indicator, label, requirement-label, input, leading-icon, clear-button, chevron, list, option, option-label, option-supporting-text, option-leading-icon, mark, group, group-title, divider, status.
  • empty-text and clear-label left empty are read from the product’s words (setWords()).
  • Before the element is defined, its options are running text. Hide tanrei-combobox:not(:defined) > * and reserve the height.
  • With selection="multiple" the element submits each of values under its name, resets to its values attribute (a JSON array, or values separated by spaces), and change also carries detail.values.
  • Parts of the chosen values: entry (each chip), entry-container, entry-label and entry-remove.
  • remove-label, added-text and removed-text left empty are read from the product’s words entryRemoveLabel, entryAddedText and entryRemovedText, the ones the chip field reads.

Guidelines

Combobox, combobox field, or a field by hand

You need Use
A label, the box with its list, help and an error A combobox field
The box alone, under a label that stands elsewhere: a toolbar’s filter, a table’s cell, a row with its label beside it A combobox, named by its own label
Something of your own inside the frame, beside or below the box A field with a combobox and your own element in it
A closed list with no typing A select
Typing that leads to places to go rather than to a value A search
  • Give a bare combobox a label in the words of the visible label, or in words that say what the visible label and its place say together: “Assignee, release notes”.
  • Give a bare combobox its width by its place: a column of a grid, a cell, a toolbar’s item with a width.
  • Leave the chevron out (no-chevron) where suggestions exist only for what was typed.
  • Use the combobox field wherever a label above the box, help and an error are what you need.

Don’t

  • Don’t use a bare combobox in a form to save the room of a label.
  • Don’t use the placeholder as the label. It goes as soon as someone types, and it is never the name.
  • Don’t set label, error or disabled on a combobox inside a field. Say them on the field, so that the label and the help follow.
  • Don’t put a combobox field inside a field. It is a field already; the control a field frames is the combobox.
  • Don’t write supporting-text, error-text, required or optional on a combobox. They are a field’s, and a combobox draws none of them.

Accessibility

Focus order

Each number is a stop of the Tab key, in the order Tab reaches it; Shift+Tab goes back the same way. The component is live: press Tab to follow it. Drawn over the fixture stacked-clearable, as the web package draws it.
    Role
    combobox; while selection is multiple, after a list of the chosen values, and its listbox allows several selected options
    Labeling
    The accessible name is the label of the Field that frames the combobox, or its own label where no Field does; a filled or outlined combobox draws that name floating, and labelHidden only stops the drawing. The placeholder is never the name. The description is what the Field gives: its supporting text with, in error, the error text after it and its optional text. The combobox is exposed as invalid while error is true or its Field is in error, as required while its Field says so — whichever mark is drawn — and as read-only while readOnly is true. It is expanded while its list is open, and names its active option. Its name also names the list and the chevron's button. An option is named by its label and described by its supporting text, and exposes whether it is the chosen one, whether it is disabled, and its position among the options shown; a group is named by its title. The clear button is named by clearLabel. The status row is a live region. The leading glyphs, the check and the dividers are decorative.
    Minimum target
    The hit area meets the minimum target size even when the visual size is smaller. minimum 36px · pointer 36px · spacing 8px · touch 36px

    Keyboard

    Keys Action
    Tab or Shift Tab Moves focus to the input and on from it; the clear button, while shown, is the next stop. Leaving resolves the text (a typed label chooses its option, any other text is kept as the value or given up) and closes the list; the active option is not chosen.
    Typing Edits the text and opens the list, filtered. With allowCustomValue false the first match becomes the active option, read out once typing pauses for half a second; with it true none does.
    Down Arrow or Up Arrow (also with Alt), list closed Opens the list with every option; the chosen option is active, or the first enabled one.
    Down Arrow or Up Arrow , list open Makes the next or previous option active, across groups, and goes round at the ends — Down on the last to the first, Up on the first to the last — unless wrap is false, which stops them. With allowCustomValue true the text is the place before the first option: Up Arrow on the first returns to it with no option active, so that Enter keeps what was typed.
    Page Down or Page Up , list open Moves the active option by ten, stopping at the ends.
    Home or End or Left Arrow or Right Arrow Move the caret in the text, list open or closed.
    Enter , an option active Chooses it, emits change if the value changed, and closes the list. On a disabled option, nothing. It does not submit a form.
    Enter , no option active Commits the text: a typed label chooses its option; with allowCustomValue true any other text becomes the value. Then emits action and submits the enclosing form on the web. With allowCustomValue false a text that names no option is not committed and the list stays.
    Escape With the list open: closes it, choosing nothing and keeping the text. With the list closed and the text edited: restores the committed value's text. Otherwise the combobox does not act on it. It never clears a committed value.
    Enter or Space on the clear button Empties the text and the value and returns focus to the input.
    Enter , an option active, selection multiple Chooses it, or takes it out where it is chosen; the text empties and the list stays open with the option active. It does not submit a form.
    Enter , no option active, selection multiple A typed label chooses its option; with allowCustomValue true another text becomes a value of its own. On an empty text, emits action and submits the enclosing form on the web.
    Escape , selection multiple With the list open: closes it. With it closed: empties the typed text. It never removes a chosen value.
    Backspace , or the arrow toward the line's start, caret at the start, selection multiple Moves focus to the last chosen value; removes nothing.
    Arrow keys or Home or End on a chosen value Move among the chosen values the way the key points; past the last, back to the input. Escape and Tab return to the input.
    Backspace or Delete on a chosen value Removes it and moves focus to its neighbour, or to the input where none is left.
    Any of these while an input method is composing Belongs to the input method (CMB-16).

    Notes

    • The pattern is the WAI-ARIA editable combobox with a listbox popup: focus stays in the input and the active option is its active descendant on the web, as the search's suggestions are (SRC-14) and a select's options. The input keeps its name, its description, its invalid and required states and its focused edge while the person reads the options, and typing never stops editing the text.
    • Text entry happens in the platform's native text element: on the web an <input type="text" role="combobox"> in the shadow root with the label, the description and the states set on that element — not through ElementInternals, which axe cannot see.
    • While an input method composes, every key is the input method's (CMB-16): the Enter that confirms a conversion chooses nothing and submits nothing. A combobox that chose on that Enter cannot be used in Japanese, Chinese or Korean.
    • With allowCustomValue false, typing makes the first match active, so that Enter chooses what was found; a screen reader reads that option once typing pauses for half a second, not after every key. With allowCustomValue true nothing is active until an arrow key is pressed, so that Enter keeps what was typed, and the text is a stop of the arrow keys between the last option and the first. One rule in both: Enter commits what the field shows as about to be committed. The arrow keys go round at the ends unless wrap is false.
    • Leaving the field never chooses the active option (CMB-29): a pointer that rested on a row, or the first match of half a word, is not an answer. A whole label typed out is.
    • Escape closes, then restores, and never clears (CMB-30). Clearing is emptying the text, or the clear button.
    • The list does not open on focus (CMB-21): tabbing through a form would open a list over the next fields at every stop, and on a touch screen a list would rise together with the keyboard.
    • Errors are words: a text that names no option is given up, not kept as an error of the combobox's own, and the combobox reports no refusal to its Field (CMB-61); a product that wants to say "choose one from the list" sets error and errorText on the Field, or on the combobox field, from its change and input handlers.
    • A match is marked by weight (CMB-38), never by color alone and never announced: the label is read whole.
    • The chevron is a button for a pointer and for touch exploration, outside the focus order; the keyboard opens the list with Down Arrow.
    • Heights are minimums: at 200% text size the field grows, labels, options and titles wrap, and the list scrolls; only the text in the input stays on one line, and scrolls.
    • Web: a touch browser zooms the page into an input whose text is smaller than 16 px. Both sizes use 16 px text (comp.input-box.input.typescale.medium).
    • The combobox draws no frame: the label row, the requirement, the supporting row and the error are those of the Field that frames it (FLD-2 to FLD-13), and the combobox field is that pair as one component. A bare combobox is for a place whose label stands elsewhere — a toolbar, a table cell, a row of an editor — and is named by its own label. The list is an anchored surface by Popover's rules (POP-2 to POP-8, POP-18 to POP-27, POP-34, POP-36, POP-43) with the menu's look; it is not a Popover element, because its content is rows with one meaning, not content of any kind.
    • How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves.
    • The box is the combobox's own part, not a Text input placed in it: the native text element is itself the combobox — it carries the role, the expanded state and the relations to the list and to the active option, which must stand in one tree with it — and the keys, the text a choice writes and the commit are the combobox's. Its drawing is the box every input control is drawn on, from the one set of tokens `comp.input-box` that the text input, the select, the number input and the color input read too (CMB-63): the two are one drawing, and neither is built from the other.
    • WCAG 2.5.8 (target size): every option is drawn at least the touch target high for touch and the pointer target high for a fine pointer, at every size (CMB-34), because rows that touch cannot reach past each other. In the default system both are the minimum target, at which a small option is held; a system that sets either higher draws its small options that high.
    • Several values (selection multiple) follow the APG combobox with a listbox that allows several selected options: aria-multiselectable on the listbox and aria-selected on each option, as every other Tanrei list says selection. The chosen values stand before the input as input Chips in a list named by the combobox's name, each with a remove action named in the product's words, and a live region says what was added or removed.
    • While selection is multiple the list stays open after a choice, so that several values can be chosen in a row, and the typed text empties, so that the next search starts from nothing: as Ant Design's Select in mode multiple, Carbon's multiselect and Mantine's MultiSelect do (MUI's Autocomplete closes unless disableCloseOnSelect is set). Leaving chooses nothing and empties the text, as MUI's Autocomplete and Ant Design's Select clear the search on blur: a value is added only by a choice.
    • Backspace on an empty input moves focus to the last chosen value and removes nothing; a second Backspace removes it. MUI, Ant Design and Mantine remove the last value at once; Tanrei follows its own chip field (CHF-12), so that the two fields of one product answer the same key the same way and a value is never removed by a key whose effect was not seen first: the focused chip is read out before it can be removed.

    Generated from specs/combobox.spec.json, tokens/sys/measure.tokens.json

    What the component handles

    • The input is an editable combobox with a list box. Its name is its own label, or the label of the field around it where it has none. The placeholder is never the name.
    • Its description is what its field gives: the help or the error text, and the optional text.
    • It is exposed as invalid while in error, as required while its field says so, as read-only and disabled, and as expanded while its list is open.
    • Focus stays in the input while the list is open. The active option is its active descendant, so typing never stops editing the text. An option that typing made active is named once typing pauses for half a second, so that a screen reader reads the typed letter first and then the option Enter would choose; an option the arrow keys move to is named at once.
    • The list is a list box of the same name. Each option has its name, its description, whether it is the chosen one, whether it is disabled, and its position among the options shown. A group is named by its title.
    • The status row is a live region: its text is read politely when it changes, and at once when the source failed.
    • The chevron is a button of the same name, outside the focus order. The clear button is named by clearLabel, and is the next focus stop after the input.
    • Focus is shown by the box’s own edge, from the keyboard and from a pointer alike. The hit area meets the minimum target.
    • The asterisk after a floating label is hidden from assistive technology: the required state already says it.
    • A missing name is reported in debug builds.
    • With several values, the list box says that several options can be selected, and each option whether it is selected. The chosen values are a list named like the combobox, each a chip with a remove button named by removeLabel. A polite live region says what the person added or removed, in addedText and removedText.

    What you need to do

    • Name every bare combobox with label. A visible text beside it does not name it.
    • Where a bare combobox can be wrong, say what is wrong in words that reach assistive technology: a message of your own tied to the page, or a field around the combobox.
    • Give every option a label and a value that is not empty, and keep the values unique.
    • Give a clearable combobox a clearLabel, and write emptyText and statusText.
    • With several values, give removeLabel with the place {entry}, and addedText and removedText, in the product’s language, or set them once for every field with setWords().