Newskit Logo
View Github

Actions & Inputs

Radio Button

Radio Buttons are selection controls that are typically used in forms. They are used for exclusive selection - allowing users to select one of multiple options in a Radio Group.

Status

Beta

Introduced

v5.3.0
View code

Status

Beta

Introduced

Anatomy

The Radio Button contains one required element and three optional elements.

ItemNameDescriptionComponentOptional

Options

The Radio Button has options that can be used to provide an appropriate experience for different use cases.

Size

There are three sizes of the Radio Button input and the feedback element; small, medium (default), and large.

The icon that appears within the Radio Button input changes at all three sizes of Radio Button but can be overridden.

Icon

The icon that appears within the Radio Button input can be overridden across different states.

Feedback

The feedback element is non-interactive and appears in the background behind the Radio Button input for visual feedback on hover.

Label

The Radio Button has a label that appears to the right (end) of a Radio Button, for context.

In the case of needing a label on the left (start) of a Radio Button, this can be set via thelabelPosition prop.

Radio Group

The Radio Group component is used to group Radio Buttons together.

Fieldset

Selection controls (inputs), such as the FormInput, Radio Button, and Checkbox, can be grouped together with other selection controls, Labels, and Assistive Text together in a Fieldset. The Fieldset has a caption that gives a title attributed to the elements that appear in the Fieldset, called a Legend.

The Fieldset can also support other selection controls (inputs) such as the FormInput, FormInput Switch, and FormInput TextField.

For more information, please refer to the Fieldset component.

Size

There are three sizes of the Radio Button input and the feedback element; small, medium (default), and large.

The icon that appears within the Radio Button input changes at all three sizes of Radio Button but can be overridden.

Icon

The icon that appears within the Radio Button input can be overridden across different states.

Feedback

The feedback element is non-interactive and appears in the background behind the Radio Button input for visual feedback on hover.

Label

The Radio Button has a label that appears to the right (end) of a Radio Button, for context.

In the case of needing a label on the left (start) of a Radio Button, this can be set via thelabelPosition prop.

Radio Group

The Radio Group component is used to group Radio Buttons together.

Fieldset

Selection controls (inputs), such as the FormInput, Radio Button, and Checkbox, can be grouped together with other selection controls, Labels, and Assistive Text together in a Fieldset. The Fieldset has a caption that gives a title attributed to the elements that appear in the Fieldset, called a Legend.

The Fieldset can also support other selection controls (inputs) such as the FormInput, FormInput Switch, and FormInput TextField.

For more information, please refer to the Fieldset component.

States

The Radio Button has the following states:

Base

The Radio Button has a base (default) state. This is the base style of the Radio Button before it has been interacted with by a user.

Hover

The Radio Button has a hover state. The style of the Radio Button changes to visually communicate and provide feedback to the user that the Radio Button is an interactive element. The style of the label remains the same. The label can also be interacted with (hovered) to check the Radio Button.

Focus

The Radio Button in a focus state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Focus Hover

The Radio Button in a focus hover state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Checked

The Radio Button has a checked state. The style of the Radio Button input changes to visually communicate and provide feedback to the user that the Radio Button has been checked. The style of the label remains the same.

Checked Hover

The Radio Button has a checked hover state. The style of the Radio Button input changes to visually communicate and provide feedback to the user that the Radio Button has been checked and hovered over. The style of the label remains the same.

Checked Focus

The Radio Button in a checked focus state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Checked Focus Hover

The Radio Button in a checked focus hover state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Invalid

The Radio Button in an invalid state changes style when the Radio Button selection doesn’t conform to a specific format eg. attempting to proceed without selecting a required Radio Group in a Form. The Form component is used to apply validation behaviour. The style of the label remains the same.

Invalid Focus

The Radio Button in an invalid focus state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Invalid Hover

The Radio Button has an invalid hover state. The style of the Radio Button input changes to visually communicate and provide feedback to the user that the Radio Button is in an invalid state and hovered over. The style of the label remains the same.

Invalid Focus Hover

The Radio Button in an invalid focus hover state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Checked Invalid

The Radio Button has a checked invalid state. The style of the Radio Button input changes to visually communicate and provide feedback to the user that the Radio Button has been checked and is in an invalid state. The style of the label remains the same.

Checked Invalid Focus

The Radio Button in a checked invalid focus state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Checked Invalid Hover

The Radio Button has a checked invalid hover state. The style of the Radio Button input changes to visually communicate and provide feedback to the user that the Radio Button has been checked and is in an invalid state, and hovered over. The style of the label remains the same.

Checked Invalid Focus Hover

The Radio Button in a checked invalid focus hover state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Valid

The Radio Button in a valid state changes style when the Radio Button selection conforms to a specific format eg. updating preferences in a Form. The Form component is used to apply validation behaviour. The style of the label remains the same.

Valid Focus

The Radio Button in a valid focus state communicates that a user has highlighted a Checkbox, using an input method such as a keyboard or voice.

Valid Hover

The Radio Button has a valid hover state. The style of the Radio Button input changes to visually communicate and provide feedback to the user that the Radio Button is in a valid state and hovered over. The style of the label remains the same.

Valid Focus Hover

The Radio Button in a valid focus hover state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Checked Valid

The Radio Button has a checked valid state. The style of the Radio Button input changes to visually communicate and provide feedback to the user that the Radio Button has been checked and is in a valid state. The style of the label remains the same.

Checked Valid Focus

The Radio Button in a checked valid focus state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Checked Valid Hover

The Radio Button has a checked valid hover state. The style of the Radio Button input changes to visually communicate and provide feedback to the user that the Radio Button has been checked and is in a valid state, and hovered over. The style of the label remains the same.

