Checkbox

Installation

npx gbs-add-block@latest -a Checkbox -beta

The block copies the checkbox folder into your project, along with the small shared folder that every component imports. You own the code and can change it freely. There are no peer dependencies other than React.

Requirements

• React 19 and @types/react 19
• TypeScript target ES2022 or newer, with "jsx": "react-jsx"
• Browsers from 2024 or newer (the styles use light-dark(), color-mix() and :indeterminate)

Import the stylesheet once, for example in your global CSS:

@import "../components/checkbox/styles.css";

or in your root layout / entry file:

import "@/components/checkbox/styles.css";

Checkbox is a single on/off choice with a label, hint and error, including a partly checked state. CheckboxGroup is a labelled set of checkboxes sharing one array of values, with an optional "select all" box. The box is the browser's own <input type="checkbox">, restyled. Forms post it, form libraries register it, and screen readers announce it exactly as a native checkbox, including "mixed".

Checkbox

CheckboxGroup

Quick Start

"use client";
 
import { useState } from "react";
import { Checkbox, CheckboxGroup } from "@/components/checkbox";
 
export default function Preferences() {
  const [terms, setTerms] = useState(false);
  const [channels, setChannels] = useState<string[]>(["email"]);
 
  return (
    <>
      <Checkbox label="I accept the terms" checked={terms} onCheckedChange={setTerms} required />
 
      <CheckboxGroup
        label="Notify me by"
        name="channels"
        options={[
          { value: "email", label: "Email" },
          { value: "sms", label: "SMS", description: "Urgent alerts only" },
          { value: "push", label: "Push" },
        ]}
        value={channels}
        onValueChange={setChannels}
        selectAll
      />
    </>
  );
}

Both are controlled (checked / value) or uncontrolled (defaultChecked / defaultValue).

Props Table

Checkbox

Accepts every <input> attribute except type, plus:

CheckboxGroup

Indeterminate State

<Checkbox label="Select all rows" checked={someSelected ? "indeterminate" : allSelected} onCheckedChange={toggleAll} />

"indeterminate" shows a dash and is announced as "mixed". It is a display state only: clicking the box makes it checked, and onCheckedChange receives true.

Groups

With options, which supports select-all:

<CheckboxGroup label="Permissions" options={permissions} value={granted} onValueChange={setGranted} selectAll />

• Select all: shows checked, unchecked or mixed. Clicking it selects every enabled option, or clears them when all are already selected.
• Disabled options: they keep their state either way.

With children, for custom layouts:

<CheckboxGroup label="Size" orientation="horizontal" defaultValue={["md"]}>
  <Checkbox value="sm" label="Small" />
  <Checkbox value="md" label="Medium" />
  <Checkbox value="lg" label="Large" />
</CheckboxGroup>

Any Checkbox with a value inside a group reads and updates the group's array, at any depth.

Forms

<form action={savePreferences}>
  <Checkbox name="newsletter" value="yes" label="Send me the newsletter" />
  <CheckboxGroup name="channels" options={channels} />
  <button type="submit">Save</button>
</form>

On the server, formData.get("newsletter") is "yes" when checked, and formData.getAll("channels") lists the checked values. Unchecked boxes post nothing, as native checkboxes do.

With react-hook-form, register a single checkbox like a native one:

<Checkbox label="Remember me" {...register("remember")} />

Keyboard

Accessibility: every box is a native checkbox with a real <label>. A group is a <fieldset> with a <legend>, so screen readers announce the group name when entering it. Descriptions and errors are linked through aria-describedby, and errors are announced with role="alert". The mixed state comes from the native indeterminate property.

Styling and Theming

All rules are in the CSS components layer, so utility classes passed through className / classNames override them.

<Checkbox classNames={{ input: "rounded-full", label: "font-medium" }} />

CSS variables

Override them on .ck-root, .ck-group, :root, or through style. Each variable falls back to the shared --gbs-* of the same name, then to the DataGrid's --dg-* when that stylesheet is loaded, and finally to the built-in palette.

Data attributes

Locale Text

<CheckboxGroup localeText={{ selectAll: "Alle auswählen" }} />

Headless Use

Next.js

Both are client components with "use client" at the top of their files. They render the same markup on the server and the client. A controlled indeterminate state is applied right after hydration, because it exists only as a DOM property.

Migrating from the Previous Check Box

Notes

• A checkbox inside a CheckboxGroup without a value is independent of the group, which is how the select-all box works.
• required on a single Checkbox uses the browser's validation: the form won't submit until it's checked.