Components
Checkbox
Checkbox allows users to select one or more options. It can also be used in situations where the user needs to confirm something.
HTML
Unable to parse html
const Preview = () => { return ( <Checkbox label='Checkbox label' description='Description' value='value' /> ); }; render(<Preview />)
Usage
Use the classname ds-input on <input> along with type="checkbox".
For a valid form element, we recommend using <ds-field> together with a <label>.
CSS variables and data attributes
Sizes are controlled with data-size and colors with data-color. The component will inherit these from the nearest parent.
Checkbox is ds-input with type="checkbox", so variables and data attributes that apply to input also apply to checkbox.
| Name | Value |
|---|---|
| data-width | auto |
| Name | Value |
|---|---|
| --dsc-input-padding-block | var(--ds-size-2) |
| --dsc-input-padding-inline | var(--ds-size-3) |
| --dsc-input-padding | var(--dsc-input-padding-block) var(--dsc-input-padding-inline) |
| --dsc-input-size--toggle | var(--ds-size-6) |
| --dsc-input-size | var(--ds-size-12) |
| --dsc-input-background--readonly | var(--ds-color-neutral-surface-tinted) |
| --dsc-input-background | var(--ds-color-neutral-surface-default) |
| --dsc-input-border-color--readonly | var(--ds-color-neutral-border-subtle) |
| --dsc-input-border-color | var(--ds-color-neutral-border-default) |
| --dsc-input-border-style | solid |
| --dsc-input-border-width--toggle | max(var(--ds-border-width-default),calc(var(--ds-size-1)/2)) |
| --dsc-input-border-width | var(--ds-border-width-default) |
| --dsc-input-outline-color--hover | var(--ds-color-neutral-border-default) |
| --dsc-input-outline-color--toggle--hover | var(--dsc-input-accent-color) |
| --dsc-input-outline-width--hover | var(--ds-border-width-default) |
| --dsc-input-outline-style--hover | solid |
| --dsc-input-color--readonly | var(--ds-color-neutral-text-default) |
| --dsc-input-color | var(--ds-color-neutral-text-default) |
| --dsc-input-stroke-color | var(--ds-color-base-contrast-default) |
| --dsc-input-stroke-color--invalid | var(--ds-color-danger-base-contrast-default) |
| --dsc-input-stroke-width | 0.05em |
| --dsc-input-accent-color | var(--ds-color-base-default) |
| --dsc-input-accent-color--invalid | var(--ds-color-danger-text-subtle) |
| --dsc-input-line-height | var(--ds-line-height-md) |
Examples
Grouping
Use fieldset for grouping multiple choices.
HTML
Unable to parse html
const GroupEn = () => { const { getCheckboxProps } = useCheckboxGroup({ value: ['email'], }); return ( <Fieldset> <Fieldset.Legend>How would you prefer us to contact you?</Fieldset.Legend> <Fieldset.Description> Select all the options that are relevant to you. </Fieldset.Description> <Checkbox label='E-mail' {...getCheckboxProps('email')} /> <Checkbox label='Phone' {...getCheckboxProps('phone')} /> <Checkbox label='Text message' {...getCheckboxProps('text')} /> </Fieldset> ); }; render(<GroupEn />)
Outline
data-variant="outline" adds extra padding and a border around the selection to create a larger clickable area.
HTML
Unable to parse html
const OutlineEn = () => { const { getCheckboxProps } = useCheckboxGroup({ value: ['operations'], variant: 'outline', }); return ( <Fieldset> <Fieldset.Legend> Which notifications do you want to receive? </Fieldset.Legend> <Fieldset.Description> Choose the notification types that are relevant to you. </Fieldset.Description> <Checkbox label='Service updates' description='Alerts about planned maintenance and service disruptions.' {...getCheckboxProps('operations')} /> <Checkbox label='Reminders' description='Alerts about deadlines and tasks that need your attention.' {...getCheckboxProps('reminders')} /> </Fieldset> ); }; render(<OutlineEn />)
ReadOnly
type="checkbox" is always :read-only and does not support this in the same way as input types you can type into.
If you set readonly on checkbox we ensure that it behaves as if it has read-only access by stopping onClick and onChange.
The user will still be able to focus on the element.
HTML
Unable to parse html
const ReadOnly = () => ( <Checkbox label='Checkbox label' description='Description' value='value' readOnly /> ); render(<ReadOnly />)
React
In React, building a checkbox is simpler, because we have a ready-made component that handles most of the logic and state management for us.
Checkbox is a composite component that uses field, label, validation message, and input to create a checkbox.
We also have a dedicated useCheckboxGroup React hook to make it easier to manage a group of Checkbox components.
- disabled
- Description
Disables element @note Avoid using if possible for accessibility purposes
- Type
boolean
- readOnly
- Description
Toggle `readOnly`
- Type
boolean
- data-indeterminate
- Description
Indeterminate state for checkbox inputs Only works when used inside `Field` component
- Type
boolean- Default
false
- aria-label
- Description
Optional aria-label
- Type
string
- label
- Description
Checkbox label
- Type
ReactNode
- description
- Description
Description for field
- Type
ReactNode
- value
- Description
Value of the `input` element
- Type
string | number | readonly string[]
- error
- Description
Error message for field
- Type
ReactNode
- variant
- Description
If outline, the checkbox will have a border.
- Type
"outline"
- aria-labelledby
- Type
string
| Name | Type | Default | Description |
|---|---|---|---|
| disabled | boolean | - | Disables element @note Avoid using if possible for accessibility purposes |
| readOnly | boolean | - | Toggle `readOnly` |
| data-indeterminate | boolean | false | Indeterminate state for checkbox inputs Only works when used inside `Field` component |
| aria-label | string | - | Optional aria-label |
| label | ReactNode | - | Checkbox label |
| description | ReactNode | - | Description for field |
| value | string | number | readonly string[] | - | Value of the `input` element |
| error | ReactNode | - | Error message for field |
| variant | "outline" | - | If outline, the checkbox will have a border. |
| aria-labelledby | string | - | - |
Indeterminate checkbox
Use useCheckboxGroup to create a parent checkbox that can select or clear all options in the group.
This activates an additional state, indeterminate, alongside checked and unchecked. It is shown as a horizontal line when one or more checkboxes are selected in the group. It is shown as a regular checkbox when all checkboxes in the group share the same state.
This is enabled by setting allowIndeterminate: true in getCheckboxProps.
React
Unable to parse html
const InTableEn = () => { const tableData = [ { id: 1, navn: 'Lise Nordmann', epost: 'lise@nordmann.no', telefon: '68051156', }, { id: 2, navn: 'Kari Nordmann', epost: 'kari@nordmann.no', telefon: '68059679', }, { id: 3, navn: 'Ola Nordmann', epost: 'ola@nordmann.no', telefon: '68055731', }, { id: 4, navn: 'Per Nordmann', epost: 'per@nordmann.no', telefon: '68059631', }, ]; const { getCheckboxProps } = useCheckboxGroup({ name: 'checkbox-table', value: ['2', '3'], }); return ( <Table> <colgroup> {/* ensure the first column only takes up the necessary space */} <col style={{ width: '1px' }} /> <col /> <col /> </colgroup> <Table.Head> <Table.Row> <Table.HeaderCell> <Checkbox aria-label='Select all' {...getCheckboxProps({ allowIndeterminate: true, value: 'all', })} /> </Table.HeaderCell> <Table.HeaderCell>Name</Table.HeaderCell> <Table.HeaderCell>E-mail</Table.HeaderCell> </Table.Row> </Table.Head> <Table.Body> {tableData.map((person) => ( <Table.Row key={person.id}> <Table.Cell> <Checkbox aria-labelledby={`checkbox-${person.id}-name`} {...getCheckboxProps(person.id.toString())} /> </Table.Cell> <Table.Cell id={`checkbox-${person.id}-name`}> {person.navn} </Table.Cell> <Table.Cell>{person.epost}</Table.Cell> </Table.Row> ))} </Table.Body> </Table> ); }; render(<InTableEn />)