Usage
Checkboxes let users choose one or more options from a limited set. For more than 10 options, use a Select instead. Group related checkboxes with a shared name when submitting them in a form.
Checkbox is a compact control, so wrap it in a horizontal Field: the Field owns the label, helper text and error, and orientation="horizontal" places the label beside the control. The checkbox also renders its own built-in label/hint/error when used standalone; inside a Field those step aside automatically.
import "@nordhealth/components/lib/Checkbox"
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 checkbox can be unchecked, checked, or indeterminate for a partially-selected group.
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 control required.
Hidden label
Use a visually hidden label when the surrounding context already names the control, keeping it available to assistive technology.
Hint and error
Provide context with a Field Description, show validation with a Field Error and mark the Field invalid. Set required on the Field Label to show the indicator and mark the control required.
RTL
Checkboxes follow the document or container direction. Toggle the direction to see the label and control mirror.
Accessibility
- Always give the checkbox an accessible name with a Field Label connected via
for. - Mark required checkboxes by setting
requiredon the Field Label; it shows the indicator and marks the control required. - The
indeterminatestate is communicated to assistive technology, but it is not a value a user can set directly — set it in code to represent a partially-selected group. - When several checkboxes form one question, group them under a legend with a Field Set and Field Legend so the relationship is announced.
- Convey validation with a Field Error rather than colour alone — it is associated with the control and announced to assistive technology.
API reference
Checkbox
Checkboxes allow user to choose one or more options from a limited set of options. If you have more than 10 options, please use Select component instead.
<nord-accordion></nord-accordion>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
indeterminate | indeterminate | Controls whether the checkbox is in an indeterminate state. | boolean | false |
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) |
Dependencies
This component is internally dependent on the following components:
Design guidelinesFor designers
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Use for making it possible to choose one or more options from a limited number of options.
- Use for “accepting terms of service” and similar functionality.
- Use in forms to toggle something on or off.
Don’t
- Avoid using when you have more than 10 options to choose from.
- Don’t change the selection of another checkbox when another one is clicked. Only exception is when a checkbox 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
Checkbox labels should be clear, accurate and predictable. It should be possible for the user to understand what they are selecting:
When writing checkbox 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