Skip to content
Shaken UI
Sign in

Checkbox

Save

A checkbox with a label, description, indeterminate state, and a check that draws itself, plus a group with a select-all parent.

Category
Forms
Version
0.1.1
Frameworks
Next.js, Vite + React
Styling
Tailwind CSS v4

Preview

Checkbox preview
Email me when

A step errored and the run stopped.

An agent is waiting on a person.

Attaches tool inputs and outputs as a JSON file.

Connect Slack in Integrations first.

Installation

npx @shakenui/cli add checkbox

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add checkbox --dry-run

Usage

checkbox-example.tsx
"use client";

import { useState } from "react";
import { Checkbox, CheckboxGroup } from "@/components/shaken/ui/checkbox";

const events = [
  { value: "run-failed", label: "Run failed", description: "A step errored and the run stopped." },
  { value: "approval-requested", label: "Approval requested", description: "An agent is waiting on a person." },
  { value: "run-finished", label: "Run finished" },
];

export default function CheckboxExample() {
  const [value, setValue] = useState<string[]>(["run-failed", "approval-requested"]);

  return (
    <div className="grid w-full max-w-sm gap-6">
      <CheckboxGroup
        label="Email me when"
        value={value}
        onValueChange={setValue}
        allValues={events.map((event) => event.value)}
      >
        <Checkbox parent label="All run events" />
        <div className="grid gap-3 pl-6.5">
          {events.map((event) => (
            <Checkbox key={event.value} value={event.value} label={event.label} description={event.description} />
          ))}
        </div>
      </CheckboxGroup>
      <Checkbox
        defaultChecked
        label="Include the full trace"
        description="Attaches tool inputs and outputs as a JSON file."
      />
      <Checkbox disabled label="Send to Slack" description="Connect Slack in Integrations first." />
    </div>
  );
}

API

PropTypeDefaultDescription
labelReactNode—Text beside the box. Clicking it toggles the checkbox.
descriptionReactNode—A secondary line under the label, linked with aria-describedby.
checked / defaultCheckedboolean—Controlled or initial state.
onCheckedChange(checked: boolean) => void—Called when the box is ticked or cleared.
indeterminatebooleanfalseShows a dash for a partly selected set.
parentbooleanfalseInside a CheckboxGroup with allValues: becomes a select-all box that goes indeterminate automatically.
valuestring—Identifies the checkbox in a CheckboxGroup's value.
label / description (CheckboxGroup)ReactNode—Names and describes the group with aria-labelledby and aria-describedby.
allValuesstring[]—CheckboxGroup: every child value, needed for a parent checkbox.

Accessibility

  • Base UI renders role="checkbox" with aria-checked ("mixed" when indeterminate) and a hidden native input for forms.
  • The wrapping <label> gives the checkbox its accessible name and makes the text a click target.
  • Space toggles the focused box; the focus ring shows on keyboard focus only.
  • A 32px invisible hit area surrounds the 16px box.
  • The check draws and the dash grows only with motion allowed; under reduced motion they appear in place.

Files

Installed into src/components/shaken, or components/shaken when the project has no src directory.

  • src/components/shaken/ui/checkbox.tsxcheckbox
  • npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required

Source

The exact source the CLI installs, from /r/items/react/checkbox/0.1.1.json.

ui/checkbox.tsxShow
ui/checkbox.tsx
"use client";

import { Checkbox as BaseCheckbox } from "@base-ui/react/checkbox";
import { CheckboxGroup as BaseCheckboxGroup } from "@base-ui/react/checkbox-group";
import { type ReactNode, useId } from "react";

type ClassName<State> = string | ((state: State) => string | undefined) | undefined;

function cx(...classes: (string | false | null | undefined)[]) {
  return classes.filter(Boolean).join(" ");
}

/** Prepends base classes while keeping Base UI's state-function form of className working. */
function withBase<State>(base: string, className: ClassName<State>) {
  return typeof className === "function" ? (state: State) => cx(base, className(state)) : cx(base, className);
}

const box = cx(
  "group/checkbox relative inline-flex size-4 shrink-0 cursor-pointer items-center justify-center rounded-[5px] border outline-none",
  // A larger invisible hit area, so the 16px box is easy to tap on its own.
  "after:absolute after:-inset-2 after:content-['']",
  "border-zinc-950/25 bg-white shadow-[0_1px_1px_rgb(0_0_0/0.04)] hover:border-zinc-950/40",
  "dark:border-white/25 dark:bg-black dark:shadow-none dark:hover:border-white/40",
  "data-[checked]:border-zinc-950 data-[checked]:bg-zinc-950 data-[checked]:text-white",
  "data-[indeterminate]:border-zinc-950 data-[indeterminate]:bg-zinc-950 data-[indeterminate]:text-white",
  "dark:data-[checked]:border-white dark:data-[checked]:bg-white dark:data-[checked]:text-black",
  "dark:data-[indeterminate]:border-white dark:data-[indeterminate]:bg-white dark:data-[indeterminate]:text-black",
  "data-[invalid]:border-red-500 dark:data-[invalid]:border-red-400",
  // Colors ease over 150ms; the press answers in 100ms.
  "transition-[background-color,border-color,color,scale] duration-150 ease-out active:duration-100",
  "motion-safe:active:scale-[0.92] motion-reduce:transition-none",
  "focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-sky-500",
  "data-[disabled]:cursor-not-allowed data-[disabled]:opacity-45 data-[disabled]:active:scale-100",
);

