Overview

Use a radio button field in forms when someone must choose exactly one option from a small set, such as how pupils will take an assessment or who can see results.

It's the default way to use radio buttons in product UI: it adds the legend, an optional description and the error message, and connects to Form validation. For the control's states, sizes and when to use radios at all, see Radio Button.

Radio button field anatomy

#PartIn codeDescription
1LegendlabelThe question, as a legend. Shows an asterisk when the field is required.
2DescriptiondescriptionOptional. Extra context for the whole group.
3Radio buttonRadioButtonField.ItemOne per option.
4Labellabel on the itemThe option. Clicking it selects the option.
5ErrorvalidationShows under the options when validation fails.

When to use

  • In a form, when someone must choose exactly one of 2 to 5 options.
  • When the choice is confirmed by submitting the form.

For 6 or more options, use Select Field. When people can choose more than one, use Checkbox Group. When the choice applies straight away, use Segmented Control or Tabs.

Do's and Don'ts

    Do

    Use radio buttons when people must choose exactly one option from a small set.

    Don't

    Use radio buttons for multi-select, when people can choose more than one option, like assigning several classes. Use Checkbox Group instead.

    Do

    Order options logically, here from the narrowest to the widest audience, and preselect the safest one.

    Don't

    Order options randomly or alphabetically when a natural order exists.

    Do

    Stack options vertically, with one option per line.

    Don't

    Lay options out horizontally when labels vary in length. It's hard to scan, and it breaks on mobile and at 200% zoom.

Legend and description

  • Always set label. It becomes the group's legend, which screen readers announce with every option. Write it as a question or a short instruction, in sentence case.
  • Use description only when people need context to choose, for example "You can change this until the assessment starts." Don't repeat the legend.

Default selection

Preselect an option with defaultValue when there's a sensible, low-risk default. Leave it empty when the choice must be deliberate, and make it required.

Required and validation

  • Mark a field as required with validation={{ required: '…' }}. The legend shows an asterisk.
  • Validate on submit. The error appears under the options and stays until the person chooses one.
  • Word the error as what to do: "Choose how pupils will take the assessment", not "This field is required".

Required radio button field showing an error after submit

Layout

  • Use direction="column" (default) in most forms.
  • Use direction="row" only for 2 or 3 short labels, such as "Online" and "On paper", and not on narrow, mobile-width layouts.

Size

Use md (default) in teacher and admin tools. Use size="lg" on each item only on pupil-facing screens, such as answering a question.

Accessibility

  • The legend names the group. RadioButtonField renders a fieldset and legend, so screen readers announce the question with each option. Never leave label empty.
  • Each option has a clickable label. RadioButtonField.Item connects the label to its radio button, so the whole label is a target.
  • Keyboard. Tab moves into the group, onto the selected option (or the first one). Arrow keys move between options and select them. Tab again leaves the group.
  • Focus is always visible. Keyboard focus shows a 2px white gap and a 4px primary-800 ring.
  • Errors are in text. The error message has an icon and text, not just a colour change.

Options

OptionIn codeValuesDefault
LegendlabelTextRequired
DescriptiondescriptionTextNone
Directiondirectionrow, columncolumn
Default valuedefaultValueAny item's value (a string)None
Validationvalidationreact-hook-form rules, such as requiredNone
DisableddisabledOn the field or one RadioButtonField.Itemfalse
Sizesize on RadioButtonField.Itemmd, lgmd

Related