RadioGroup

ReactProps

Github Storybook Markdown Copy for LLM

A RadioGroup is a set of related options where only one can be selected at a time. A Radio button must be a child of a RadioGroup.

Import

import { Radio, RadioGroup } from "@cfa/react-core";

Live Editor

Guidelines

When to use

• RadioGroup is for a single choice from options that stay visible.

Do

• Use RadioGroup for fewer than three options, or when all short options should stay visible at once.
• Always provide a visible group label in sentence case. Associate it with fieldset and legend or aria-labelledby.
• Include optional description text when people need context or constraints on the group.
• When the group is required, validate on submit. Show a group-level error if nothing is selected.
• Show the description and error message at the same time. Do not hide description when the group is invalid.

Avoid

• Using RadioGroup for multiple selection. Use CheckboxGroup.
• Using RadioGroup for on/off options. Use Switch.
• Using RadioGroup for long searchable lists. Use Select or Combobox.
• Nesting groups inside groups. Flatten the structure or use grouping inside Select.

Examples

Default Value

The defaultValue prop can be used to set the default selected value of the radio group. This is useful when you want to pre-select a specific option.

Description

The description prop on <RadioGroup /> can be used to provide additional context for the entire group.

Radio Description

The description prop on an individual <Radio /> adds helper text for that option. Use it when each choice needs its own supporting detail.

Disabled State

To disable the entire group, pass the isDisabled prop to the parent <RadioGroup />. You can also disable an individual <Radio /> by passing the isDisabled prop to the child <Radio />.

Readonly

To set the radio group to read-only, pass the isReadOnly prop to the parent <RadioGroup />. Use this when you want to prevent the user from changing the selection but still want to display the selected value and be available to screen readers.

Controlled

The value prop can be used to control the selected value of the <RadioGroup />. This is useful when you want to manage the selected value externally.

Invalid

To indicate an error, pass the isInvalid prop to the parent <RadioGroup />. You can also pass the errorMessage prop to provide additional context.

Native HTML Forms

The <RadioGroup /> component can be used in a native HTML form. The name prop is required for the <RadioGroup /> to work properly in a form.