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.

| # | Part | In code | Description |
|---|---|---|---|
| 1 | Legend | label | The question, as a legend. Shows an asterisk when the field is required. |
| 2 | Description | description | Optional. Extra context for the whole group. |
| 3 | Radio button | RadioButtonField.Item | One per option. |
| 4 | Label | label on the item | The option. Clicking it selects the option. |
| 5 | Error | validation | Shows 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'slegend, which screen readers announce with every option. Write it as a question or a short instruction, in sentence case. - Use
descriptiononly 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".

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.
RadioButtonFieldrenders afieldsetandlegend, so screen readers announce the question with each option. Never leavelabelempty. - Each option has a clickable label.
RadioButtonField.Itemconnects 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-800ring. - Errors are in text. The error message has an icon and text, not just a colour change.
Options
| Option | In code | Values | Default |
|---|---|---|---|
| Legend | label | Text | Required |
| Description | description | Text | None |
| Direction | direction | row, column | column |
| Default value | defaultValue | Any item's value (a string) | None |
| Validation | validation | react-hook-form rules, such as required | None |
| Disabled | disabled | On the field or one RadioButtonField.Item | false |
| Size | size on RadioButtonField.Item | md, lg | md |