Usage
Radio buttons let users choose a single option from a set of mutually exclusive choices. Give every radio in a group the same name so selecting one deselects the others, and a distinct value.
Radios are always grouped, so wrap them in a Field Set with a Field Legend: the legend labels the question the radios answer, and the Field Set exposes the group to assistive technology. Add a Field Description for a group-level hint and a Field Error for validation. Each radio also renders its own built-in label when used standalone; inside a Field Set it steps aside automatically.
import "@nordhealth/components/lib/Radio"
import "@nordhealth/components/lib/Field"
import "@nordhealth/components/lib/FieldLabel"
import "@nordhealth/components/lib/FieldSet"
import "@nordhealth/components/lib/FieldLegend"
import "@nordhealth/components/lib/FieldGroup"
import "@nordhealth/components/lib/FieldDescription"
import "@nordhealth/components/lib/FieldError"
Standalone or inside a Field
Use the control on its own with its built-in label, hint and error, or wrap it in a Field — the Field then provides the labelling. Both render the same control:
Examples
Checked
Set checked on the radio that should be selected by default.
Sizes
The size attribute accepts s, m (default) and l.
Disabled
Use disabled to prevent interaction.
Required
Set required on the Field Label to show the indicator and mark the group required.
Hidden label
Visually hide the per-radio label when the legend and surrounding layout already convey each option, keeping it available to assistive technology.
Subscription plan
A real-world group of radios laid out as a set of plans the user chooses between.
Hint and error
Give the group a hint with a Field Description, show validation with a Field Error and mark the Field Set invalid.
RTL
Radios follow the document or container direction. Toggle the direction to see the label and control mirror.
Accessibility
- All radios in one group must share the same
nameso they behave as a single, mutually-exclusive set and arrow keys move selection between them. - Group radios under a Field Set with a Field Legend so the question the radios answer is announced — the Field Set exposes
role="group"named by its legend. - Give each radio an accessible name with a Field Label connected via
for. - Mark a required group by setting
requiredon the Field Label of the relevant control, or convey it in the legend. - Convey validation with a Field Error rather than colour alone — it is a live region announced to assistive technology, and marking the Field Set
invalidkeeps the styling in sync.
API reference
Radio
Radio buttons are graphical user interface elements that allow user to choose only one option from a predefined set of mutually exclusive options.
<nord-radio></nord-radio>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
checked | checked | Controls whether the checkbox is checked or not. | boolean | false |
size | size | The size of the component. | 's' | 'm' | 'l' | 'm' |
placeholder | placeholder | Placeholder text to display within the control. | string | undefined | — |
required | required | Determines whether the control is required or not.
A required control is announced as such to assistive technology and, inside
a <nord-field>, drives the required indicator on the <nord-field-label>.
When using this property you need to also set “novalidate” attribute on a form element to prevent browser from displaying its own validation errors. | boolean | false |
disabled | disabled | Makes the component disabled. This prevents users from being able to interact with the component, and conveys its inactive state to assistive technologies. | boolean | false |
name | name | The name of the form component. | string | undefined | — |
value | value | The value of the form component. | string | '' |
form | form | Gets the form, if any, associated with the form element. The setter accepts a string, which is the id of the form. | HTMLFormElement | null | — |
Field properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
label | label | Label for the control. Ignored when the control is wrapped in a
<nord-field>, which provides the label via <nord-field-label>. | string | '' |
hint | hint | Optional hint text shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-description>. | string | undefined | — |
hintBelow | hint-below | Renders the hint below the control and any error instead of below the label. | boolean | false |
hideLabel | hide-label | Visually hide the label, but still expose it to assistive technologies. | boolean | false |
error | error | Optional error shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-error>. | string | undefined | — |
hideRequired | hide-required | Visually hide the required indicator, but still expose the required state to assistive technologies. | boolean | false |
Slots
| Slot name | Description |
|---|---|
label | Use when a label requires more than plain text. |
hint | Optional slot that holds hint text for the input. |
error | Optional slot that holds error text for the input. |
Methods
| Method name | Parameters | Description |
|---|---|---|
focus(options?: FocusOptions) => void | options: An object which controls aspects of the focusing process. | Programmatically move focus to the component. |
blur() => void | N/A | Programmatically remove focus from the component. |
click() => void | N/A | Programmatically simulates a click on the component. |
| Event | Detail Type | Description |
|---|---|---|
input | NordEvent | Fired as the user types into the input. |
change | NordEvent | Fired whenever the input's value is changed via user interaction. |
CSS Properties
CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.
| Property | Description | Default |
|---|---|---|
--n-label-color | Controls the text color of the label, using our color tokens. | var(--n-color-text) |
Design guidelinesFor designers
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Use a radio component when users can only select one option from a list.
- Favor radios over a select component when there are a small number of options. This reduces the number of clicks a user has to make, increasing efficiency.
- Radio buttons are grouped by their
nameattribute. Therefore, it is crucial that the samenameis used for a group of radios. - Give each radio within a group a unique
value. - Radios must be grouped for accessibility — wrap them in a Field Set with a Field Legend. The legacy Fieldset still works but is deprecated.
- In most cases, a stack component should be used to layout a group of radio buttons.
Don’t
- Don’t place interactive content (buttons, links etc) inside the label.
- Don’t use when a user can select more than one option. In this case, use a checkbox instead.
- Don’t use for “accepting terms of service” and similar functionality. Use a checkbox instead.
- When you have more than 10 options to choose from. Consider using a select instead.
Hint placement
Hint text is rendered above the control by default to preserve existing behavior for current consumers. Use the hint-below property to opt in to rendering the hint below the control and any error.
This is a non-breaking rollout for teams adopting the new layout gradually. Existing integrations keep the current placement unless hint-below is explicitly set.
Content guidelines
Radio button labels should be clear, accurate and predictable. It should be possible for the user to understand what they are enabling or disabling:
When writing radio button labels, always write them in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):
Avoid ending in punctuation if it’s a single sentence, word, or a fragment:
Do not use commas or semicolons at the end of each line
Additional considerations
- Hint text can be used to offer further information or explanation for an option.
- Once a radio has been selected, users cannot return to having no radios selected without refreshing their browser window. Therefore, you should include "None of the above" or "I do not know" if they are valid options.
- In most cases, radio buttons should be stacked vertically. However, radio buttons can be stacked horizontally when there are only two options with short labels. An example might be a yes/no question.