Skip to content

Checkbox

Get Ritla UI

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

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add checkbox

    Also works with shadcn: npx shadcn@latest add @ritla/checkbox

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/react

  3. Or 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

checkbox.tsx
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.

EnglishMirroredArabic
LTR →

API reference

Checkbox

PropTypeDefaultDescription
childrenReactNodeNoneFigma's Label. A positive statement (“Send me updates”).
descriptionReactNodeNoneFigma's Show hint support: a helper line.
checked / defaultCheckedbooleanNoneFigma's Value.
onCheckedChange(checked: boolean) => voidNoneWhen it toggles.
indeterminatebooleanfalseValue = Indeterminate (aria-checked="mixed").
errorReactNode | booleanNoneState = Error: a message replaces the description.
disabled / readOnly / requiredbooleanNoneState = 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…NoneFor 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 toUseWhy
Agree to something, or opt in, before submittingCheckboxOne independent yes or no, saved with the form.
Pick any number from a short listCheckbox groupEvery option visible, each on or off.
Pick several options that need a description or priceCheckbox cardThe whole card is the target, with room for details.
Pick exactly one optionRadio groupRadios show that the options exclude each other.
Turn a setting on or off right awaySwitchA switch applies immediately, with no Save.
Filter a list instantlyFilter chipsChips 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: Positive, uncheckedPeople check the box if they want offers; the meaning is plain.
Don't: Negative, checkedUnchecking “don't email me” to get emails is a double negative, and the box was decided for them.

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: Group with a labelOne label names the set; each option stands on its own.
Don't: Loose checkboxesWithout a group label, it isn't clear what the options are about.

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: Error with a messageThe message says exactly what is missing.
Don't: Error state onlyA red box alone doesn't say why the form was stopped.

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.

Do: RTL variantThe box is on the right, where the Arabic line starts.
Don't: English variant with Arabic textThe box ends up after the text, on the left.

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.

KeyAction
SpaceToggles the box.

ARIA

  • role="checkbox" with aria-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-invalid and 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 lg size 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-16 Medium, the description label-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.

  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space