Checkbox

Overview

Use a checkbox when the user can turn an independent option on or off.

Checkboxes are right for preferences, permissions, optional settings, and multi-select lists. Use a radio group when the user must choose exactly one option from a set.

Use Checkbox Group when several checkboxes belong to the same question or setting. Groups are useful for permissions, filters, notification channels, roles, and feature selections where more than one option can be selected.

Anatomy

A checkbox has an input, visual indicator, label, optional description, and state. The label should make sense when read on its own.

A checkbox group provides shared state and contains individual checkbox items. It should have a group label or surrounding Fieldset so users understand what the choices are about.

Behavior

A checkbox can be checked, unchecked, disabled, or invalid. Some grouped checkbox patterns also use an indeterminate parent state to show that only some child items are selected.

Use disabled items for options that are visible but unavailable. Use parent checkboxes when a group needs select-all behavior. Use nested parent checkboxes when choices are hierarchical.

Accessibility

Always connect the checkbox to a label. Descriptions and errors should be associated through Field when the checkbox appears in a form.

Group related checkboxes with a visible label. Make sure each checkbox has its own label and that parent states are understandable through text, not only the visual indeterminate mark.

Installation

npx love-ui@latest add checkbox

Usage

import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox"

<Checkbox />

<CheckboxGroup defaultValue={["next"]}>
  <Label>
    <Checkbox value="next" />
    Next.js
  </Label>
  <Label>
    <Checkbox value="vite" />
    Vite
  </Label>
  <Label>
    <Checkbox value="astro" />
    Astro
  </Label>
</CheckboxGroup>

Examples

The examples show disabled, described, card-style, and form-connected checkboxes.

For accessible labelling and validation, prefer using the Field component to wrap checkboxes. See the related example: Checkbox field.

Disabled

With Description

Card Style

Form Integration

Field provides accessible labelling and validation primitives for form controls. Use it with Form to submit values.

Checkbox Group

Checkbox Group is included in the same component file. Use it when several checkboxes answer the same question or share one submitted value.

For accessible group labelling and validation, prefer wrapping checkbox groups with Field and Fieldset. See the related example: Checkbox group field.

Basic Group

With Disabled Item

Parent Checkbox

Nested Parent Checkbox

Group Form Integration