form-field — wyrd.component.combobox

Combobox

Single-select autocomplete field with popup suggestions, canonical selected value, and component-owned empty-state localization.

Install @wyrd-company/react or the Flutter package and use it directly — your DESIGN.md does the styling.

catalog/contracts/combobox.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: Combobox  tag: wyrd-combobox  package: wyrd.component.combobox  title: Combobox  summary: Single-select autocomplete field with popup suggestions, canonical selected value, and component-owned empty-state localization.relationships:  related-to:    - collection-navigation    - quality-parity-and-gatesclassification:  category: form-field  composition: collection  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: value      type:        kind: string      required: false      controlled: true      serializable: true      summary: Controlled selected option value; free-text values are not accepted.    - name: default-value      type:        kind: string      required: false      serializable: true      summary: Initial uncontrolled selected option value.    - name: options      type:        kind: array        item:          kind: object          fields:            value:              kind: string            label:              kind: string            disabled:              kind: boolean      required: false      default: []      serializable: true      summary: Ordered selectable option items; disabled items render but are skipped by navigation and activation.    - name: placeholder      type:        kind: string      required: false      serializable: true      summary: Placeholder text shown when no option is selected and no filter text is entered.    - name: is-open      type:        kind: boolean      required: false      default: false      controlled: true      reflects: true      serializable: true      summary: Controlled suggestion popup visibility.    - name: default-open      type:        kind: boolean      required: false      default: false      serializable: true      summary: Initial uncontrolled suggestion popup visibility.    - name: is-disabled      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Prevents text editing, popup opening, and option activation.    - name: is-required      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Marks the field as requiring one selected option.    - name: is-invalid      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Marks the selection as invalid and associates the error slot.    - name: active-index      type:        kind: integer        minimum: 0      required: false      default: 0      serializable: true      summary: Initial active suggestion index when the popup opens.  slots:    - name: label      required: true      cardinality: exactly-one      accepts:        - text      summary: Visible label and accessible-name source.    - name: description      required: false      cardinality: zero-or-one      accepts:        - text      summary: Help text associated with the input.    - name: error      required: false      cardinality: zero-or-one      accepts:        - text      summary: Validation error associated when is-invalid is true.  events:    - name: value-change      payload:        value:          kind: string        action:          kind: action-ref      bubbles: true      composed: true      cancelable: false      summary: Canonical value-change event carrying the selected option value.    - name: open-change      payload:        is-open:          kind: boolean        reason:          kind: enum          values:            - input            - trigger            - keyboard            - dismiss            - select            - programmatic      bubbles: true      composed: true      cancelable: false      summary: Canonical suggestion popup visibility event.    - name: option-select      payload:        index:          kind: integer        value:          kind: string        action:          kind: action-ref      bubbles: true      composed: true      cancelable: true      summary: Canonical suggestion activation event emitted once per accepted selection.  states:    - name: closed      source: behavior-runtime      summary: Suggestion popup is not visible.    - name: open      source: behavior-runtime      summary: Suggestion popup is visible.    - name: focused      source: platform      summary: Text input owns focus.    - name: selected      source: property      summary: State when value or default-value matches an option.    - name: disabled      source: property      summary: Disabled state derived from is-disabled.    - name: invalid      source: property      summary: Invalid state derived from is-invalid.    - name: required      source: property      summary: Required state derived from is-required.  parts:    - name: root      summary: Field root and popup positioning owner.      slots:        - label        - description        - error    - name: label      summary: Label text.      slots:        - label    - name: input      summary: Editable combobox input control.    - name: popup      summary: Suggestion popup surface.    - name: option      summary: Repeated suggestion option container.    - name: empty-state      summary: Localized empty-state row shown when no option matches the filter.    - name: description      summary: Description text.      slots:        - description    - name: error      summary: Error text.      slots:        - error  tokens:    root:      gap: spacing.xs    label:      color: color.on-surface      text: typography.label-md    input:      background: color.surface      foreground: color.on-surface      placeholder: color.on-surface-variant      border-color: color.outline      border-color-focus: color.primary      border-color-invalid: color.error      border-width: 1px      radius: rounded.sm      padding-x: spacing.md      padding-y: spacing.sm      text: typography.body-md    popup:      background: color.surface-container      foreground: color.on-surface      border-color: color.outline      radius: rounded.md      shadow: shadow.md      padding-y: spacing.xs    option:      foreground: color.on-surface      foreground-active: color.on-primary      background-hover: color.secondary      background-active: color.primary-hover      background-selected: color.secondary      padding-x: spacing.md      padding-y: spacing.sm    empty-state:      foreground: color.on-surface-variant      padding-x: spacing.md      padding-y: spacing.sm    description:      color: color.on-surface-variant      text: typography.body-md    error:      color: color.error      text: typography.body-mdmessages:  - key: combobox.no-options    description: Empty-state text shown by the combobox popup when filtering leaves no matching options.obligations:  accessibility:    role: combobox    name: Label slot provides the accessible name.    description: Description and error slots are programmatically associated with the input.    keyboard:      - Text input follows platform editing keys.      - ArrowDown and ArrowUp open suggestions and move the active option, skipping disabled options.      - Enter accepts the active enabled option when the popup is open.      - Escape closes the popup without changing the selected value.      - Tab leaves the field and closes the popup.    semantics:      - Input exposes combobox, expanded, autocomplete=list, aria-controls, and aria-activedescendant semantics on web.      - Web listbox and option IDREF targets must live in the same root as the input.      - Required, invalid, and disabled states are exposed through platform semantics.      - Error text is associated only when invalid.  behavior:    model: collection    interactions:      - Typing filters options by label, opens the popup, and clears the active option when no enabled match remains.      - Selecting an enabled option commits its value, emits option-select and value-change, closes the popup, and displays the selected option label.      - Enter only commits an enabled option value; arbitrary filter text is not a value in v1.      - Controlled value and is-open properties win over default-value and default-open.    hostEffects:      - Focus the input for keyboard entry.      - Dispatch value-change, open-change, and option-select events.      - Keep popup positioning synchronized with the input control.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion    - keyboard-inset  sdui:    status: serializable    serializableProperties:      - value      - default-value      - options      - placeholder      - is-open      - default-open      - is-disabled      - is-required      - is-invalid      - active-index    serializableSlots:      - label      - description      - error    eventBindings:      - value-change      - open-change      - option-select    notes: Option data, selected value, and open state serialize; popup positioning, focus, filtering query, and keyboard host effects remain target-local.examples:  - name: empty    state: closed    properties:      placeholder: Choose a spell      options:        - value: light          label: Light        - value: shield          label: Shield        - value: misty-step          label: Misty Step    slots:      label: Spell      description: Pick the prepared spell to cast.  - name: selected    state: selected    properties:      default-value: shield      options:        - value: light          label: Light        - value: shield          label: Shield        - value: misty-step          label: Misty Step    slots:      label: Spell  - name: no-options    state: open    properties:      is-open: true      options: []    slots:      label: Spell      description: The popup shows the localized empty state when the typed filter has no matches.