Checked Valid Focus Hover

The Radio Button in a checked valid focus hover state communicates that a user has highlighted a Radio Button, using an input method such as a keyboard or voice.

Disabled

The Radio Button in a disabled state communicates that a Radio Button exists, but is not available to the user in that scenario. When the user's cursor hovers over a Radio Button in a disabled state, the cursor shows as not allowed.

Disabled Radio Buttons are often used to maintain layout consistency and communicate that a Radio Button may become available if another condition has been met. The style of the label (colour) also changes to indicate that the Radio Button is disabled.

Checked Disabled

The Radio Button in a checked disabled state communicates that a Radio Button exists, but is not available to the user in that scenario. When the user's cursor hovers over a Radio Button in a checked disabled state, the cursor shows as not allowed.

Disabled checked Radio Buttons are often used to maintain layout consistency and communicate that a Radio Button may become available if another condition has been met. The style of the label (colour) also changes to indicate that the Radio Button is checked and disabled.

The Feedback element becomes visible (configurable) on state change, eg hover.

Behaviours

The following guidance describes how the Radio Button component behaves.

Label overflow wrap

When a Label is too long for the available horizontal space, it wraps to form another line.

Clickable area

The Radio Button feedback element indicates the minimum clickable area for the Radio Button input (also known as hit area, or touch target area). The size of the clickable area changes according to the size of the Radio Button. The associated Label is also clickable next to the Radio Button.

Focusable area

Both the Radio Button input and Label are interactive, and a user can hover over either, but only the Radio Button input itself is focusable by using an input method such as a keyboard or voice.

Validation

The Radio Button validation rules can be defined for onSubmit or onBlur, for both the initial validation and re-validation using the Form.

For more information, please refer to the Form component.

Note

Validation only works if the FormInput Radio Button uses the Form component.

Exclusive selection

Checking a Radio Button in a Radio Group will uncheck all other Radio Buttons in that group.

Autofocus

The Radio Button can be set to be auto-focused on page load (when mounted).

Default checked

The Radio Button's initial state can be set to be checked or unchecked by default (controlled or uncontrolled).

Adding checked to the native HTML element will set the Radio Button as selected by default.

Voiceover will read out the Radio Button to the user and let them know it is selected.

Label overflow wrap

When a Label is too long for the available horizontal space, it wraps to form another line.

Clickable area

The Radio Button feedback element indicates the minimum clickable area for the Radio Button input (also known as hit area, or touch target area). The size of the clickable area changes according to the size of the Radio Button. The associated Label is also clickable next to the Radio Button.

Focusable area

Both the Radio Button input and Label are interactive, and a user can hover over either, but only the Radio Button input itself is focusable by using an input method such as a keyboard or voice.

Validation

The Radio Button validation rules can be defined for onSubmit or onBlur, for both the initial validation and re-validation using the Form.

For more information, please refer to the Form component.

Note

Validation only works if the FormInput Radio Button uses the Form component.

Exclusive selection

Checking a Radio Button in a Radio Group will uncheck all other Radio Buttons in that group.

Autofocus

The Radio Button can be set to be auto-focused on page load (when mounted).

Default checked

The Radio Button's initial state can be set to be checked or unchecked by default (controlled or uncontrolled).

Adding checked to the native HTML element will set the Radio Button as selected by default.

Voiceover will read out the Radio Button to the user and let them know it is selected.

Usage

The following guidance describes how and when to appropriately use the Radio Button component.

Do

Use Radio Buttons when a user can select only one option from a list.

Don’t

Don’t use Radio Buttons when a user can select multiple options from a list. In this case, use a group of Checkboxes.

Do

Radio Buttons should always have an associated Label to give users context of what the Radio Button represents.

Don’t

Avoid placing Labels to the left (start) of Radio Buttons when there are multiple Radio Buttons grouped together to avoid layout misalignment. Instead place Labels to the right (end) so that when used together in forms, Radio Button inputs align vertically, which makes them easier to find, especially for users of screen magnifiers.

Do

Radio Buttons should be displayed stacked vertically for consistent alignment and positioning across different breakpoints.

Do

Use Assistive Text to provide context to the Radio Button group. For example, why a selection is required.

Accessibility Considerations

The Radio Button has the following accessibility considerations:

Grouping Radio Buttons

It is recommended to group Radio Buttons together in a RadioGroup. Other related elements such as Labels and Assistive Text should be grouped together using the Fieldset component, with a title attributed to the elements that appear in the Fieldset, called a Legend.

Focus order
OrderElementRole
Keyboard Interactions
CommandDescription
WAI-ARIA
ElementAttributeValueDescriptionUser Supplied

API

The Radio Button has a range of props that can be used to define an appropriate experience for different use cases.

There are three components exported from the package; one for use within the NewsKit Form component, one for use as a controlled component, and the RadioGroup component that is used to group Radio Buttons together.

FormInput Radio Button

The FormInput Radio Button has a range of props that can be used to define an appropriate experience for different use cases. Use this component within the NewsKit Form component.

NameTypeDefaultDescriptionRequired
RadioButton

The Radio Button has a range of props that can be used to define an appropriate experience for different use cases. Use this component as a controlled component, for instance where you have a custom validation mechanism.

NameTypeDefaultDescriptionRequired
RadioGroup

The Radio Group has a range of props that can be used to define an appropriate experience for different use cases. Use this component to group Radio Buttons together.

NameTypeDefaultDescriptionRequired

Compliance

All of the components in the NewsKit design system go through a comprehensive set of checks to ensure that we are producing compliant and best practice components.

FeatureDescriptionStatus

Need Help?

Cant find what you are looking for?

Need Help?

Cant find what you are looking for?