Checkbox

A native checkbox for selecting one or more options.

Overview

Checkbox renders a native checkbox. Use it when a person can select any number of independent options, including none. It participates in a form through name and value. It does not store form state or validate the field.

Preview

Customize

Checked
Disabled
Indeterminate

Installation

Add the component with the CLI. It copies the files in and installs anything they depend on.

npx vinyaas add checkbox

Usage

import { Checkbox } from "@/components/ui/checkbox";
import { Label } from "@/components/ui/label";

export function TermsField() {
  return (
    <div className="flex items-center gap-2">
      <Checkbox id="terms" name="terms" value="accepted" />
      <Label htmlFor="terms">Accept terms and conditions</Label>
    </div>
  );
}

Examples

With a label

htmlFor matches the checkbox id. The label names the control.

Checked

defaultChecked starts the box selected.

Disabled

A disabled checkbox cannot be toggled.

Indeterminate

Use indeterminate when a parent checkbox represents a partial selection.

In practice

Independent notification channels use checkboxes. Save writes the selection.

Choose which workspace email you want to receive.

Release notes and occasional announcements.

Invoices, receipts, and payment failures.

Sign-ins, password changes, and 2FA events.

Tips, webinars, and partner offers.

API

Other attributes for the underlying element are passed through.

NameTypeDefaultDescription
checkedboolean—Controlled checked state. Pair it with onChange.
defaultCheckedboolean—Uncontrolled initial checked state.
disabledboolean—Native disabled state. The control stays in the tab order.
requiredboolean—Native required state for the surrounding form.
namestring—Submitted with the form when the box is checked.
valuestring—Submitted value. The default is on.
indeterminateboolean—Mixed state, such as a parent of partially selected items.
classNamestring—Merged onto the checkbox with cn.

Accessibility

Checkbox is a native checkbox. It does not add an ARIA role.

  • Name it with a label whose htmlFor matches the checkbox id.
  • Space toggles it when it has focus.
  • disabled blocks toggling. The control stays in the accessibility tree.
  • Focus uses a visible focus-visible ring.
  • aria-invalid and other ARIA attributes are passed through. indeterminate is the native mixed state.