Skip to content
Cloaked Design SystemPrimitives

Radio

A controlled round single-select control that selects an option without deselecting the current option on a second press.

Implementation preview
COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

6 stories
SELECTED EXAMPLE

Playground

Open controls
Playground selectedOpen canvas
Example sourcepackages/design-system/src/components/primitives/Radio/Radio.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

A controlled round single-select control that selects an option without deselecting the current option on a second press.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Radio } from '@cloakedinc/design-system';
RadioRadioProps

packages/design-system/src/components/primitives/Radio/Radio.tsx:32

PropTypePresenceNotes
selectedbooleanRequiredCurrent state, exposed as `aria-checked`.
onSelect(() => void) | undefinedOptionalCalled when an unselected radio is pressed. A selected radio is a no-op.
disabledboolean | undefinedOptionalBlocks the press and dims the chip.
ariaLabelstring | undefinedOptionalAccessible label when no visible label is associated with the radio.
classNamestring | undefinedOptional
hapticHapticFeedback | undefinedOptionalHaptic feedback for selection. Defaults to `true` (`selection`).Source default: true
testIdstring | undefinedOptionalSelector on the `role="radio"` button; the chip inside is decorative and carries none.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

The bare single-select chip (role="radio"). Select-only — pressing an unselected radio fires onSelect; pressing the selected one is a no-op, because exclusive selection is owned by the parent.

When to use

You rarely reach for Radio directly — for a labeled set of mutually exclusive options use RadioGroup, which composes this chip with copy, layout, and group semantics. Drop to a bare Radio only when you are building a custom row layout the group can't express. Compared with its siblings:

  • Selecting more than one item from a set? Use Checkbox.
  • A compact 2–4 option switch inline (a view or filter toggle)? Use SegmentedControl.
  • A long list of choices where space is tight? Use Select.

Component specification

$schema../../../specs/component-spec.schema.json
Parts
Id
control
Label
Control
Description
Owns radio semantics, focus treatment, interaction, and disabled behavior.
Id
selection-chip
Label
Selection chip
Description
Uses the shared internal selection visual without exposing it as a standalone public component.
Id
dot
Label
Selection dot
Description
Appears only while this option is selected.
Allowed Design Choices
Variants
Base
Label
Base
Description
Radio has one round visual treatment.
Sizes
Variants
Id
base
Label
Base
Description
A round select-only control for one option in an exclusive set.
Platforms
  • ios
  • android
  • web
SizesNone specified
Measurements
Id
control-diameter
Label
Control diameter
Kind
exact
Token
--cds-size-32
Value
32
Unit
px
Applies To
  • control
  • selection-chip
Id
selection-dot-diameter
Label
Selection dot diameter
Kind
exact
Token
--cds-size-8
Value
8
Unit
px
Applies To
  • dot
  • selected
Layout
Alignment
The selection dot is centered inside the circular chip.
Flow
The bare control is inline; a parent group composes visible labels and descriptions beside it.
Notes
  • Use RadioGroup when presenting a complete labeled set of mutually exclusive options.
Typography And Color
Typography
Label
Composed label
Description
A visible option label beside the bare control uses the body ramp.
Token
--cds-type-body-size
Colors
Label
Unselected chip
Description
Uses the neutral selection-off container role.
Token
--cds-selection-off-container
Label
Selected chip
Description
Uses the theme-aware bold fill.
Token
--cds-bg-bold
Label
Selection dot
Description
Maintains contrast on the selected fill.
Token
--cds-text-on-bold
Label
Focus ring
Description
Uses the brand accent for keyboard focus.
Token
--cds-brand
States
Id
unselected
Label
Unselected
Description
Shows the neutral empty chip and reports aria-checked false.
Id
selected
Label
Selected
Description
Shows the bold chip with a centered dot and reports aria-checked true.
Id
disabled-unselected
Label
Disabled unselected
Description
Keeps the unselected value visible while blocking selection.
Id
disabled-selected
Label
Disabled selected
Description
Keeps the selected value visible while blocking selection.
Id
keyboard-focus
Label
Keyboard focus
Description
Shows the brand focus ring around the circular control.
Behavior
Label
Select only
Description
Invoke selection once for an enabled unselected option; pressing the selected option is a no-op.
Label
Parent ownership
Description
Let the parent group enforce exclusivity and update which option is selected.
Label
Disabled
Description
Do not invoke selection or haptic feedback while disabled.
Accessibility
Label
Radio semantics
Description
Expose radio role, the controlled selected value, and native disabled behavior.
Label
Group semantics
Description
Place related radio controls in a named radiogroup and associate each with visible option text.
Content Adaptation
Label
Option copy
Description
Keep the circular control fixed while visible labels and descriptions wrap in the parent layout.
Motion Haptics
Motion
Label
Selection change
Description
Change the chip fill and dot visibility without layout movement.
Haptics
Label
Selection feedback
Description
Request the selection haptic after an enabled new selection unless feedback is disabled.
Platform DifferencesNone specified
Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1