Radio Button Group | Calcite Design System

Radio Button Group allows you to switch between horizontal and vertical layouts of Radio Buttons.

Overview

Built of Radio Buttons, you can control the group's scale, layout, and state in a single wrapper.

Sample

Usage

Groups of Radio Buttons
Easy switching between vertical and horizontal layouts for responsive design

Component comparison

Radio Button Group, Segmented Control, and Select all support single selection, but each has a different layout and user experience.

Radio Button Group

This component

Best for choosing one option from a group of two or more related options.

Each option is displayed.

Segmented Control

Alternative

Best for choosing one option from a group of two or more related options. Preferred for visual emphasis, custom styling, or icon support.

Each option is displayed.

Select

Alternative

Best for choosing one option from a group of three or more related options. Preferred when preserving layout space is more important than showing all options at once.

The selected option is always displayed. All options are visible when the component's menu is open.

Best practices

Radio Button Group with a small subset of six Radio Buttons comprised of tree types with the Maple value checked.

Do use Radio Button Groups for a small number of options.

Radio Button Group with a large subset of 27 Radio Buttons comprised of tree types with the Banyan value checked.

Avoid using Radio Button Groups for a large number of options. Consider Combobox with a selection-mode of "single" or "single-persist" instead.

Accessibility

Key	Function
`Arrow left`	Moves focus and selection to previous `calcite-radio-button`. If the current focus and selection is the first `calcite-radio-button`, the focus and selection will cycle to the last `calcite-radio-button`.
`Arrow right`	Moves focus and selection to next `calcite-radio-button`. If the current focus and selection is the last `calcite-radio-button`, the focus and selection will cycle to the first `calcite-radio-button`.
`Arrow down`	Moves focus and selection to previous `calcite-radio-button`. If the current focus and selection is the first `calcite-radio-button`, the focus and selection will cycle to the last `calcite-radio-button`.
`Arrow up`	Moves focus and selection to next `calcite-radio-button`. If the current focus and selection is the last `calcite-radio-button`, the focus and selection will cycle to the first `calcite-radio-button`.
`Tab`	Moves focus in and out of component.
`Tab` and `Shift`	Moves focus in and out of component.

Writing and copy

Keep Radio Button tone and length consistent within groups
Avoid forming questions with Radio Button text

API reference

Properties

Property	Attribute	Description	Type	Default
disabled	disabled	When `true`, interaction is prevented and the component is displayed with lower opacity.	`boolean`	`false`
labelText	label-text	Specifies the component's label text.	`string`
layout	layout	Specifies the layout of the component.	`Extract<"horizontal" \| "vertical", Layout>`	`"horizontal"`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
namerequired	name	Specifies the name of the component. Required to pass the component's `value` on form submission.	`string`
required	required	When `true` and the component resides in a form, the component must have a value in order for the form to submit.	`boolean`	`false`
scale	scale	Specifies the size of the component.	`Scale`	`"m"`
selectedItemread-only		Specifies the component's selected item.	`RadioButton`
status	status	Specifies the status of the validation message.	`Status`	`"idle"`
validationIcon	validation-icon	Specifies the validation icon to display under the component.	`IconName \| boolean`
validationMessage	validation-message	Specifies the validation message to display under the component.	`string`

Slots

Name	Description
default (unnamed)	A slot for adding `calcite-radio-button`s.
label-content	A slot for rendering content next to the component's `labelText`.

Styles

Name	Description
--calcite-radio-button-group-gap	Specifies the space between slotted components in the component.
--calcite-radio-button-input-message-spacing	Specifies the margin spacing at the top of the `calcite-input-message`.

Events

Name	Description	Behavior
calciteRadioButtonGroupChange	Fires when the component has changed.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the fist focusable `calcite-radio-button` element in the component.	`setFocus(options?: FocusOptions): Promise<void>`