Radio button
Radio buttons represent a list of mutually exclusive options.
Examples
Usage
Do
- Use when only one option can be selected
- Use when it’s important to display all of the options at once, clearly
- Keep the number of options to a minimum. If there are too many options, use a dropdown instead
- Align options vertically, for ease of reading
- Align options horizontally if needed, using existing spacing variables
- Always include a label
- Require that an option is always selected
- Make sure labels follow the same grammatical structure so it’s easier to understand the difference between them
- Include the option of “None” or “Doesn’t apply” if none of the options is accurate
Don’t
- Use if there are more than 7 options
- Use if there is a recommend option you want to emphasize over the others — use a dropdown instead
- Use if there are only two mutually exclusive options, consider using a single checkbox or a toggle instead (for example, use a single checkbox for “I agree” instead of two radio buttons for “I agree” and “I don’t agree”)
Anatomy
- (1) Radio button
- (2) Radio button label
- (3) Radio button selected
- (4) Disabled radio button
- (5) Disabled radio button selected
- (6) Multi-line label
Focus states
- (1) Focused radio button without label
- (2) Focused radio button with label
- (3) Focused radio button with multi-line label
Space and sizing
- (1) Default radio button and label
- (2) Focus area / hit target
- (3) Spacing between multiple radio buttons (8 px)
Related
APIs
IRadioButtonGroup
focus
(): void
Sets focus to the RadioButtonGroup.
RadioButtonGroupDirection
Horizontal1
number
Vertical2
number
IRadioButtonGroupProps
ariaErrorMessageId
string
Sets "aria-errormessage" attribute - the id of the element that provides error message.
ariaInvalidfalse
boolean
Sets "aria-invalid" attribute, if the error message is displayed, should be set to true.
className
string
Optional class name to add to the radio button group element.
defaultButtonId
string
The id of the button that should be focused by default.
directionRadioButtonGroupDirection.Vertical
Specifies the direction that the radio button children are layed out.
excludeFocusZone
boolean
Set to true if you don't want the radio button group's focus managed by a FocusZone.
groupClassName
string
Optional class name to add to the radio button group children container.
id
string
Optional id of the checkbox group element.
onSelect
(buttonId: string) => void
Callback called when a new button is selected.
selectedButtonId
IReadonlyObservableValue<string> | string
The id of the currently selected radio button.
text
string
Text to display above the radio group.
IRadioButtonProps
ariaDescribedBy
string
Id of another element which describes this one for screen reader users.
ariaLabelledBy
string
Id of another element which labels this one for screen reader users. Only use if custom rendering the label
with children. Otherwise, this will automatically get set to the id of the text serving as the label.
className
string
Optional class name to add to the radio button element.
disabled
boolean
If true, the button cannot be interacted with.
excludeFocusZone
boolean
Set to true if you don't want the radio button's focus managed by a FocusZone.
excludeTabStop
boolean
Set to true to omit setting the tab index.
idrequired
string
id of the radio button.
roleradio
string
Optional aria role.
text
string
Text to display next to the radio button.
For custom rendering the label of the radio button (to support two lines of text, etc.), pass
children to the <RadioButton> and use the bolt-radio-button-label className. Make sure to set
the ariaLabelledBy prop to the id of the element containing your label. E.g.
<RadioButton ariaLabelledBy={myId}>
<div className="bolt-radio-button-label" id={getSafeId(myId)}>
{label-text}
<span className="sub-text-class">{sub-text}</span>
</div>
<RadioButton>