DesignKit: design tools and components

Playground

Design system

Size

Checked

Indeterminate

Disabled

md checkbox

comfortable

Send notes

Family: Choice
Complexity: core
Status: stable
Mathematical fixtures: 9

choicebinaryindeterminate

Overview

Use checkboxes when users can combine multiple choices.

Aliases

check box

Foundations

Contrast and distinctness,Spacing,Proof system

When to use

Use Checkbox for independent choices that can be combined.
Use the indeterminate state for parent or aggregate selections when some children are selected.

When not to use

Do not use Checkbox when only one option can be selected; use RadioGroup or SegmentedControl.
Do not use Checkbox as a binary system toggle; use Switch when the state reads as on or off.

Structural parts

native checkbox

control

The interactive binary or indeterminate control.

state mark

mark

Shows checked or indeterminate state.

visible label

label

Explains the choice.

supporting copy

description

Optional clarifying helper copy.

Public interface

Props
Name	Type	Default	Description
`checked`	`boolean`	`false`	Controlled checked state.
`indeterminate`	`boolean`	`false`	Controlled mixed state.
`label`	`string`	`—`	Visible checkbox label.
`description`	`string`	`—`	Supporting helper copy.
`error`	`string`	`—`	Optional problem text for grouped or validated use.
`required`	`boolean`	`false`	Marks the checkbox as required.
`disabled`	`boolean`	`false`	Disables interaction.
`name`	`string`	`—`	Native form field name.
`id`	`string`	`—`	Optional explicit id for label binding.
`size`	`'sm' \| 'md'`	`'md'`	Chooses the checkbox size recipe.
`onChange`	`(detail: { checked: boolean; indeterminate: boolean }) => void`	`—`	Receives the checked and mixed state after native activation.
`theme`	`ThemeContract`	`—`	Sets the theme used to resolve component styles.

Events
Name	Payload	Description
`change`	`{ checked: boolean; indeterminate: boolean }`	Fires with the checked and mixed state.

Slots
Name	Description
`default`	`Checkbox` is prop-driven and does not expose custom slots.

Variants, sizes, and states

Variants

default: Checkbox uses one structural recipe and varies by size and state.

Sizes

sm: Compact checkbox for dense UI.
md: Default checkbox size.

States

unchecked: No selection.
checked: The choice is selected.
indeterminate: A mixed or partial aggregate state.
disabled: Semantically disabled and visibly muted.

Accessibility

Semantics

Uses a native checkbox input and exposes correct checked or mixed semantics.

Keyboard

Supports native focus and Space activation behavior.

Screen readers

Label and description remain attached to the checkbox input, including the mixed state.

Checklist

Verify that the control has an accessible name.
Verify that keyboard focus is visible in every state and size.
Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-checkbox-gap: clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-checkbox-hit-size: 44px
--dk-checkbox-copy-gap: 0.22rem
--dk-checkbox-motion-duration: 200ms
--dk-motion-duration: 200ms

control

--dk-checkbox-bg: #f2f5fb
--dk-checkbox-border: #95989d
--dk-checkbox-border-width: 1.5px
--dk-checkbox-size: 20px
--dk-checkbox-radius: 0.45rem
--dk-checkbox-shadow: none
--dk-checkbox-focus-ring-color: #2072e4

mark

--dk-checkbox-mark-color: #ffffff
--dk-checkbox-mark-size: 0.82rem

label

--dk-checkbox-label-color: #16181c
--dk-checkbox-label-size: clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-checkbox-label-weight: 600

description

--dk-checkbox-description-color: #16181c
--dk-checkbox-description-size: 0.8125rem

error

--dk-checkbox-error-color: #cc272e
--dk-checkbox-error-size: 0.8125rem

Implementation notes

The input uses native checkbox semantics, including indeterminate state.

Examples

Starter

One independent choice

A single checkbox with label and description.

<Checkbox label="Send notes" description="Share the update with the team." checked={true} />

Common patterns

Aggregate selection

Use the mixed state when some child items are selected.

<Checkbox label="Select all" indeterminate={true} />

Edge cases

Unavailable choice

Disabled state stays visible without pretending the option disappeared.

<Checkbox label="Enable automation" disabled={true} />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

default (size=sm)

pass

size=sm

Evidence: mathematical
Coverage: complete (4 / 4 declared kinds evaluated)
Declared: contrast, target, layout, helperText
Evaluated: contrast, target, layout, helperText
Contrast: 76.6 Lc
Target: 44 px
Layout: root · wrap 309 px single-line estimate; 145 px minimum width
240 px: pass 2 lines; 72 px estimated height320 px: pass 1 line; 44 px estimated height
Helper: 2/2

