form-field — wyrd.component.radio-group

RadioGroup

Single-choice form control group with option items, field text, 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/radio-group.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: RadioGroup  tag: wyrd-radio-group  package: wyrd.component.radio-group  title: Radio Group  summary: Single-choice form control group with option items, field text, 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 radio option items.    - name: is-disabled      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Prevents changing selection and exposes disabled group semantics.    - name: is-required      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Marks the group 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 group label and accessible-name source.    - name: description      required: false      cardinality: zero-or-one      accepts:        - text      summary: Help text associated with the radio group.    - 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 group with no invalid or disabled state.    - name: checked      source: property      summary: State when an option matching value or default-value is selected.    - name: focus-visible      source: platform      summary: Keyboard-visible focus state on a radio option.    - 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: Group label text.      slots:        - label    - name: group      summary: Native radio group container.    - name: option      summary: Option row label and control.    - name: control      summary: Native radio control.    - name: option-label      summary: Option label text.    - name: option-description      summary: Option description text.    - name: description      summary: Group description text.      slots:        - description    - name: error      summary: Group error text.      slots:        - error  tokens:    root:      gap: spacing.xs    label:      color: color.on-surface      text: typography.label-md    required-indicator:      color: color.error    group:      gap: spacing.sm    option:      gap: spacing.sm      padding-y: spacing.xs    control:      accent: color.primary      focus-ring: color.primary      disabled-opacity: opacity.disabled    option-label:      color: color.on-surface      text: typography.body-md    option-description:      color: color.on-surface-variant      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: radiogroup    name: Label slot provides the accessible name.    description: Description and error slots are programmatically associated with the group.    keyboard:      - Tab moves focus into and out of the group in document order.      - Arrow keys move selection between enabled radio options according to platform behavior.      - Space selects the focused enabled radio option.    semantics:      - The group exposes required, invalid, and disabled state where the platform supports it.      - Each option exposes checked and disabled state through native radio semantics.      - Error text is associated only when invalid.  behavior:    model: input    interactions:      - Selecting an enabled option emits value-change with that option value.      - Disabled groups 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      - 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:      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: checked    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      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

EmailPhoneMail

Choose how collaborators should reach you.

Usage

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

<WyrdRadioGroup 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';

WyrdRadioGroup(
  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: checked

Contact method

EmailPhoneMail

Usage

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

<WyrdRadioGroup 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';

WyrdRadioGroup(
  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

EmailPhoneMail

Select a contact method.

Usage

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

<WyrdRadioGroup isInvalid isRequired 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';

WyrdRadioGroup(
  isInvalid: true,
  isRequired: true,
  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 radio option items.
`is-disabled`	`boolean`	`false`	Prevents changing selection and exposes disabled group semantics.
`is-required`	`boolean`	`false`	Marks the group 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 group label and accessible-name source.
`description`	zero-or-one	`text`	Help text associated with the radio group.
`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`
`required-indicator.color`	`color.error`
`group.gap`	`spacing.sm`
`option.gap`	`spacing.sm`
`option.padding-y`	`spacing.xs`
`control.accent`	`color.primary`
`control.focus-ring`	`color.primary`
`control.disabled-opacity`	`opacity.disabled`
`option-label.color`	`color.on-surface`
`option-label.text`	`typography.body-md`
`option-description.color`	`color.on-surface-variant`
`option-description.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 group with no invalid or disabled state.
`checked`	property	State when an option matching value or default-value is selected.
`focus-visible`	platform	Keyboard-visible focus state on a radio option.
`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, 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