Checkbox

A control that allows the user to toggle between checked and not checked.

Accept terms and conditions

By clicking this checkbox, you agree to the terms.

Enable notifications

You can enable or disable notifications at any time.

1
"use client";
2

3
import { Checkbox } from "@/components/ui/pxl/checkbox";
4
import {
5
  Field,
6
  FieldContent,
7
  FieldDescription,
8
  FieldGroup,
9
  FieldLabel,
10
  FieldTitle,
11
} from "@/components/ui/pxl/field";
12
import { Label } from "@/components/ui/pxl/label";
13

14
export default function CheckboxDemo() {
15
  return (
16
    <FieldGroup className="max-w-sm">
17
      <Field orientation="horizontal">
18
        <Checkbox id="terms-checkbox" name="terms-checkbox" />
19
        <Label htmlFor="terms-checkbox">Accept terms and conditions</Label>
20
      </Field>
21
      <Field orientation="horizontal">
22
        <Checkbox
23
          id="terms-checkbox-2"
24
          name="terms-checkbox-2"
25
          defaultChecked
26
        />
27
        <FieldContent>
28
          <FieldLabel htmlFor="terms-checkbox-2">
29
            Accept terms and conditions
30
          </FieldLabel>
31
          <FieldDescription>
32
            By clicking this checkbox, you agree to the terms.
33
          </FieldDescription>
34
        </FieldContent>
35
      </Field>
36
      <Field orientation="horizontal" data-disabled>
37
        <Checkbox id="toggle-checkbox" name="toggle-checkbox" disabled />
38
        <FieldLabel htmlFor="toggle-checkbox">Enable notifications</FieldLabel>
39
      </Field>
40
      <FieldLabel>
41
        <Field orientation="horizontal">
42
          <Checkbox id="toggle-checkbox-2" name="toggle-checkbox-2" />
43
          <FieldContent>
44
            <FieldTitle>Enable notifications</FieldTitle>
45
            <FieldDescription>
46
              You can enable or disable notifications at any time.
47
            </FieldDescription>
48
          </FieldContent>
49
        </Field>
50
      </FieldLabel>
51
    </FieldGroup>
52
  );
53
}

Installation

Command
Manual

pnpm dlx shadcn@latest add pxl-ui/registry/checkbox

Install the following dependencies:

pnpm add @base-ui/react

Copy and paste the following code into your project.

1
"use client";
2

3
import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox";
4

5
import { cn } from "@/lib/utils";
6

7
function Checkbox({ className, ...props }: CheckboxPrimitive.Root.Props) {
8
  return (
9
    <CheckboxPrimitive.Root
10
      data-slot="checkbox"
11
      className={cn(
12
        "peer flex size-4 shrink-0 items-center justify-center pixel-rounded pixel-border pixel-size-md pixel-color-border shadow-xs transition-shadow outline-none group-has-disabled/field:opacity-50 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:pixel-color-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:pixel-color-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:pixel-color-foreground dark:bg-input/30 dark:aria-invalid:pixel-color-[color-mix(in_oklab,var(--destructive)_50%,transparent)] dark:aria-invalid:ring-destructive/40 data-checked:pixel-color-foreground data-checked:bg-foreground data-checked:text-background dark:data-checked:bg-foreground",
13
        className,
14
      )}
15
      {...props}
16
    >
17
      <CheckboxPrimitive.Indicator
18
        data-slot="checkbox-indicator"
19
        className="grid place-content-center text-current transition-none [&>svg]:size-3.5"
20
      >
21
        <svg
22
          xmlns="http://www.w3.org/2000/svg"
23
          fill="currentColor"
24
          viewBox="0 0 24 24"
25
        >
26
          <path d="M10 18H8v-2h2v2Zm-2-2H6v-2h2v2Zm4-2v2h-2v-2h2Zm-6 0H4v-2h2v2Zm8 0h-2v-2h2v2Zm2-2h-2v-2h2v2Zm2-2h-2V8h2v2Zm2-2h-2V6h2v2Z" />
27
        </svg>
28
      </CheckboxPrimitive.Indicator>
29
    </CheckboxPrimitive.Root>
30
  );
31
}
32

33
export { Checkbox };

Update the import paths to match your project setup.

Usage

import { Checkbox } from "@/components/ui/pxl/checkbox"

<Checkbox />

Checked State

Use defaultChecked for uncontrolled checkboxes, or checked and onCheckedChange to control the state.

1
import { useState } from "react"
2

3
export function Example() {
4
  const [checked, setChecked] = useState(false)
5

6
  return <Checkbox checked={checked} onCheckedChange={setChecked} />
7
}

Invalid State

Set aria-invalid on the checkbox and data-invalid on the field wrapper to show the invalid styles.

Basic

Pair the checkbox with Field and FieldLabel for proper layout and labeling.

Description

Use FieldContent and FieldDescription for helper text.

Disabled

Use the disabled prop to prevent interaction and add the data-disabled attribute to the <Field> component for disabled styles.

Group

Use multiple fields to create a checkbox list.

API Reference

See the Base UI documentation for more information.