Checkbox

A toggle for a single boolean value. Built on base-ui Checkbox — focus management, keyboard support, and ARIA wiring come for free.

Checkbox renders only the box. Give it an id and pair it with a FieldLabel (inside a Field) or a Label so the label text is clickable and the control is announced. See Field for the layout primitives.

With a label

Wrap the box and its label in a Field orientation="horizontal", and connect them with id / htmlFor. Clicking the label toggles the box.

Residential delivery address

import { Checkbox, Field, FieldLabel } from "@vesyl/ui-next";

export default function CheckboxBasic() {
  return (
    <Field orientation="horizontal">
      <Checkbox id="residential" />
      <FieldLabel htmlFor="residential">Residential delivery address</FieldLabel>
    </Field>
  );
}

Checked by default

Checkbox is uncontrolled by default — pass defaultChecked to start it on. To drive the value yourself, pass checked together with onCheckedChange (which receives the next boolean directly).

Require signature on delivery

Allow Saturday delivery

import { Checkbox, Field, FieldLabel, VStack } from "@vesyl/ui-next";

export default function CheckboxDefaultChecked() {
  return (
    <VStack gap={3}>
      <Field orientation="horizontal">
        <Checkbox id="signature" defaultChecked />
        <FieldLabel htmlFor="signature">Require signature on delivery</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Checkbox id="saturday" />
        <FieldLabel htmlFor="saturday">Allow Saturday delivery</FieldLabel>
      </Field>
    </VStack>
  );
}

Disabled

disabled dims the control and blocks interaction. It works with both the unchecked and checked states.

Add insurance (unavailable for this carrier)

Ground shipping only

import { Checkbox, Field, FieldLabel, VStack } from "@vesyl/ui-next";

export default function CheckboxDisabled() {
  return (
    <VStack gap={3}>
      <Field orientation="horizontal">
        <Checkbox id="insurance" disabled />
        <FieldLabel htmlFor="insurance">Add insurance (unavailable for this carrier)</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Checkbox id="ground-only" defaultChecked disabled />
        <FieldLabel htmlFor="ground-only">Ground shipping only</FieldLabel>
      </Field>
    </VStack>
  );
}

Indeterminate

indeterminate renders a minus glyph instead of a check — the third “partially selected” state used for a parent that controls a group. It is purely visual; track the real value yourself and clear it once the user commits a choice.

import { useState } from "react";
import { Checkbox, Field, FieldLabel, VStack } from "@vesyl/ui-next";

const carriers = ["UPS", "FedEx", "USPS", "DHL"];

export default function CheckboxIndeterminate() {
  const [selected, setSelected] = useState<string[]>(["UPS", "USPS"]);

  const allChecked = selected.length === carriers.length;
  const someChecked = selected.length > 0 && !allChecked;

  function toggle(carrier: string, checked: boolean) {
    setSelected((prev) =>
      checked ? [...prev, carrier] : prev.filter((c) => c !== carrier),
    );
  }

  return (
    <VStack gap={3} className="w-full max-w-xs">
      <Field orientation="horizontal">
        <Checkbox
          id="carriers-all"
          checked={allChecked}
          indeterminate={someChecked}
          onCheckedChange={(checked) =>
            setSelected(checked ? [...carriers] : [])
          }
        />
        <FieldLabel htmlFor="carriers-all">All carriers</FieldLabel>
      </Field>
      <VStack gap={2} className="pl-6">
        {carriers.map((carrier) => {
          const id = `carrier-${carrier}`;
          return (
            <Field key={carrier} orientation="horizontal">
              <Checkbox
                id={id}
                checked={selected.includes(carrier)}
                onCheckedChange={(checked) => toggle(carrier, checked === true)}
              />
              <FieldLabel htmlFor={id}>{carrier}</FieldLabel>
            </Field>
          );
        })}
      </VStack>
    </VStack>
  );
}

Group / list

For a list of options, render one Checkbox per item and keep the selection in state. Wrapping each row in a Label makes the whole row a click target; data-checked lets you highlight the selected rows.

Shipment deliveredDelivery exceptionLabel purchasedWallet balance low

import { useState } from "react";
import { Checkbox, Label, VStack } from "@vesyl/ui-next";

const notifications = [
  { id: "shipment-delivered", label: "Shipment delivered" },
  { id: "shipment-exception", label: "Delivery exception" },
  { id: "label-purchased", label: "Label purchased" },
  { id: "low-balance", label: "Wallet balance low" },
];

export default function CheckboxGroup() {
  const [selected, setSelected] = useState<string[]>([
    "shipment-exception",
    "low-balance",
  ]);

  function toggle(id: string, checked: boolean) {
    setSelected((prev) =>
      checked ? [...prev, id] : prev.filter((n) => n !== id),
    );
  }

  return (
    <VStack gap={1} className="w-full max-w-sm">
      {notifications.map((notification) => (
        <Label
          key={notification.id}
          htmlFor={notification.id}
          data-checked={selected.includes(notification.id) ? "" : undefined}
          className="hover:bg-muted data-[checked]:bg-muted flex cursor-pointer items-center gap-3 rounded-lg px-3 py-2"
        >
          <Checkbox
            id={notification.id}
            checked={selected.includes(notification.id)}
            onCheckedChange={(checked) =>
              toggle(notification.id, checked === true)
            }
          />
          {notification.label}
        </Label>
      ))}
    </VStack>
  );
}

Reference

Checkbox

Extends base-ui Checkbox.Root props (minus onChange).

Prop	Type	Default	Description
`checked`	`boolean`	—	Controlled checked state
`defaultChecked`	`boolean`	`false`	Initial checked state (uncontrolled)
`onCheckedChange`	`(checked: boolean) => void`	—	Fires when the state changes; receives the next boolean directly
`indeterminate`	`boolean`	`false`	Renders the partial-selection (minus) glyph; visual only
`disabled`	`boolean`	`false`	Dims the control and blocks interaction
`id`	`string`	—	Connects the box to a `FieldLabel` / `Label` via `htmlFor`
`name`	`string`	—	Field name when submitted as part of a native form
`value`	`string`	—	Submitted value when checked
`required`	`boolean`	`false`	Marks the field as required in a form
`className`	`string`	—	Merged onto the box