Examples

Generated from the contract's examples block. Previews are the published @wyrd-company/react component, themed by the brand's role tokens — flip the site's light/dark toggle and they follow.

Code target React Flutter Applies to every example on component pages.

empty state: closed

Usage

import { WyrdCombobox } from "@wyrd-company/react";

<WyrdCombobox placeholder="Choose a spell" options={[{"value":"light","label":"Light"},{"value":"shield","label":"Shield"},{"value":"misty-step","label":"Misty Step"}]} label="Spell" description="Pick the prepared spell to cast." />

// events: onValueChange, onOpenChange, onOptionSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCombobox(
  placeholder: 'Choose a spell',
  options: [{"value":"light","label":"Light"},{"value":"shield","label":"Shield"},{"value":"misty-step","label":"Misty Step"}],
  label: Text('Spell'),
  description: Text('Pick the prepared spell to cast.'),
)

// events: onChanged, onOpenChanged, onOptionSelect

selected state: selected

Usage

import { WyrdCombobox } from "@wyrd-company/react";

<WyrdCombobox defaultValue="shield" options={[{"value":"light","label":"Light"},{"value":"shield","label":"Shield"},{"value":"misty-step","label":"Misty Step"}]} label="Spell" />

// events: onValueChange, onOpenChange, onOptionSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCombobox(
  initialValue: 'shield',
  options: [{"value":"light","label":"Light"},{"value":"shield","label":"Shield"},{"value":"misty-step","label":"Misty Step"}],
  label: Text('Spell'),
)

// events: onChanged, onOpenChanged, onOptionSelect

no-options state: open

Usage

import { WyrdCombobox } from "@wyrd-company/react";

<WyrdCombobox isOpen options={[]} label="Spell" description="The popup shows the localized empty state when the typed filter has no matches." />

// events: onValueChange, onOpenChange, onOptionSelect

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCombobox(
  isOpen: true,
  options: [],
  label: Text('Spell'),
  description: Text('The popup shows the localized empty state when the typed filter has no matches.'),
)

// events: onChanged, onOpenChanged, onOptionSelect

Properties