export interface CheckboxProps extends BaseCheckbox.Root.Props {
  /** Text beside the box. Clicking it toggles the checkbox. */
  label?: ReactNode;
  /** A secondary line under the label, linked with `aria-describedby`. */
  description?: ReactNode;
  /** Classes for the wrapper that holds the box, label, and description. `className` styles the box. */
  containerClassName?: string;
}

/**
 * A checkbox with an optional label and description. The check draws itself in 200ms when ticked
 * and retracts faster when cleared; `indeterminate` shows a dash for a partly selected group.
 * Under reduced motion the mark appears without drawing.
 */
export function Checkbox({ label, description, containerClassName, className, "aria-describedby": describedBy, ...props }: CheckboxProps) {
  const descriptionId = useId();
  const root = (
    <BaseCheckbox.Root
      aria-describedby={cx(description != null && descriptionId, describedBy) || undefined}
      className={withBase(box, className)}
      {...props}
    >
      <BaseCheckbox.Indicator keepMounted className="pointer-events-none flex size-full items-center justify-center">
        <svg aria-hidden="true" viewBox="0 0 16 16" fill="none" className="size-3.5">
          <path
            d="M4 8.4l2.6 2.6L12 5.4"
            stroke="currentColor"
            strokeWidth="1.75"
            strokeLinecap="round"
            strokeLinejoin="round"
            pathLength={1}
            className={cx(
              "[stroke-dasharray:1] [stroke-dashoffset:1] opacity-0",
              "transition-[stroke-dashoffset,opacity] duration-100 ease-out motion-reduce:transition-none",
              "group-data-[checked]/checkbox:[stroke-dashoffset:0] group-data-[checked]/checkbox:opacity-100",
              "group-data-[checked]/checkbox:duration-200 group-data-[checked]/checkbox:ease-[cubic-bezier(0.65,0,0.35,1)]",
              "group-data-[indeterminate]/checkbox:opacity-0",
            )}
          />
          <path
            d="M4.5 8h7"
            stroke="currentColor"
            strokeWidth="1.75"
            strokeLinecap="round"
            className={cx(
              "origin-center scale-x-0 opacity-0",
              "transition-[scale,opacity] duration-100 ease-out motion-reduce:transition-none",
              "group-data-[indeterminate]/checkbox:scale-x-100 group-data-[indeterminate]/checkbox:opacity-100",
              "group-data-[indeterminate]/checkbox:duration-200 group-data-[indeterminate]/checkbox:ease-[cubic-bezier(0.22,1,0.36,1)]",
            )}
          />
        </svg>
      </BaseCheckbox.Indicator>
    </BaseCheckbox.Root>
  );

  if (label == null && description == null) return root;

  return (
    <div className={cx("group/field grid grid-cols-[auto_1fr] gap-x-2.5 gap-y-0.5", containerClassName)}>
      <label className="group/label col-span-2 grid cursor-pointer grid-cols-subgrid items-start has-[[data-disabled]]:cursor-not-allowed">
        <span className="flex h-5 items-center">{root}</span>
        <span className="text-sm leading-5 text-zinc-950 select-none group-has-[[data-disabled]]/label:opacity-50 dark:text-white">
          {label}
        </span>
      </label>
      {description != null ? (
        <p
          id={descriptionId}
          className="col-start-2 text-sm leading-5 text-zinc-500 group-has-[[data-disabled]]/field:opacity-50 dark:text-zinc-400"
        >
          {description}
        </p>
      ) : null}
    </div>
  );
}

export interface CheckboxGroupProps extends BaseCheckboxGroup.Props {
  /** Names the group. Linked with `aria-labelledby`. */
  label?: ReactNode;
  /** A sentence under the label about the whole group. */
  description?: ReactNode;
}

/**
 * Shares one value (an array of checkbox `value`s) across the checkboxes inside it. For a
 * "select all" box, pass `allValues` here and `parent` on that Checkbox: it turns indeterminate
 * while only some children are ticked.
 */
export function CheckboxGroup({ label, description, className, children, ...props }: CheckboxGroupProps) {
  const id = useId();
  const labelId = `${id}-label`;
  const descriptionId = `${id}-description`;
  return (
    <BaseCheckboxGroup
      aria-labelledby={label != null ? labelId : undefined}
      aria-describedby={description != null ? descriptionId : undefined}
      className={withBase("grid content-start gap-3", className)}
      {...props}
    >
      {label != null || description != null ? (
        <div className="grid gap-0.5">
          {label != null ? (
            <div id={labelId} className="text-sm leading-5 font-medium text-zinc-950 dark:text-white">
              {label}
            </div>
          ) : null}
          {description != null ? (
            <p id={descriptionId} className="text-sm leading-5 text-zinc-500 dark:text-zinc-400">
              {description}
            </p>
          ) : null}
        </div>
      ) : null}
      {children}
    </BaseCheckboxGroup>
  );
}