default (size=md)

pass

size=md

Evidence: mathematical
Coverage: complete (4 / 4 declared kinds evaluated)
Declared: contrast, target, layout, helperText
Evaluated: contrast, target, layout, helperText
Contrast: 76.6 Lc
Target: 44 px
Layout: root · wrap 309 px single-line estimate; 145 px minimum width
240 px: pass 2 lines; 72 px estimated height320 px: pass 1 line; 44 px estimated height
Helper: 2/2

default (size=lg)

pass

size=lg

Evidence: mathematical
Coverage: complete (4 / 4 declared kinds evaluated)
Declared: contrast, target, layout, helperText
Evaluated: contrast, target, layout, helperText
Contrast: 76.6 Lc
Target: 44 px
Layout: root · wrap 309 px single-line estimate; 145 px minimum width
240 px: pass 2 lines; 72 px estimated height320 px: pass 1 line; 44 px estimated height
Helper: 2/2

checked (size=sm)

pass

size=sm

Evidence: mathematical
Coverage: complete (4 / 4 declared kinds evaluated)
Declared: contrast, target, layout, helperText
Evaluated: contrast, target, layout, helperText
Contrast: 76.6 Lc
Target: 44 px
Layout: root · wrap 309 px single-line estimate; 145 px minimum width
240 px: pass 2 lines; 72 px estimated height320 px: pass 1 line; 44 px estimated height
Helper: 2/2

checked (size=md)

pass

size=md

Evidence: mathematical
Coverage: complete (4 / 4 declared kinds evaluated)
Declared: contrast, target, layout, helperText
Evaluated: contrast, target, layout, helperText
Contrast: 76.6 Lc
Target: 44 px
Layout: root · wrap 309 px single-line estimate; 145 px minimum width
240 px: pass 2 lines; 72 px estimated height320 px: pass 1 line; 44 px estimated height
Helper: 2/2

checked (size=lg)

pass

size=lg

Evidence: mathematical
Coverage: complete (4 / 4 declared kinds evaluated)
Declared: contrast, target, layout, helperText
Evaluated: contrast, target, layout, helperText
Contrast: 76.6 Lc
Target: 44 px
Layout: root · wrap 309 px single-line estimate; 145 px minimum width
240 px: pass 2 lines; 72 px estimated height320 px: pass 1 line; 44 px estimated height
Helper: 2/2

indeterminate (size=sm)

pass

size=sm

Evidence: mathematical
Coverage: complete (4 / 4 declared kinds evaluated)
Declared: contrast, target, layout, helperText
Evaluated: contrast, target, layout, helperText
Contrast: 76.6 Lc
Target: 44 px
Layout: root · wrap 309 px single-line estimate; 145 px minimum width
240 px: pass 2 lines; 72 px estimated height320 px: pass 1 line; 44 px estimated height
Helper: 2/2

indeterminate (size=md)

pass

size=md

Evidence: mathematical
Coverage: complete (4 / 4 declared kinds evaluated)
Declared: contrast, target, layout, helperText
Evaluated: contrast, target, layout, helperText
Contrast: 76.6 Lc
Target: 44 px
Layout: root · wrap 309 px single-line estimate; 145 px minimum width
240 px: pass 2 lines; 72 px estimated height320 px: pass 1 line; 44 px estimated height
Helper: 2/2

indeterminate (size=lg)

pass

size=lg

Evidence: mathematical
Coverage: complete (4 / 4 declared kinds evaluated)
Declared: contrast, target, layout, helperText
Evaluated: contrast, target, layout, helperText
Contrast: 76.6 Lc
Target: 44 px
Layout: root · wrap 309 px single-line estimate; 145 px minimum width
240 px: pass 2 lines; 72 px estimated height320 px: pass 1 line; 44 px estimated height
Helper: 2/2

Related components and foundations

Multiline input with labels, guidance, and errors.

Binary setting with on and off states.

Switch

Binary setting with on and off states.

RadioGroup

Single-choice group with visible options and descriptions.

Table

Data table with sorting, selection, and sticky headers.

Contrast and distinctness

Check foreground contrast and separation between related colors.

Spacing

Relate component padding and layout gaps through shared spacing steps.

Proof system

Inspect calculated component checks and their coverage.

Chip

Compact selectable label with an optional dismiss action.

Switch

Binary setting with on and off states.

RadioGroup

Single-choice group with visible options and descriptions.

SegmentedControl

Compact single-choice control for switching modes.