# RadioGroup

A controlled single-choice field that stacks labelled options as divider-separated selection rows.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx

## Guidance

{
  "summary": "A controlled single-choice field that stacks labelled options as divider-separated selection rows.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "Manages a set of radios as one mutually-exclusive field — one `value`, labelled `options`, and\ngroup semantics (`role=\"radiogroup\"`). This is the control you reach for, not the bare `Radio`.\n\nOptions render as divider-separated `List.Item.Selection` rows with the control at the trailing\nedge, so a group reads as part of the surface it sits on. Rows are 80px with a `description` and\n64px without."
    },
    {
      "heading": "When to use",
      "body": "Use `RadioGroup` for a single choice where every option should stay visible so seeing them all\naids the decision — best at 2–5 options. Pair it with `Field` for the label; only pass the\nstandalone aria props when used outside `Field`. Choosing between the neighbours:\n\n-   The list is **long or space is tight**? Use `Select` — don't stack a dozen radios.\n-   You need a **compact inline** 2–4 option switch (view/filter) rather than a labelled form field?\n    Use `SegmentedControl`.\n-   The user may pick **more than one** option? Use `Checkbox`."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "value",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Value of the selected option; a value matching no option leaves the group unselected.",
      "source": {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 23
      }
    },
    {
      "name": "options",
      "type": "RadioOption[]",
      "declared_type": "RadioOption[]",
      "required": true,
      "description": "Options in display order. Dividers sit between rows, not after the last one.",
      "source": {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 25
      }
    },
    {
      "name": "onChange",
      "type": "((value: string) => void) | undefined",
      "declared_type": "(value: string) => void",
      "required": false,
      "description": "Called with the next value. Pressing the already-selected option does not call it.",
      "source": {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 27
      }
    },
    {
      "name": "disabled",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Prevents interaction with every option when true.",
      "source": {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 29
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "required",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Marks the group as required for assistive technology.",
      "source": {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 31
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Accessible name when no visible label is associated with the group.",
      "source": {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 33
      }
    },
    {
      "name": "haptic",
      "type": "HapticFeedback | undefined",
      "declared_type": "HapticFeedback",
      "required": false,
      "description": "Haptic feedback for value changes. Defaults to `true` (`selection`).",
      "source": {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 35
      },
      "values": [
        "error",
        "heavy",
        "light",
        "medium",
        "selection",
        "success",
        "warning",
        false,
        true
      ],
      "values_complete": true,
      "default": "true",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 36
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Test id for the group; each row derives `${testId}-${option.value}`.",
      "source": {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 38
      }
    },
    {
      "name": "id",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "DOM id the control renders, which the Field's label points at.",
      "source": {
        "path": "packages/design-system/src/hooks/FieldContext.ts",
        "line": 22
      }
    },
    {
      "name": "invalid",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Paints the invalid treatment and announces the control as invalid. A Field supplies\nthis from its own `error`; set it directly only for a control with no Field around it.",
      "source": {
        "path": "packages/design-system/src/hooks/FieldContext.ts",
        "line": 31
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "ariaDescribedBy",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Ids of the helper or error copy describing the control, supplied by a parent Field.",
      "source": {
        "path": "packages/design-system/src/hooks/FieldContext.ts",
        "line": 33
      }
    },
    {
      "name": "ariaLabelledBy",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Id of the visible label naming the control, supplied by a parent Field.",
      "source": {
        "path": "packages/design-system/src/hooks/FieldContext.ts",
        "line": 35
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "RadioGroup",
    "public_path": "RadioGroup",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "RadioGroup",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
          "line": 45
        },
        "props_type": "RadioGroupProps",
        "props": [
          {
            "name": "value",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Value of the selected option; a value matching no option leaves the group unselected.",
            "source": {
              "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
              "line": 23
            }
          },
          {
            "name": "options",
            "type": "RadioOption[]",
            "declared_type": "RadioOption[]",
            "required": true,
            "description": "Options in display order. Dividers sit between rows, not after the last one.",
            "source": {
              "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
              "line": 25
            }
          },
          {
            "name": "onChange",
            "type": "((value: string) => void) | undefined",
            "declared_type": "(value: string) => void",
            "required": false,
            "description": "Called with the next value. Pressing the already-selected option does not call it.",
            "source": {
              "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
              "line": 27
            }
          },
          {
            "name": "disabled",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Prevents interaction with every option when true.",
            "source": {
              "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
              "line": 29
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "required",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Marks the group as required for assistive technology.",
            "source": {
              "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
              "line": 31
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Accessible name when no visible label is associated with the group.",
            "source": {
              "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
              "line": 33
            }
          },
          {
            "name": "haptic",
            "type": "HapticFeedback | undefined",
            "declared_type": "HapticFeedback",
            "required": false,
            "description": "Haptic feedback for value changes. Defaults to `true` (`selection`).",
            "source": {
              "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
              "line": 35
            },
            "values": [
              "error",
              "heavy",
              "light",
              "medium",
              "selection",
              "success",
              "warning",
              false,
              true
            ],
            "values_complete": true,
            "default": "true",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
              "line": 36
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Test id for the group; each row derives `${testId}-${option.value}`.",
            "source": {
              "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
              "line": 38
            }
          },
          {
            "name": "id",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "DOM id the control renders, which the Field's label points at.",
            "source": {
              "path": "packages/design-system/src/hooks/FieldContext.ts",
              "line": 22
            }
          },
          {
            "name": "invalid",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Paints the invalid treatment and announces the control as invalid. A Field supplies\nthis from its own `error`; set it directly only for a control with no Field around it.",
            "source": {
              "path": "packages/design-system/src/hooks/FieldContext.ts",
              "line": 31
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "ariaDescribedBy",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Ids of the helper or error copy describing the control, supplied by a parent Field.",
            "source": {
              "path": "packages/design-system/src/hooks/FieldContext.ts",
              "line": 33
            }
          },
          {
            "name": "ariaLabelledBy",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Id of the visible label naming the control, supplied by a parent Field.",
            "source": {
              "path": "packages/design-system/src/hooks/FieldContext.ts",
              "line": 35
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 8,
        "name": "RadioOption",
        "code": "export interface RadioOption {\n    value: string;\n    label: string;\n    /** Supporting copy shown beneath the label. */\n    description?: string;\n    /** Prevents this option from being selected. */\n    disabled?: boolean;\n}"
      },
      {
        "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx",
        "line": 21,
        "name": "RadioGroupProps",
        "code": "export interface RadioGroupProps extends FieldControlProps {\n    /** Value of the selected option; a value matching no option leaves the group unselected. */\n    value: string;\n    /** Options in display order. Dividers sit between rows, not after the last one. */\n    options: RadioOption[];\n    /** Called with the next value. Pressing the already-selected option does not call it. */\n    onChange?: (value: string) => void;\n    /** Prevents interaction with every option when true. */\n    disabled?: boolean;\n    /** Marks the group as required for assistive technology. */\n    required?: boolean;\n    /** Accessible name when no visible label is associated with the group. */\n    ariaLabel?: string;\n    /** Haptic feedback for value changes. Defaults to `true` (`selection`). */\n    haptic?: HapticFeedback;\n    className?: string;\n    /** Test id for the group; each row derives `${testId}-${option.value}`. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/hooks/FieldContext.ts",
        "line": 20,
        "name": "FieldControlProps",
        "code": "export interface FieldControlProps {\n    /** DOM id the control renders, which the Field's label points at. */\n    id?: string;\n    /** Blocks interaction and dims the control. */\n    disabled?: boolean;\n    /** Marks the control required for native form semantics. */\n    required?: boolean;\n    /**\n     * Paints the invalid treatment and announces the control as invalid. A Field supplies\n     * this from its own `error`; set it directly only for a control with no Field around it.\n     */\n    invalid?: boolean;\n    /** Ids of the helper or error copy describing the control, supplied by a parent Field. */\n    ariaDescribedBy?: string;\n    /** Id of the visible label naming the control, supplied by a parent Field. */\n    ariaLabelledBy?: string;\n}"
      },
      {
        "path": "packages/design-system/src/tokens/CdsHaptic.ts",
        "line": 6,
        "name": "HapticFeedback",
        "code": "export type HapticFeedback = boolean | HapticType;"
      },
      {
        "path": "packages/design-system/src/tokens/HapticType.ts",
        "line": 2,
        "name": "HapticType",
        "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "RadioGroup",
      "status": "preview",
      "version": "3.0.0",
      "summary": "A controlled single-choice field that stacks labelled options as divider-separated selection rows."
    },
    "parts": [
      {
        "id": "group",
        "label": "Group",
        "description": "Owns the accessible radio-group name, validation, and required state."
      },
      {
        "id": "option",
        "label": "Option row",
        "description": "Pressable full-width row carrying one option's copy and its selection control."
      },
      {
        "id": "label",
        "label": "Option label",
        "description": "Names the option and provides the row's accessible name."
      },
      {
        "id": "description",
        "label": "Option description",
        "description": "Optional supporting copy beneath the option label."
      },
      {
        "id": "indicator",
        "label": "Selection indicator",
        "description": "Trailing control showing unselected or selected-dot state without duplicating semantics."
      },
      {
        "id": "divider",
        "label": "Row divider",
        "description": "Hairline separating adjacent options; absent after the last option."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "row": {
          "label": "Row",
          "description": "Each option is one full-width selection row on the list surface."
        }
      },
      "sizes": {}
    },
    "variants": [
      {
        "id": "row",
        "label": "Row",
        "description": "Divider-separated single-choice rows with a trailing selection control.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "row-min-height",
        "label": "Option row height",
        "kind": "at-least",
        "token": "--cds-size-80",
        "value": 80,
        "unit": "px",
        "appliesTo": [
          "option",
          "description"
        ]
      },
      {
        "id": "compact-row-min-height",
        "label": "Option row height without description",
        "kind": "at-least",
        "token": "--cds-size-64",
        "value": 64,
        "unit": "px",
        "appliesTo": [
          "option"
        ]
      },
      {
        "id": "row-inset",
        "label": "Option row inset",
        "kind": "exact",
        "token": "--cds-space-20",
        "value": 20,
        "unit": "px",
        "appliesTo": [
          "option"
        ]
      },
      {
        "id": "copy-to-control-gap",
        "label": "Copy-to-control gap",
        "kind": "exact",
        "token": "--cds-space-24",
        "value": 24,
        "unit": "px",
        "appliesTo": [
          "option",
          "indicator"
        ]
      },
      {
        "id": "indicator-diameter",
        "label": "Selection indicator diameter",
        "kind": "exact",
        "token": "--cds-size-32",
        "value": 32,
        "unit": "px",
        "appliesTo": [
          "indicator"
        ]
      }
    ],
    "layout": {
      "alignment": "Copy fills the leading column and the selection control pins to the trailing edge, both vertically centered.",
      "flow": "Options stack full-width with a hairline between adjacent rows and none after the last.",
      "notes": [
        "Keep option rows flush to the surface; do not wrap them in per-option cards or radii.",
        "Use Select when the choice list is too long to keep visible."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Option label",
          "description": "Use body text for the option name.",
          "token": "--cds-type-body-size"
        },
        {
          "label": "Option description",
          "description": "Use body-small secondary text for supporting copy.",
          "token": "--cds-type-body-small-size"
        }
      ],
      "colors": [
        {
          "label": "Row surface",
          "description": "Use the list row surface for every option, selected or not.",
          "token": "--cds-bg-surface"
        },
        {
          "label": "Row divider",
          "description": "Use the shared divider hairline between adjacent options.",
          "token": "--cds-divider"
        },
        {
          "label": "Selected indicator",
          "description": "Use the theme-aware bold fill for the chosen option's control.",
          "token": "--cds-bg-bold"
        },
        {
          "label": "Option copy",
          "description": "Use primary and secondary text emphasis by copy hierarchy.",
          "token": "--cds-text-primary"
        }
      ]
    },
    "states": [
      {
        "id": "unselected",
        "label": "Unselected",
        "description": "Shows the neutral empty indicator with no row treatment change."
      },
      {
        "id": "selected",
        "label": "Selected",
        "description": "Fills the trailing indicator and shows the dot; the row itself is unchanged."
      },
      {
        "id": "option-disabled",
        "label": "Option disabled",
        "description": "Dims one row and blocks its press while leaving the rest selectable."
      },
      {
        "id": "group-disabled",
        "label": "Group disabled",
        "description": "Dims and blocks every option in the group."
      },
      {
        "id": "invalid",
        "label": "Invalid",
        "description": "Exposes group-level invalid and described-by relationships supplied by Field."
      }
    ],
    "behavior": [
      {
        "label": "Single selection",
        "description": "Emit a new option value only when it differs from the controlled value."
      },
      {
        "label": "Disabled options",
        "description": "Never emit changes for a disabled option or disabled group."
      },
      {
        "label": "Row press target",
        "description": "Treat the whole row as the press target, not just the selection control."
      }
    ],
    "accessibility": [
      {
        "label": "Group name",
        "description": "Associate a visible Field label or provide an accessible group name."
      },
      {
        "label": "Option semantics",
        "description": "Expose each option as a radio whose accessible name is its label and whose description is announced when present."
      },
      {
        "label": "Validation",
        "description": "Expose required, invalid, and described-by state on the group without duplicating it on decorative indicators."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Option count",
        "description": "Keep groups to a short visible set; use Select for long lists."
      },
      {
        "label": "Descriptions",
        "description": "Use concise descriptions to clarify consequences, not repeat option labels; omitting them tightens the row."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Selection state",
          "description": "Change only the indicator fill and dot; option content must not move."
        }
      ],
      "haptics": [
        {
          "label": "Selection feedback",
          "description": "Request the selection haptic after a new enabled value is chosen, and none when the current value is re-pressed."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "web"
        ],
        "description": "Web renders each option as a button with radio semantics rather than a native radio input; native platforms map the same option content to their radio accessibility controls.",
        "rationale": "The row is the press target on every platform, and the shared row treatment matters more here than native input chrome the design hides anyway."
      }
    ]
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-size-80",
      "light": "80px",
      "dark": "80px"
    },
    {
      "name": "--cds-size-64",
      "light": "64px",
      "dark": "64px"
    },
    {
      "name": "--cds-space-20",
      "light": "20px",
      "dark": "20px"
    },
    {
      "name": "--cds-space-24",
      "light": "24px",
      "dark": "24px"
    },
    {
      "name": "--cds-size-32",
      "light": "32px",
      "dark": "32px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-bg-surface",
      "light": "#ffffff",
      "dark": "#1b1b18"
    },
    {
      "name": "--cds-divider",
      "light": "#e0ddd6",
      "dark": "#ffffff1a"
    },
    {
      "name": "--cds-bg-bold",
      "light": "#0b0b0a",
      "dark": "#ffffff"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx

- [With Field](/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--with-field&viewMode=story) | export: WithField | source: packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx

- [Label Only](/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--label-only&viewMode=story) | export: LabelOnly | source: packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx

- [With Disabled Option](/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--with-disabled-option&viewMode=story) | export: WithDisabledOption | source: packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx

- [Disabled](/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--disabled&viewMode=story) | export: Disabled | source: packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx

- [State Matrix](/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--state-matrix&viewMode=story) | export: StateMatrix | source: packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.