Components / Controls

RadioGroup

Picks one option from a short list, with every option visible. It is built on native radios, so forms, reset and required work without extra code. For a compact switcher use SegmentedControl instead.

Source Edit this page

Arrow keys select and wrap skipping disabled

When to use

A short list (about two to six) where seeing every choice helps the decision.
Settings that need a description per option, such as a digest frequency or a connection type.
A choice that is submitted with a form.

Use something else when:

there are many options: Select
the choice is a compact view or mode switcher: SegmentedControl
it is a single on/off setting: Switch

Usage

tsx

import { RadioGroup } from "@arshad-shah/cynosure";

<RadioGroup
  label="Digest"
  name="digest"
  defaultValue="weekly"
  description="How often we email you a summary."
  options={[
    { value: "daily", label: "Daily" },
    { value: "weekly", label: "Weekly", description: "Every Monday" },
    { value: "never", label: "Never", disabled: true },
  ]}
  onChange={setDigest}
/>

Controlled use

Pass value and onChange(value) to own the state. Without value, the group is uncontrolled and starts from defaultValue.

Controlled value

Layout and states

orientation: vertical (default) or horizontal.
error: shows a message under the group. description adds help text.
required and disabled: apply to the whole group. Set disabled on one option to disable just that choice.
labelHidden: hides the group label visually while it still names the group. Prefer a visible label.

Props

Every prop of RadioGroup
Prop	What it does	Type	Default
`label`Required	Names the group, shown above the options.	`ReactNode`
`options`Required	The choices: `{ value, label, description?, disabled? }`.	`RadioOption[]`
`labelHidden`	Visually hide the label (it still names the control). Prefer visible labels.	`boolean`
`description`	Help text shown below the options.	`ReactNode`
`error`	Error message shown below the options and announced.	`ReactNode`
`name`	Native group name (generated when omitted).	`string`
`value`	Controlled selected value.	`string`
`defaultValue`	Selected value at first, when uncontrolled.	`string`
`onChange`	Called with the option's value when it is chosen.	`((value: string) => void)`
`orientation`	Stack the options, or lay them in a row that wraps. Default "vertical".	`"horizontal" \| "vertical"`	`"vertical"`
`required`	The form will not submit until an option is chosen; also draws the required marker.	`boolean`
`disabled`	Disables every option.	`boolean`
`size`	Size of the radios and their text. Default "md".	`Size`	`"md"`
`tone`	Colour of the chosen radio. Default "accent".	`Tone`	`"accent"`
`className`	Added to the root element, for layout.	`string`
`style`	Layout only.	`CSSProperties`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Behaviour and accessibility, table 1
Input	Result
`TabTab`	Moves to the checked option (or the first one if none is checked)
Arrow keys	Move and select, wrapping at the ends and skipping disabled options
Click, tap	Selects the option

Native radios: the group shares one name (generated when omitted), so forms, form.reset() and required validation are native.
Group label: the label, description and error are linked to the group through Field.
Right-to-left: arrow keys follow the reading direction.

Theming

Tokens: --cy-radio-group-gap. The ring uses --cy-checkbox-border and its size --cy-checkbox-size (-sm, -lg), so radios line up with checkboxes. Each option is a Choice row: --cy-choice-gap is the space before its label.

createTheme({ components: { radioGroup: { gap: "12px" } } });

tone colours the selected option. className and style are for layout only.

Checkbox · Choice · Switch · SegmentedControl · Select

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

Controlled useLink to "Controlled use"

Layout and statesLink to "Layout and states"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

ThemingLink to "Theming"

RelatedLink to "Related"