Checkbox

A checkbox turns one option on or off in a form. Group related checkboxes in tk-checkbox-group.

Stable

Figma

Overview

Usage

API

Accessibility

Product updates

Events and meetups

Research invitations

<tk-checkbox-group label="Email notifications" helper="Select all that apply">
  <tk-checkbox name="topics" value="product" checked>Product updates</tk-checkbox>
  <tk-checkbox name="topics" value="events">Events and meetups</tk-checkbox>
  <tk-checkbox name="topics" value="research">Research invitations</tk-checkbox>
</tk-checkbox-group>

Anatomy

Part	What it is
`tk-checkbox`	one option and its own form control; one Tab stop
default slot	the label, required; it is the accessible name and can hold a link
box	16px; shows a check or a minus when on
helper	an optional hint under the label
error message	an optional message under the label, on a single checkbox only
`tk-checkbox-group`	the group; adds no Tab stop and submits nothing itself
group label	the legend: the category or the question, required
group helper and error	under the group label, above the options
group default slot	the `tk-checkbox` items, stacked vertically

The whole row, box and label, is one click target.

States

Remember me

Product updates

All files

Security alerts

<tk-checkbox>Remember me</tk-checkbox>
<tk-checkbox checked>Product updates</tk-checkbox>
<tk-checkbox indeterminate>All files</tk-checkbox>
<tk-checkbox disabled checked>Security alerts</tk-checkbox>

On hover, a checked box's fill changes; an unchecked box stays the same. Keyboard focus shows a ring around the box.

checked: the initial state. Clicking toggles it; read the live state from the checked property.
indeterminate: a parent whose children are partly selected. Set it from your code; a click clears it and toggles checked. The select-all logic is yours.
disabled: can't be focused or changed, and isn't submitted. Checked and unchecked disabled boxes differ only by a faint check mark, so if "on and locked" matters, say it in text. Prefer an active checkbox.

Required and error

On a single checkbox, required means it must be checked before the form submits, and adds an asterisk. error shows your message under it and a red border on an unchecked box.

I agree to the Terms of Service

<tk-checkbox name="terms" required error="Agree to the Terms of Service to continue">
  I agree to the <a href="/terms">Terms of Service</a>
</tk-checkbox>

The checkbox doesn't validate. You set error and clear it. In a group, set error on the group, not on the items.

Group

Design

Code

Research

<tk-checkbox-group label="Topics" required error="Select at least one topic">
  <tk-checkbox name="topics" value="design">Design</tk-checkbox>
  <tk-checkbox name="topics" value="code">Code</tk-checkbox>
  <tk-checkbox name="topics" value="research">Research</tk-checkbox>
</tk-checkbox-group>

label is required. label-hidden hides it on screen and keeps it for screen readers.
The group error sits above the options, so it stays in view on a long list. It doesn't color any box.
required only adds the asterisk. Check "at least one" yourself and show the result through error.
disabled disables every checkbox in the group.
Each checkbox submits its own name and value; the group has no value.

When to use

Use a checkbox group to pick zero, one, or several independent options. The choice applies when the form is submitted.
Use a single checkbox for one yes or no in a form, such as agreeing to terms.
Use a Radio group when exactly one answer is valid.
Use a Switch when the change takes effect at once.
Use a Multiselect for a long list or a tight space.
Use a Selection card when each option needs a description, an image, or a price.

Content

Say what's on: a checked box turns the thing on. "Publish store", not "Hide store".
Keep labels short, in sentence case, with no end punctuation.
Write agreements in the first person: "I agree to the Terms of Service".
Make the group label the category or the question, in one sentence.
Keep a helper to one short sentence, with no full stop and no links. Put explanations there, not in a tooltip.
Say what to do in an error, in the label's words: "Select at least one topic". No "please", no "invalid".
Don't pre-check answers to a question. In settings, show the current value.
Let long labels wrap; don't truncate them.

Do / Don't

