form-field — wyrd.component.select

Select

Native single-choice select field with label, description, validation state, options, optional placeholder, and one canonical value-change event.

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

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

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: Select  tag: wyrd-select  package: wyrd.component.select  title: Select  summary: Native single-choice select field with label, description, validation state, options, optional placeholder, and one canonical value-change event.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: form-field  composition: multi-slot  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: value      type:        kind: string      required: false      controlled: true      serializable: true      summary: Controlled selected option value.    - 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            description:              kind: string            disabled:              kind: boolean      required: false      default: []      serializable: true      summary: Ordered selectable option items.    - name: placeholder      type:        kind: string      required: false      serializable: true      summary: Disabled placeholder option shown when no value is selected.    - name: is-disabled      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Prevents changing selection and exposes disabled semantics.    - 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.  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 select.    - 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.  states:    - name: default      source: platform      summary: Enabled field with no invalid or disabled state.    - name: selected      source: property      summary: State when an option matching value or default-value is selected.    - name: focus-visible      source: platform      summary: Keyboard-visible focus state.    - name: disabled      source: property      summary: Disabled state derived from is-disabled or option 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 container.      slots:        - label        - description        - error    - name: label      summary: Label text.      slots:        - label    - name: control      summary: Native select control.    - 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    control:      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    description:      color: color.on-surface-variant      text: typography.body-md    error:      color: color.error      text: typography.body-mdmessages: []obligations:  accessibility:    role: combobox    name: Label slot provides the accessible name.    description: Description and error slots are programmatically associated with the control.    keyboard:      - Native select follows platform selection keys.      - Tab moves focus into and out of the field in document order.    semantics:      - Required, invalid, and disabled states are exposed through platform semantics.      - Error text is associated only when invalid.      - Each option exposes selected and disabled state through native select semantics.  behavior:    model: input    interactions:      - Selecting an enabled option emits value-change with that option value.      - Disabled selects and disabled options do not change value.      - Controlled value wins over default-value.    hostEffects:      - Dispatch value-change event.      - Bind value to SDUI form state when present.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion  sdui:    status: serializable    serializableProperties:      - value      - default-value      - options      - placeholder      - is-disabled      - is-required      - is-invalid    serializableSlots:      - label      - description      - error    eventBindings:      - value-change    notes: Options serialize as ordered records; value-change serializes to a named binding/action channel.examples:  - name: empty    state: default    properties:      placeholder: Choose a contact method      options:        - value: email          label: Email        - value: phone          label: Phone        - value: mail          label: Mail    slots:      label: Contact method      description: Choose how collaborators should reach you.  - name: selected    state: selected    properties:      default-value: email      options:        - value: email          label: Email        - value: phone          label: Phone        - value: mail          label: Mail    slots:      label: Contact method  - name: invalid    state: invalid    properties:      is-invalid: true      is-required: true      placeholder: Choose a contact method      options:        - value: email          label: Email        - value: phone          label: Phone        - value: mail          label: Mail    slots:      label: Contact method      error: Select a contact method.

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: default

Contact method

Choose how collaborators should reach you.

Usage

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

<WyrdSelect placeholder="Choose a contact method" options={[{"value":"email","label":"Email"},{"value":"phone","label":"Phone"},{"value":"mail","label":"Mail"}]} label="Contact method" description="Choose how collaborators should reach you." />

// events: onValueChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdSelect(
  placeholder: 'Choose a contact method',
  options: [{"value":"email","label":"Email"},{"value":"phone","label":"Phone"},{"value":"mail","label":"Mail"}],
  label: Text('Contact method'),
  description: Text('Choose how collaborators should reach you.'),
)

// events: onChanged

selected state: selected

Contact method

Usage

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

<WyrdSelect defaultValue="email" options={[{"value":"email","label":"Email"},{"value":"phone","label":"Phone"},{"value":"mail","label":"Mail"}]} label="Contact method" />

// events: onValueChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdSelect(
  initialValue: 'email',
  options: [{"value":"email","label":"Email"},{"value":"phone","label":"Phone"},{"value":"mail","label":"Mail"}],
  label: Text('Contact method'),
)

// events: onChanged

invalid state: invalid

Contact method

Select a contact method.

Usage

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

<WyrdSelect isInvalid isRequired placeholder="Choose a contact method" options={[{"value":"email","label":"Email"},{"value":"phone","label":"Phone"},{"value":"mail","label":"Mail"}]} label="Contact method" error="Select a contact method." />

// events: onValueChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdSelect(
  isInvalid: true,
  isRequired: true,
  placeholder: 'Choose a contact method',
  options: [{"value":"email","label":"Email"},{"value":"phone","label":"Phone"},{"value":"mail","label":"Mail"}],
  label: Text('Contact method'),
  error: Text('Select a contact method.'),
)

// events: onChanged

Properties

Name	Type	Default	Summary
`value`	`string`	`undefined`	Controlled selected option value.
`default-value`	`string`	`undefined`	Initial uncontrolled selected option value.
`options`	`array`		Ordered selectable option items.
`placeholder`	`string`	`undefined`	Disabled placeholder option shown when no value is selected.
`is-disabled`	`boolean`	`false`	Prevents changing selection and exposes disabled semantics.
`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.

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 select.
`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.

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`
`control.background`	`color.surface`
`control.foreground`	`color.on-surface`
`control.placeholder`	`color.on-surface-variant`
`control.border-color`	`color.outline`
`control.border-color-focus`	`color.primary`
`control.border-color-invalid`	`color.error`
`control.border-width`	`1px`
`control.radius`	`rounded.sm`
`control.padding-x`	`spacing.md`
`control.padding-y`	`spacing.sm`
`control.text`	`typography.body-md`
`description.color`	`color.on-surface-variant`
`description.text`	`typography.body-md`
`error.color`	`color.error`
`error.text`	`typography.body-md`

States

State	Source	Summary
`default`	platform	Enabled field with no invalid or disabled state.
`selected`	property	State when an option matching value or default-value is selected.
`focus-visible`	platform	Keyboard-visible focus state.
`disabled`	property	Disabled state derived from is-disabled or option disabled.
`invalid`	property	Invalid state derived from is-invalid.
`required`	property	Required state derived from is-required.

SDUI

Status: serializable. Options serialize as ordered records; value-change serializes to a named binding/action channel.

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

  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