Name	Type	Default	Summary
`value`	`string`	`undefined`	Controlled selected option value; free-text values are not accepted.
`default-value`	`string`	`undefined`	Initial uncontrolled selected option value.
`options`	`array`		Ordered selectable option items; disabled items render but are skipped by navigation and activation.
`placeholder`	`string`	`undefined`	Placeholder text shown when no option is selected and no filter text is entered.
`is-open`	`boolean`	`false`	Controlled suggestion popup visibility.
`default-open`	`boolean`	`false`	Initial uncontrolled suggestion popup visibility.
`is-disabled`	`boolean`	`false`	Prevents text editing, popup opening, and option activation.
`is-required`	`boolean`	`false`	Marks the field as requiring one selected option.
`is-invalid`	`boolean`	`false`	Marks the selection as invalid and associates the error slot.
`active-index`	`integer`	`0`	Initial active suggestion index when the popup opens.

Slots & events

Slot	Cardinality	Accepts	Summary
`label`	exactly-one	`text`	Visible label and accessible-name source.
`description`	zero-or-one	`text`	Help text associated with the input.
`error`	zero-or-one	`text`	Validation error associated when is-invalid is true.

Event	Payload	Summary
`value-change`	`value, action`	Canonical value-change event carrying the selected option value.
`open-change`	`is-open, reason`	Canonical suggestion popup visibility event.
`option-select`	`index, value, action`	Canonical suggestion activation event emitted once per accepted selection.

Tokens

The contract's token bindings. Open the shared contextual sidebar from any example; primary swatches reflect the color you pick there. Error swatches show the active preset's values; editing any knob switches to custom and resets error to TWW · Ink.

Binding	Token
`root.gap`	`spacing.xs`
`label.color`	`color.on-surface`
`label.text`	`typography.label-md`
`input.background`	`color.surface`
`input.foreground`	`color.on-surface`
`input.placeholder`	`color.on-surface-variant`
`input.border-color`	`color.outline`
`input.border-color-focus`	`color.primary`
`input.border-color-invalid`	`color.error`
`input.border-width`	`1px`
`input.radius`	`rounded.sm`
`input.padding-x`	`spacing.md`
`input.padding-y`	`spacing.sm`
`input.text`	`typography.body-md`
`popup.background`	`color.surface-container`
`popup.foreground`	`color.on-surface`
`popup.border-color`	`color.outline`
`popup.radius`	`rounded.md`
`popup.shadow`	`shadow.md`
`popup.padding-y`	`spacing.xs`
`option.foreground`	`color.on-surface`
`option.foreground-active`	`color.on-primary`
`option.background-hover`	`color.secondary`
`option.background-active`	`color.primary-hover`
`option.background-selected`	`color.secondary`
`option.padding-x`	`spacing.md`
`option.padding-y`	`spacing.sm`
`empty-state.foreground`	`color.on-surface-variant`
`empty-state.padding-x`	`spacing.md`
`empty-state.padding-y`	`spacing.sm`
`description.color`	`color.on-surface-variant`
`description.text`	`typography.body-md`
`error.color`	`color.error`
`error.text`	`typography.body-md`

States

State	Source	Summary
`closed`	behavior-runtime	Suggestion popup is not visible.
`open`	behavior-runtime	Suggestion popup is visible.
`focused`	platform	Text input owns focus.
`selected`	property	State when value or default-value matches an option.
`disabled`	property	Disabled state derived from is-disabled.
`invalid`	property	Invalid state derived from is-invalid.
`required`	property	Required state derived from is-required.

SDUI

Status: serializable. Option data, selected value, and open state serialize; popup positioning, focus, filtering query, and keyboard host effects remain target-local.

Serializable	Members
Properties	`value, default-value, options, placeholder, is-open, default-open, is-disabled, is-required, is-invalid, active-index`
Slots	`label, description, error`
Events	`value-change, open-change, option-select`

  The Wyrding Way — a contract-first design system. © Wyrd Company 
   Pipeline demo
 Choose an example to inspect its pipeline context.
 Explore the shape of a brand's pipeline input: presets and knobs regenerate the illustrative excerpt below — not a compilable DESIGN.md (see the format reference). Primary swatches update live; accent, shape, density, and ground are excerpt-only; error swatches are preset-derived until any edit switches to custom (TWW · Ink errors). Component previews use the published brand package and the site's light/dark toggle.
 
  Start from
       
 * homages — shown for range, not affiliation.
 
  Tokens
 Primary updates live swatches. Accent, shape, density, and ground appear in the excerpt only. Error swatches follow the preset until you edit a knob — then they reset to TWW · Ink.
  color.primary   #26221A    color.accent   #9C7C14    rounded.md   2px    density   1.0×    ground     
 
   DESIGN.md excerpt illustrative

Examples

Properties

Slots & events

Tokens

States

Accessibility

SDUI