Checkbox
For choosing any number of options, or turning one setting on before submitting. The box sits at the inline start, and the label toggles it too.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add checkboxAlso works with shadcn:
npx shadcn@latest add @ritla/checkboxDependencies it brings
@base-ui/react@phosphor-icons/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { Checkbox } from "@/components/ui/checkbox";<Checkbox name="updates" description="About once a month.">Send me product updates</Checkbox>Examples
Values and states
checked and indeterminate (only some children), error, disabled and readOnly. size="lg" is the large touch box with its halo.
API reference
Checkbox
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | None | Figma's Label. A positive statement (“Send me updates”). |
description | ReactNode | None | Figma's Show hint support: a helper line. |
checked / defaultChecked | boolean | None | Figma's Value. |
onCheckedChange | (checked: boolean) => void | None | When it toggles. |
indeterminate | boolean | false | Value = Indeterminate (aria-checked="mixed"). |
error | ReactNode | boolean | None | State = Error: a message replaces the description. |
disabled / readOnly / required | boolean | None | State = Disabled and Read-only. |
size | "sm" | "lg" | "sm" | Small (Web), an 18px box, or Large (Native), a 20px box with a halo in a 48px target. |
name / value / parent | … | None | For forms and CheckboxGroup (parent for “select all”). |
Usage guidelines
A checkbox is an independent option, on or off, saved with the form. When to pick it, how to write its label, how to group boxes, and the checks before handoff.
1. Checkbox or another control
Use a checkbox when each option stands on its own and the choice takes effect on submit. If only one option can be true, or the change should apply at once, another control fits better.
| You need to | Use | Why |
|---|---|---|
| Agree to something, or opt in, before submitting | Checkbox | One independent yes or no, saved with the form. |
| Pick any number from a short list | Checkbox group | Every option visible, each on or off. |
| Pick several options that need a description or price | Checkbox card | The whole card is the target, with room for details. |
| Pick exactly one option | Radio group | Radios show that the options exclude each other. |
| Turn a setting on or off right away | Switch | A switch applies immediately, with no Save. |
| Filter a list instantly | Filter chips | Chips apply as they are pressed. |
2. Write the label
The label is a positive statement that is true when the box is checked: “Email me the monthly statement”. The whole label toggles the box, not only the box. Consent and marketing boxes always start unchecked, so the person decides.
Say it positively, let people opt in
A marketing opt-in at sign-up.
Do
- Write what checking the box means: Email me offers.
- Keep the label to one line; put details in the helper text.
- Start consent and marketing boxes unchecked.
- Link long terms from the label: “I agree to the terms”.
Don't
- Write negatives: “Don't email me offers”.
- Preselect consent to marketing or data sharing.
- Put a question in the label (“Receive emails?”).
3. Groups and select all
Put related checkboxes under one label in a Checkbox group (a fieldset with a legend in code). Order them logically and keep them to about ten. A “select all” parent turns Indeterminate when only some children are checked.
A labeled, stacked group
Notification preferences.
Do
- Give the group a label that says what the options are.
- Stack options vertically, one per line.
- Use a select-all parent for long lists; code sets Indeterminate for you.
- Put the group's error or hint under the whole group.
Don't
- Put checkboxes side by side in a row; they are hard to scan.
- Use more than about ten options; use a Multi select.
- Show Indeterminate on a box that has no children.
4. Checkbox cards
A Checkbox card is a list row or card chosen with a checkbox, for options that need more than a label: a description, a price, an icon or an avatar. The whole card is the label. The checkbox sits at the inline end, or at the start with Leading type = Checkbox.
Do
- Use cards when options differ by details people need to compare.
- Keep the headline short and put the details in the supporting text.
- Show a price or quantity as trailing text.
Don't
- Nest buttons or links inside a checkbox card.
- Mix checkbox cards and plain checkboxes in one group.
5. Errors and required boxes
When a box must be checked to continue, such as accepting the terms, say so in the error message on submit, under the box. A group in Error shows every box in error and one message for the group.
Say what is needed
The terms checkbox after a failed submit.
Do
- Say what to do: “Accept the terms to continue”.
- Show the error on submit, not while people are still reading.
Don't
- Show the error state with no message.
- Disable the submit button until the box is checked, with no explanation.
6. Arabic and RTL
On Arabic screens use the RTL variant: the box sits at the inline start (the right) and the label runs to the left of it. The check mark and the Indeterminate dash never mirror. Write labels natively and positively in Arabic too.
The box sits at the inline start
An opt-in in an Arabic form.
Before handoff
- Checkboxes only for choices applied on submit.
- Labels are positive; consent starts unchecked.
- Groups have a label and at most about ten options.
- Required boxes have an error message.
- Arabic screens use the RTL variant.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| Space | Toggles the box. |
ARIA
role="checkbox"witharia-checked(true, false, mixed), named by its text and linked to its description.- The whole row is a
<label>: clicking the text toggles it, and the touch target is at least 48px. - An error sets
aria-invalidand shows why.
Do
- The label next to the box and clickable: the whole row is the target.
- Space toggles, Tab moves.
- Indeterminate is announced as mixed (
aria-checked="mixed", set by code). - A 48 px target on touch screens (the
lgsize in apps).
Don't
- Hide the label and rely on nearby text.
- A checkbox that runs an action immediately.
Arabic and RTL notes
Mirrors
- The box sits at the inline start (the right), the text after it.
Does not mirror
- The check and the dash never mirror.
- Numerals
- No numbers in the box.
- Arabic typography
- Text is
label-16Medium, the descriptionlabel-12; Arabic lines are taller and the box stays on the first line.
Do
- The RTL variant, with the box on the right.
- Keep the check mark as it is; it is not directional.
Don't
- Arabic in the English variant.
- Flip the check mark.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space