RadioGroup

A radio group is used to group related options together.

View sourceView on npmReport an issueWAI-ARIA

Radio buttons are used for mutually exclusive choices, not for multiple choices. Only one radio button can be selection at a time. When a user chooses a new item, the previous choice is automatically deselected. They can be used in tiles, data tables, modals, side panels, and in forms on full-page layouts. Radio button can be used to change from one setting to another in a Listbox, page or component. It can often act as a filtering mechanism.

Anatomy

Structure

<RadioGroup>
    <Radio> /* (Required) A radio button for the RadioGroup */
        <IconList /> /* (Optional) A list of icons in the radio */
        <Icon /> /* (Optional) An icon in the radio */
        <Text /> /* (Optional) Text in the radio, required if using an Icon or an IconList */
    </Radio>
</RadioGroup>

Composed Components

A RadioGroup uses the following components:

Icon

An icon component is used to render a custom icon.

IconList

An IconList encapsulates a collection of icons.

Text

A text component is a primitive component matching Hopper's typography type scale.

Usage

Label

A radio group can have a label to provide more context to the user.

Disabled

A radio group can be disabled.

Sizes

A radio group can vary in size.

Orientation

A radio group can be displayed horizontally or vertically.

Description

A radio group can have a description to provide more information to the user.

Variants

A radio group can be bordered.

Invalid

A radio group can be invalid.

Fluid

A radio group can be expanded to full width to fill its parent container.

Controlled

A radio group can handle value state in controlled mode.

ContextualHelp

A ContextualHelp element may be placed next to the label to provide additional information or help about a RadioGroup.

No Label on Items

A radio component can be rendered without a label.

Disabled Items

A radio component can be disabled.

Description on Items

A radio component can have a description to provide more information to the user.

Icon

Each radio can be customized with an icon or an icon list.

Best Practices

Radio buttons should:

  • Always be used with an associated label component.
  • Be part of a list of radio buttons that:
    • Include at least two or more choices.
    • Are used to have users select only one option.
    • Include mutually exclusive options–this means that each option must be independant from every other option in the list.
    • List options in a logical order.
    • Have a default option selected whenever possible.

Alignment

Radio button labels are positioned to the right of their inputs. As a grouping, they have to be laid out vertically.

Placement

Radio buttons are often used in forms. In a forms, they should be placed at least 24px below or before the next component. A space of 8px between each radio button in a grouping is necessary.

Overflow content

We recommend radio button labels being fewer than three words. If you are tight on space, consider rewording the label. Do not truncate the radio button label text with an ellipsis. Long labels may wrap to a second line, and this is preferable to truncation. Text should wrap beneath the radio button so the control and label are top aligned.

States

The radio button input allows for two states: unselected and selected. The default view of a radio button is having at least one radio button preselected. Only one radio should be selected at a time. When a user chooses a new item, the previous choice is automatically deselected.

Grouping in a wrapper

When the Radio group is the only control in the container, or if you need to bring an intentional prominence to this control, we suggest to organize the Radio within a wrapper and to use the Medium size which will bring more scannability to the options.

Props

RadioGroup

listProps?

The props of the list element that wraps the Radio components.

orientation?

A RadioGroup can be displayed horizontally or vertically.

Defaults to vertical.
variant?

A RadioGroup has two variants: borderless and bordered.

Defaults to borderless.
isFluid?

If true, the RadioGroup will take all available width.

Defaults to false.
form?

The element to associate the input with. The value of this attribute must be the id of a in the same document. See MDN.

style?

The inline style for the element. A function may be provided to compute the style based on component state.

children?

The children of the component. A function may be provided to alter the children based on component state.

validationBehavior?

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

Defaults to 'native'.
name?

The name of the input element, used when submitting an HTML form. See MDN.

value?

The current value (controlled).

defaultValue?

The default value (uncontrolled).

isDisabled?

Whether the input is disabled.

isReadOnly?

Whether the input can be selected but not changed by the user.

isRequired?

Whether user input is required on the input before form submission.

isInvalid?

Whether the input value is invalid.

validate?

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

description?

The helper message of the field.

errorMessage?

The error message of the field.

label?

The label of the field.

necessityIndicator?

Whether the required state should be shown as an asterisk or a label, which would display (Optional) on all non required field labels.

size?

A Field can vary in size.

Defaults to md.
contextualHelp?

A ContextualHelp element to place next to the label.

Radio

size?

A radio can vary in size.

Defaults to md.
style?

The inline style for the element. A function may be provided to compute the style based on component state.

children?

The children of the component. A function may be provided to alter the children based on component state.

value

The value of the radio button, used when submitting an HTML form. See MDN.

isDisabled?

Whether the radio button is disabled or not. Shows that a selection exists, but is not available in that circumstance.

autoFocus?

Whether the element should receive focus on render.

inputRef?

A ref for the HTML input element.

className?

The CSS className for the element. A function may be provided to compute the class based on component state.

Migration Notes

RadioGroup

Coming from Orbiter, you should be aware of the following changes:

  • required has been renamed to isRequired.
  • onChange signature has changed (no event are passed).
  • disabled has been renamed to isDisabled.
  • autofocus is not supported. You must use autofocus on the actual Radio.
  • fluid has been renamed to isFluid.
  • reverse is not supported, use flex-direction or row-reverse instead.
  • The default orientation is now vertical instead of horizontal.
  • validationState has been removed. Use isInvalid instead. There is no isValid.
  • wrap has been removed. If horizontal, radios will wrap.
  • There is no align prop. If needed, the styled system can be used.
  • inline prop is not available.

Radio

Coming from Orbiter, you should be aware of the following changes:

  • The Counter component is no longer allowed as a specialized slot.
  • Values are not auto-generated when missed.
  • onChange is only supported on RadioGroup, not on Radio.
  • onValueChange has been deleted, use onChange instead.
  • checked has been renamed to isSelected.
  • disabled has been renamed to isDisabled.
  • required has been renamed to isRequired.
  • reverse is not supported, use flex-direction or row-reverse instead.
  • validationState has been removed. Yse isInvalid instead. There is no isValid.
  • value is required.