Radio Button | Calcite Design System

Radio Buttons are circular actions used to make single-choice decisions.

Overview

Radio Buttons are designed to take up small interface area, which can fit within a multitude of workflows. Radio Buttons always have one selected item, denoted with a filled Brand color. You can use Radio Button Group as a convenient utility for layout and group configurations.

For "yes" and "no" interactions, multiple selections, and interactions where a choice is optional, please consider Checkbox. The key difference between a checkbox and radio is that radios must always have something active, whereas a checkbox is optional.

For "on" and "off" or boolean interactions, please consider Switch.

Sample

Usage

Various interactions where a single choice needs to be made
Forms

Component comparison

Radio Button, Checkbox, and Switch are similar, but each component is designed for a different purpose.

Radio Button

This component

Best for choosing a single option. Often used in a Radio Button Group with related options.

Allows only one option per Radio Button Group to be selected. Selection cannot be cleared.

Checkbox

Alternative

Best for "yes" or "no" decisions.

Allows a choice to be selected or left unselected.

Switch

Alternative

Best for toggling a setting "on" or "off".

Allows only one option to be selected.

Accessibility

Form controls such as Radio Button should specify their labelText property or be accompanied by a Label component to provide context to assistive technologies. For additional information, refer to the forms and labels accessibility guidance.

When Radio Buttons are presented with the same name property value, or contained in a Radio Button Group:

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

Writing and copy

Do prefer brevity in Radio Buttons.

Avoid tying Radio Button choices to long sentences or paragraphs.

Keep labels for Radio Buttons simple and succinct
Do not use contractions (you're, aren't, can't, haven't) for Radio Button labels in order to reduce confusion
Avoid writing Radio Button text as questions.

API reference

Properties

Property	Attribute	Description	Type	Default
checked	checked	When `true`, the component is checked.	`boolean`	`false`
disabled	disabled	When `true`, interaction is prevented and the component is displayed with lower opacity.	`boolean`	`false`
form	form	Specifies the `id` of the component's associated form. When not set, the component is associated with its ancestor form element, if one exists.	`string`
labelText	label-text	Specifies the component's label text.	`string`
name	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 selected from the `calcite-radio-button-group` in order for the form to submit.	`boolean`	`false`
scale	scale	Specifies the size of the component inherited from the `calcite-radio-button-group`.	`Scale`	`"m"`
status	status	Specifies the status of the input field, which determines message and icons.	`Status`	`"idle"`
valuerequired	value	The component's value.	`any`

Events

Name	Description	Behavior
calciteRadioButtonChange	Fires only when the radio button is checked. This behavior is identical to the native HTML input element. Since this event does not fire when the radio button is unchecked, it's not recommended to attach a listener for this event directly on the element, but instead either attach it to a node that contains all of the radio buttons in the group or use the `calciteRadioButtonGroupChange` event if using this with `calcite-radio-button-group`.	bubblescomposed

Styles

Name	Description
--calcite-radio-button-background-color	Specifies the component's background color.
--calcite-radio-button-border-color	Specifies the component's border color.
--calcite-radio-button-corner-radius	Specifies the component's corner radius.
--calcite-radio-button-size	Specifies the component's size.

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component.	`setFocus(options?: FocusOptions): Promise<void>`
setValidity	Sets the component's validity state.	`setValidity(validity: ValidityStateFlags, validationMessage?: string): Promise<void>`