# nord-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.
## 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:
> **Do:** User settings
> **Don't:** Option 1
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):
> **Do:** User settings
> **Don't:** User Settings
Avoid ending in punctuation if it’s a single sentence, word, or a fragment:
> **Do:** Show dashboard
> **Don't:** Show dashboard.
Do not use commas or semicolons at the end of each line
> **Do:** Patients
> **Don't:** Patients;
## Examples
### Basic
```html
Label
```
### Checked
```html
```
### Disabled
```html
Checked
Unchecked
```
### Hidden Label
```html
Label
```
### Indeterminate
```html
Indeterminate
Indeterminate disabled
Indeterminate with error
This field is required
```
### Required
```html
```
### Size
```html
Label
Label
Label
```
### With A Complex Hint
```html
Label
Hint is an accessible way to provide additional information that might help the user
```
### With A Complex Label
```html
Label with color
```
### With A Hint
```html
Label
Hint is an accessible way to provide additional information that might help the user
```
### With A Hint Below
```html
Label
Hint is an accessible way to provide additional information that might help the user
This field is required
```
### With Error
```html
Label
This field is required
```
### Overview
```html
Subscribe to the newsletter
```
### States
```html
```
### Sizes
```html
```
### With Hint And Error
```html
Accept terms
You must agree before continuing.
Subscribe
This field is required
```
### Standalone
```html
```
### Field
```html
I agree to the terms
```
## API Reference
### Properties
- **indeterminate** (`boolean`, default: `false`) — Controls whether the checkbox is in an indeterminate state.
- **checked** (`boolean`, default: `false`) — Controls whether the checkbox is checked or not.
- **size** (`'s' | 'm' | 'l'`, default: `'m'`) — The size of the component.
- **placeholder** (`string | undefined`) — Placeholder text to display within the control.
- **label** (`string`, default: `''`) — Label for the control. Ignored when the control is wrapped in a
<nord-field>, which provides the label via <nord-field-label>.
- **hint** (`string | undefined`) — Optional hint text shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-description>.
- **hint-below** (`boolean`, default: `false`) — Renders the hint below the control and any error instead of below the label.
- **hide-label** (`boolean`, default: `false`) — Visually hide the label, but still expose it to assistive technologies.
- **error** (`string | undefined`) — Optional error shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-error>.
- **required** (`boolean`, default: `false`) — 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.
- **hide-required** (`boolean`, default: `false`) — Visually hide the required indicator, but still expose the required state
to assistive technologies.
- **disabled** (`boolean`, default: `false`) — Makes the component disabled. This prevents users from
being able to interact with the component, and conveys
its inactive state to assistive technologies.
- **name** (`string | undefined`) — The name of the form component.
- **value** (`string`, default: `''`) — The value of the form component.
- **form** (`HTMLFormElement | null`) — Gets the form, if any, associated with the form element.
The setter accepts a string, which is the id of the form.
### Events
- **input** (`NordEvent`) — Fired as the user types into the input.
- **change** (`NordEvent`) — Fired whenever the input's value is changed via user interaction.
### Slots
- **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
- **focus** — `focus(options?: FocusOptions) => void` — Programmatically move focus to the component.
- **blur** — `blur() => void` — Programmatically remove focus from the component.
- **click** — `click() => void` — Programmatically simulates a click on the component.
### CSS Custom Properties
- `--n-label-color` (default: `var(--n-color-text)`) — Controls the text color of the label, using our color tokens.
### Dependencies
- `icon`