A checkbox lets the user turn one or more options on or off, independently of each other. The choice is saved when the form is submitted.
Every example on this page is the real component, not a picture. Click, tab and press Space to try it. Figma: Checkbox.
Choose a mode, value and state and the checkbox and its code update. Light mode is the default. Use dark mode only on a dark surface (surface-100 or surface-80). The checkbox in the stage is live: click it to change its value.
A checkbox lets the user turn one or more options on or off, independently of each other. The choice is saved when the form is submitted.
Checkbox has two sizes (Large, Small), a light and a dark mode, an Inline menu type for table headers, a read-only check icon for tables, and tiles (color swatch, image, number) for product pages and filtering.
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use a checkbox. Specifications holds the values: tokens, sizes, measurements, states and requirements. Code shows how to add a checkbox to a page.
Use a checkbox when the user picks any number of options, or confirms one option, and the choice is saved when the form is submitted. Use it to:
Checkbox, radio and switch look alike but do different jobs. Use checkboxes when several options can be chosen. When exactly one of two or more options can be chosen, use eco-radio.
A checkbox is saved when the form is submitted. For a setting that turns on or off with immediate effect, use eco-switch.
Related checkboxes go in a fieldset with a legend, so a screen reader reads the question with each option.
The mixed state says that some, but not all, of the children are selected. A checkbox with no children is either checked or not.
| The user… | Use |
|---|---|
| picks any number of options, saved on submit | Checkbox |
| picks exactly one of two or more options | eco-radio |
| turns a setting on or off, with immediate effect | eco-switch |
fieldset with a legend..form-checkbox-item--dark on dark surfaces.body-md. 8px from the box. A checkbox without a label needs an aria-label.The box followed by a 24×24px dropdown arrow, with no label. Dimensions are under Sizes in Specifications.
Two modes (light, dark) and two types (standard, inline menu), plus the read-only check icon for tables. Choose the mode to see every variant on a light or a dark surface. Tiles have their own section below. Figma also has a Breakpoint property, which only changes the Large label size: use the Breakpoint toggle to preview it.
A visible label is the default. A checkbox without a label needs an aria-label, and is only for dense cases such as table rows.
A parent checkbox shows the mixed state when only some children are selected. Click the parent to select or clear all. This is the only case where the mixed state is used.
A checkbox with a dropdown arrow, for example a table header where the checkbox selects all rows and the arrow opens a menu (class .form-checkbox-item--menu markup below). It has no label, so it needs an aria-label. States: enabled, hover, focus and disabled, each unchecked, checked or mixed. The menu itself is not part of this component.
Read-only, to show whether a role has a permission. Always disabled, light mode only (class .check-icon on the cell).
| Permission | Standard | Administrator |
|---|---|---|
| View orders | ||
| Manage users |
Checkbox tiles are used first and foremost on product pages (PDP) and in filtering, where the choice is a picture or a color instead of a text label. They are native checkboxes, so several can be chosen. Three kinds: Color swatch, Image and Number (the “+10” tile that shows how many more there are). They have no label, so each needs an aria-label. Figma: Color swatch and Image and Number.
A 24×24px tile with a 16px square of the product color. The same size on desktop and mobile. The color is the product’s own, set with the --swatch variable. In filtering several colors can be chosen, so these are checkboxes.
The same tiles as a compact grid, all 26 product colors:
The swatch shows the product color, including the glossy gradients and finishes (gold, mirror lens, semi shiny, transparent, pattern). The library below has all 26 product colors from Figma, each with its name in alt-label-lg style (Medium, uppercase, text-tertiary) and a 16px swatch. In the real filter the hex value comes from the product data.
The product picture inside a 48px tile (40px on mobile), with 6px around the image. On a product page (PDP) only one can be chosen at a time, so the tiles are radio inputs with the same tile styling (use checkboxes only when several can be chosen, as in filtering). The Number tile (“+10”) has the same size and sits last in the row. States of every tile are under States in Specifications.
A checkbox has two sizes. Large is the default. Small (class .form-checkbox-item--sm) is for dense layouts such as tables and filters. Measurements are under Sizes in Specifications.
Related options go in a fieldset with a legend. Stack them in a column, or wrap them in a row when the labels are short.
A checkbox is a 16px box with a 1px grey border that fills black when selected. Use the light version on light surfaces and the dark version (.form-checkbox-item--dark) on dark ones: surface-100 or surface-80. Never mix them. The label is 16/22 on mobile and 17/24 from 769px. Token names and values are under Design Tokens in Specifications.
A click on the box or the label toggles the checkbox. Clearing the mixed state also makes it checked. Space toggles the focused checkbox.
Hover changes the fill and the border color. The focus ring (2px line, 2px offset) shows with :focus-visible only, so a mouse click does not draw it. The 4px margin around the box leaves room for it. All states are listed under States in Specifications.
The mixed state belongs to a “select all” parent. It shows when only some of the children are selected, and is set with input.indeterminate = true in JavaScript: it cannot be set in HTML.
A disabled checkbox cannot be focused and has no hover. The label turns text-disabled through :has(input:disabled).
A checkbox is a native <input type="checkbox">, so the browser and the screen reader do most of the work. All requirements are listed under Accessibility Requirements in Specifications.
Tab and Shift+Tab move between checkboxes. Space toggles the focused one. The focus ring shows with :focus-visible.
Every checkbox needs a name: a visible label in the label element, or an aria-label when there is none (Inline menu, tiles, table rows). Group related checkboxes in a fieldset with a legend. Never build the box from an image or an SVG file.