form-field — wyrd.component.checkbox-group

CheckboxGroup

Multi-choice form control group with option items, field text, and one canonical values-change event.

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

catalog/contracts/checkbox-group.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: CheckboxGroup  tag: wyrd-checkbox-group  package: wyrd.component.checkbox-group  title: Checkbox Group  summary: Multi-choice form control group with option items, field text, and one canonical values-change event.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: form-field  composition: multi-slot  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: values      type:        kind: array        item:          kind: string      required: false      default: []      controlled: true      serializable: true      summary: Controlled selected option values.    - name: default-values      type:        kind: array        item:          kind: string      required: false      default: []      serializable: true      summary: Initial uncontrolled selected option values.    - 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 checkbox 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 at least 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 checkbox group.    - name: error      required: false      cardinality: zero-or-one      accepts:        - text      summary: Validation error associated when is-invalid is true.  events:    - name: values-change      payload:        values:          kind: array          item:            kind: string        action:          kind: action-ref      bubbles: true      composed: true      cancelable: false      summary: Canonical values-change event carrying the full selected values array.  states:    - name: default      source: platform      summary: Enabled group with no invalid or disabled state.    - name: checked      source: property      summary: State when one or more options matching values or default-values are selected.    - name: focus-visible      source: platform      summary: Keyboard-visible focus state on a checkbox 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 checkbox group container.    - name: option      summary: Option row label and control.    - name: control      summary: Native checkbox 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:      size: spacing.md      background: color.surface      background-checked: color.primary      foreground-checked: color.on-primary      border-color: color.outline      border-color-focus: color.primary      border-color-disabled: color.disabled      border-width: 1px      radius: rounded.sm      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: group    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 checkbox options in document order.      - Space toggles the focused enabled checkbox option.    semantics:      - The group exposes required, invalid, and disabled state where the platform supports it.      - Each option exposes checked and disabled state through native checkbox semantics.      - Error text is associated only when invalid.  behavior:    model: input    interactions:      - Toggling an enabled option emits values-change with the full selected values array.      - Disabled groups and disabled options do not change values.      - Controlled values win over default-values.    hostEffects:      - Dispatch values-change event.      - Bind values to SDUI form state when present.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion  sdui:    status: serializable    serializableProperties:      - values      - default-values      - options      - is-disabled      - is-required      - is-invalid    serializableSlots:      - label      - description      - error    eventBindings:      - values-change    notes: Options serialize as ordered records; values-change serializes to a named binding/action channel.examples:  - name: empty    state: default    properties:      options:        - value: email          label: Email        - value: sms          label: SMS        - value: phone          label: Phone    slots:      label: Notification channels      description: Choose every channel collaborators may use.  - name: selected    state: checked    properties:      default-values:        - email        - sms      options:        - value: email          label: Email        - value: sms          label: SMS        - value: phone          label: Phone    slots:      label: Notification channels  - name: invalid    state: invalid    properties:      is-invalid: true      is-required: true      options:        - value: email          label: Email        - value: sms          label: SMS        - value: phone          label: Phone    slots:      label: Notification channels      error: Select at least one channel.

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

Notification channels

EmailSMSPhone

Choose every channel collaborators may use.

Usage

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

<WyrdCheckboxGroup options={[{"value":"email","label":"Email"},{"value":"sms","label":"SMS"},{"value":"phone","label":"Phone"}]} label="Notification channels" description="Choose every channel collaborators may use." />

// events: onValuesChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCheckboxGroup(
  options: [{"value":"email","label":"Email"},{"value":"sms","label":"SMS"},{"value":"phone","label":"Phone"}],
  label: Text('Notification channels'),
  description: Text('Choose every channel collaborators may use.'),
)

// events: onValuesChange

selected state: checked

Notification channels

EmailSMSPhone

Usage

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

<WyrdCheckboxGroup defaultValues={["email","sms"]} options={[{"value":"email","label":"Email"},{"value":"sms","label":"SMS"},{"value":"phone","label":"Phone"}]} label="Notification channels" />

// events: onValuesChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCheckboxGroup(
  defaultValues: ["email","sms"],
  options: [{"value":"email","label":"Email"},{"value":"sms","label":"SMS"},{"value":"phone","label":"Phone"}],
  label: Text('Notification channels'),
)

// events: onValuesChange

invalid state: invalid

Notification channels

EmailSMSPhone

Select at least one channel.

Usage

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

<WyrdCheckboxGroup isInvalid isRequired options={[{"value":"email","label":"Email"},{"value":"sms","label":"SMS"},{"value":"phone","label":"Phone"}]} label="Notification channels" error="Select at least one channel." />

// events: onValuesChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCheckboxGroup(
  isInvalid: true,
  isRequired: true,
  options: [{"value":"email","label":"Email"},{"value":"sms","label":"SMS"},{"value":"phone","label":"Phone"}],
  label: Text('Notification channels'),
  error: Text('Select at least one channel.'),
)

// events: onValuesChange

Properties

Name	Type	Default	Summary
`values`	`array`		Controlled selected option values.
`default-values`	`array`		Initial uncontrolled selected option values.
`options`	`array`		Ordered selectable checkbox option items.
`is-disabled`	`boolean`	`false`	Prevents changing selection and exposes disabled group semantics.
`is-required`	`boolean`	`false`	Marks the group as requiring at least 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 checkbox group.
`error`	zero-or-one	`text`	Validation error associated when is-invalid is true.

Event	Payload	Summary
`values-change`	`values, action`	Canonical values-change event carrying the full selected values array.

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.size`	`spacing.md`
`control.background`	`color.surface`
`control.background-checked`	`color.primary`
`control.foreground-checked`	`color.on-primary`
`control.border-color`	`color.outline`
`control.border-color-focus`	`color.primary`
`control.border-color-disabled`	`color.disabled`
`control.border-width`	`1px`
`control.radius`	`rounded.sm`
`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 one or more options matching values or default-values are selected.
`focus-visible`	platform	Keyboard-visible focus state on a checkbox 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; values-change serializes to a named binding/action channel.

Serializable	Members
Properties	`values, default-values, options, is-disabled, is-required, is-invalid`
Slots	`label, description, error`
Events	`values-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