Checkbox

Basic control to allow selecting one or more items from a set.

Want to skip the docs? Try our MCP Server

#
Documentation

#
Usage

Label


import { Checkbox } from "@optiaxiom/react";
 
export function App() {
  return <Checkbox>Label</Checkbox>;
}

#
Label

The children prop is used as the label of the checkbox control.

Label


import { Checkbox, Group, Separator } from "@optiaxiom/react";
 
export function App() {
  return (
    <Group gap="16">
      <Checkbox>Label</Checkbox>
      <Separator orientation="vertical" />
      <Checkbox />
    </Group>
  );
}

#
Controlled

Use the checked and defaultChecked props to toggle between controlled and uncontrolled usage. And combine it with onCheckedChange to listen for changes to the state.

Label


"use client";
 
import { Button, Checkbox, Group } from "@optiaxiom/react";
import { useState } from "react";
 
export function App() {
  const [value, setValue] = useState(false);
 
  return (
    <Group gap="16">
      <Checkbox checked={value} onCheckedChange={setValue}>
        Label
      </Checkbox>
      <Button disabled={!value} onClick={() => setValue(false)}>
        Reset
      </Button>
    </Group>
  );
}

#
Form integration

Integrate with form libraries like react-hook-form for validation and error handling.


"use client";
 
import { Button, Checkbox, Field, Group, Input } from "@optiaxiom/react";
import { useForm } from "react-hook-form";
 
type FormData = {
  email: string;
  newsletter: boolean;
  terms: boolean;
};
 
export function App() {
  const {
    formState: { errors },
    handleSubmit,
    register,
  } = useForm<FormData>();
 
  return (
    <form
      noValidate
      onSubmit={handleSubmit((data) => {
        console.log(data);
      })}
    >
      <Group flexDirection="column" gap="16">
        <Field error={errors.email?.message} label="Email" required>
          <Input
            placeholder="you@example.com"
            {...register("email", {
              required: "Email is required",
            })}
          />
        </Field>
 
        <Checkbox {...register("newsletter")}>Subscribe to newsletter</Checkbox>
 
        <Field error={errors.terms?.message}>
          <Checkbox
            {...register("terms", {
              required: "You must accept the terms",
            })}
          >
            Accept terms and conditions
          </Checkbox>
        </Field>
 
        <Button alignSelf="start" type="submit">
          Submit
        </Button>
      </Group>
    </form>
  );
}

#
Disabled state

Enable the disabled prop to toggle the disabled state of the checkbox control.

Label


import { Checkbox, Group } from "@optiaxiom/react";
 
export function App() {
  return (
    <Group gap="16">
      <Checkbox defaultChecked disabled>
        Label
      </Checkbox>
      <Checkbox disabled>Label</Checkbox>
    </Group>
  );
}

#
Indeterminate

Enable the indeterminate prop to toggle the indeterminate state of the checkbox control.

Label


import { Checkbox } from "@optiaxiom/react";
 
export function App() {
  return <Checkbox indeterminate>Label</Checkbox>;
}

#
Description

Use the description prop to add helper text after the label.

Label

Helper Text


import { Checkbox } from "@optiaxiom/react";
 
export function App() {
  return <Checkbox description="Helper Text">Label</Checkbox>;
}

#
Common patterns

#
Select all with indeterminate state

Implement a “select all” checkbox that shows indeterminate state when some items are selected.


"use client";
 
import { Checkbox, Group } from "@optiaxiom/react";
import { useState } from "react";
 
const fruits = ["Apple", "Banana", "Orange", "Mango"];
 
export function App() {
  const [selected, setSelected] = useState<string[]>([]);
 
  const allSelected = selected.length === fruits.length;
  const someSelected = selected.length > 0 && !allSelected;
 
  return (
    <Group flexDirection="column" gap="8">
      <Checkbox
        checked={allSelected}
        indeterminate={someSelected}
        onCheckedChange={(checked) => {
          setSelected(checked ? [...fruits] : []);
        }}
      >
        Select All
      </Checkbox>
 
      <Group flexDirection="column" gap="8" pl="24">
        {fruits.map((fruit) => (
          <Checkbox
            checked={selected.includes(fruit)}
            key={fruit}
            onCheckedChange={(checked) => {
              setSelected((prev) =>
                checked
                  ? [...prev, fruit]
                  : prev.filter((item) => item !== fruit),
              );
            }}
          >
            {fruit}
          </Checkbox>
        ))}
      </Group>
    </Group>
  );
}

#
Related

RadioGroup

Basic control to allow selecting only one item from a set.

Switch

Control to allow toggling between checked and not checked state.

#
Props

#
Checkbox

Supports all Box props in addition to its own. Renders a <div> element but forwards all props to a hidden <input> element.

Prop
`asChild` Change the default rendered element for the one passed as a child, merging their props and behavior. Read the Composition guide for more details. `false \| true`
`children` `ReactNode`
`className` `string`
`description` Add secondary text after the label. `ReactNode`
`indeterminate` Display a partially checked icon instead of the regular checkmark. `false \| true`
`name` The name of the form control element. `string`
`onCheckedChange` Handler that is called when the checked state changes. `(checked: boolean) => void`
`required` Whether selecting this input is required. `false \| true`
`value` The value of the form control element. `string \| number \| readonly string[]`

#
Accessibility

#
Keyboard interactions

Key	Description
`Space`	Toggles the checkbox between checked and unchecked
`Tab`	Moves focus to or away from the checkbox
`Shift + Tab`	Moves focus to the previous focusable element

Checkbox automatically handles accessibility:

Uses proper role="checkbox" and ARIA attributes
Supports aria-checked for checked/unchecked/indeterminate states
Associates label text with the checkbox control

#
Changelog

#
0.2.0

Moved indeterminate from checked state to explicit prop

#
0.1.0

Added component