Usage
A Toggle is a switch for an on/off setting that takes effect immediately, such as enabling a feature. Reach for a Checkbox instead when the choice is part of a list that is confirmed on submit.
Toggle is a compact control, so wrap it in a horizontal Field: set orientation="horizontal" on the Field and place a Field Label beside the switch. The Field owns the label, helper text and error. The toggle also renders its own built-in label/hint/error when used standalone; inside a Field those step aside automatically.
import "@nordhealth/components/lib/Toggle"
import "@nordhealth/components/lib/Field"
import "@nordhealth/components/lib/FieldLabel"
import "@nordhealth/components/lib/FieldDescription"
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
States
A toggle can be on (checked) or off.
Sizes
The size attribute accepts s, m (default) and l.
Reverse order
Use reverse to place the label before the switch, which works well in full-width settings rows.
Disabled
Use disabled to prevent interaction.
Hidden label
Use a visually hidden label when the surrounding context already names the toggle, keeping it available to assistive technology.
With a hint
Add a Field Description to explain what the toggle controls.
Error
Show validation with a Field Error and mark the Field invalid.
RTL
Toggles follow the document or container direction. Toggle the direction to see the switch and label mirror.
Accessibility
- Always give the toggle an accessible name with a Field Label connected via
for. - A toggle should take effect immediately. If the setting is only applied after submitting a form, prefer a Checkbox so the interaction matches user expectations.
- Convey validation with a Field Error rather than colour alone — it is associated with the toggle and announced to assistive technology.
- The toggle exposes a checkbox-style on/off state to assistive technology and is operable with the keyboard like any other form control.
API reference
Toggle
Toggle switch gives control over a feature or option that can be turned on or off. If a physical switch would work for the action, a toggle is probably the best component to use.
<nord-toggle></nord-toggle>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
checked | checked | Controls whether the toggle is checked or not. | boolean | false |
reverse | reverse | Controls whether the contents are displayed in reverse order, putting the label before the toggle. | boolean | false |
size | size | The size of the toggle switch. | '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 toggles when your intent is to turn something on or off instantly.
- Use for any feature or option that can be turned on or off.
- If a physical switch would work for the action, the toggle is probably the best component to use.
- Use for making it possible to choose one or more options from a limited number of options.
Don’t
- Toggles should never require users to click a button to apply or save the setting.
- Avoid using when you have more than 10 options to choose from.
- Don’t change the selection of another toggle when another one is clicked. Only exception is when a toggle is used to make a bulk selection of multiple items.
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
Toggle labels should be clear, accurate and predictable. It should be possible for the user to understand what they are selecting:
When writing toggle 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