✅ Do	❌ Don't
Use a radio group when only one answer is valid	Use two checkboxes as an either/or
Write "Publish store"	Write "Hide store", which a check turns into a double negative
Put the error on the group, above the options	Set `error` on items inside a group
Keep options independent	Make one checkbox check or disable another
Set `indeterminate` from code on a parent	Offer it as a third choice to click
Leave questions unchecked	Pre-check an answer for the user

Radio group: pick exactly one option.
Switch: an on/off setting that applies at once.
Selection card: a card around a checkbox, for richer options.
Multiselect: many options in a dropdown.
Field: labels and messages for text inputs; a checkbox doesn't need one.

API

`tk-checkbox` attributes

Attribute	Type	Default	What it does
`checked`	boolean	`false`	initial state; the property is live
`indeterminate`	boolean	`false`	the mixed state of a parent; set from code
`disabled`	boolean	`false`	not focusable, not changeable, left out of the form
`required`	boolean	`false`	single checkbox only: must be checked to submit; adds an asterisk
`error`	string		single checkbox only: your error message
`helper`	string		a hint under the label
`label-hidden`	boolean	`false`	hides the label on screen, keeps the accessible name
`name`	string		the form field name
`value`	string	`on`	submitted while checked; nothing is submitted while unchecked

`tk-checkbox-group` attributes

Attribute	Type	Default	What it does
`label`	string		the group label, required
`label-hidden`	boolean	`false`	hides the group label on screen, keeps the group name
`helper`	string		a hint under the group label
`error`	string		the group error, above the options
`required`	boolean	`false`	adds the asterisk; doesn't validate
`disabled`	boolean	`false`	disables every checkbox in the group

Slots

Element	Slot	Content
`tk-checkbox`	default	the label, required; may contain links
`tk-checkbox-group`	default	`tk-checkbox` items

Events

tk-checkbox fires input and change when the user toggles it, not when your code sets checked. Read the new state from checked. form.reset() restores the initial checked without firing change. The group fires no events.

CSS

tk-checkbox::part(row): the box and label row, the click target.
tk-checkbox::part(box): the native checkbox drawn as the box.
tk-checkbox-group::part(group): the native <fieldset>.

Tokens

State	Box border	Box fill	Mark	Label
unchecked	`border/subtle`	`surface/default`		`text/default`
checked, indeterminate	none	`fill/accent`; hover `fill/accent/hover`	`icon/accent/on-fill`	`text/default`
error, unchecked	`border/error`, 2px	`surface/default`		`text/default`
disabled	`border/disabled`	`surface/disabled`	`icon/disabled`	`text/disabled`

The focus ring is border/accent/focus. Helpers and the asterisk use text/secondary; error messages use text/error with icon/error. The box is 16px with radius-4. Values per theme: Color.

Accessibility

Built in:

A native checkbox inside a <label>: Tab reaches each checkbox, Space toggles it, a click on the label toggles it, and forms see it.
indeterminate is announced as mixed.
The group is a real fieldset, so screen readers announce its label with the options.
Helpers and errors are read with their checkbox or group. Errors start with a hidden "Error:", and a single checkbox with error is marked invalid.
The row is at least 24px tall, and the focus ring is never hidden.

Your part:

Validate "at least one" yourself and show it through the group error. Screen readers don't hear a group as required, so the asterisk and your message carry it.
If you mark fields with asterisks, explain them once per form: "* means required".
With label-hidden, the label still has to name the option, such as "Select row 3".
Keep options in one column. If you use several, check the Tab order.

Key	Action
`Tab`	moves focus to the next checkbox
`Space`	checks or unchecks it

Contrast limits

Unchecked box border: 1.33:1 in light and 2.00:1 in dark, under the 3:1 minimum; 4.22:1 in high contrast. It doesn't change on hover.
Disabled box: checked and unchecked differ only by the check mark, at 1.86:1 in light, 2.91:1 in dark, and 1.91:1 in high contrast. In dark, a disabled box has no visible edge.

Anatomy

States

Required and error

Group

When to use

Content

Do / Don't

Related

API

tk-checkbox attributes

tk-checkbox-group attributes

Slots

Events

CSS

Tokens

Accessibility

Contrast limits

`tk-checkbox` attributes

`tk-checkbox-group` attributes