User Interface (UI)

Let's start with how a checkbox looks: its parts, its sizes and how it shows each of its states.

Anatomy

Every checkbox has a container, a box, an indicator and a hit area. The label is optional only for a checkbox that its context already names, like one in each row of a table, which takes an aria-label instead (see Label every checkbox). Any hint and error message sit outside the container, in the page, and point to the box by its id. The parts always render in the same order, which you can see in the DOM contract.

Sizes

The size prop scales the box, the text and the gap between them together, and md is the default. The names are the same as the Button's and the Input's, and so is the text, so a checkbox reads at the same size as the inputs and buttons next to it.

<Checkbox size="xs">Email me updates</Checkbox>
{/* …sm, md, lg, xl */}

Sizes are set in rem, and the table shows the values we recommend at the default text size of 16px. The box grows with the text, a little larger than its letters, so it lines up with the first line of its label at every size. Whatever its size, the box sits in a hit area of at least 24 × 24px (WCAG 2.5.8), which is part of the <label>, so a press anywhere in it toggles the box. Each checkbox is at least as tall as its hit area, so two stacked checkboxes never share one.

States

Each state has a look of its own, styled from the <input> itself. That way, what people see and what assistive technologies report can never drift apart, and a box can't look checked without actually being checked.

<Checkbox>Email me updates</Checkbox>
<Checkbox defaultChecked>Email me updates</Checkbox>
<Checkbox indeterminate>Select all</Checkbox>

<Checkbox disabled>Text me updates</Checkbox>
<Checkbox defaultChecked disabled>Email me updates</Checkbox>

<Checkbox readOnly>Text me updates</Checkbox>
<Checkbox defaultChecked readOnly>Email me updates</Checkbox>

<Checkbox required aria-invalid="true" aria-describedby="terms-error">I agree to the terms</Checkbox>
<p id="terms-error">Agree to the terms to create an account</p>

The checked and indeterminate looks share their fill, and tell themselves apart by their mark, a check or a dash, rather than by colour (WCAG 1.4.1). The read-only look is dashed, like a read-only Input's, and drops the fill, so a checked box still shows its check without looking like one you can change. The disabled look comes from :disabled, which also matches every checkbox inside a <fieldset disabled>, so a whole group looks the way it behaves. We recommend leaving :invalid out of it, as on the Input, since it matches an unchecked required box before anyone has touched it. The invalid look comes from aria-invalid instead, which you set when the error message shows.

None of the states change the checkbox's size or position. The invalid border's second pixel is drawn inside the box, and the focus ring outside it. You'll find how each state behaves under Every state.

Tokens

The checkbox reads five theme tokens, which every component shares:

The border is the text colour at 55%, and 80% on hover. An unchecked box is nothing but its border, so the border needs 3:1 against the page, and so does the fill of a checked box, while the check needs 3:1 against the fill (WCAG 1.4.11). With our reference tokens, from the Tailwind CSS palette, the border comes to 3.5:1, the fill to 6.4:1 and the check to 6.4:1 on white, and 5.0:1, 5.7:1 and 6.4:1 on zinc-900. If you change the tokens, make sure to check the same pairs. You'll find the tokens themselves in the Button's tokens.css, which you can copy into your theme.

If you need to tune a checkbox, you can set its own variables, such as --checkbox--box--radius, --checkbox--box--fill or --checkbox--indicator--color, from a class. The Checkbox's styles sit in the components cascade layer, so your class wins without any specificity tricks:

import styles from "./Terms.module.css";

export function Terms() {
  return <Checkbox name="terms" className={styles.square}>I agree to the terms</Checkbox>;
}

.square {
  --checkbox--box--radius: 0;
}

UI Checklist

FAQ