Checkbox

A single item that can be ticked. Use it for a boolean submitted with a form, or for a list where several items can be chosen at once.

import { Checkbox } from 'neba';

<Checkbox label="Remember me" defaultChecked />;

Props

Prop	Type	Default	Description
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Height and type scale
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
label	ReactNode	—	The label, wired to the control by Base UI's Field
description	ReactNode	—	Helper text
error	ReactNode	—	Error message. Its presence turns the control invalid and re-points the colour family at danger
invalid	boolean	!!error	Forces the invalid state without a message, for when a form library owns validity
checked	boolean	—	Whether it is ticked. Use with onCheckedChange for a controlled checkbox
defaultChecked	boolean	false	The initial state, for an uncontrolled checkbox
onCheckedChange	(checked: boolean, details) => void	—	Called when the checkbox is ticked or unticked
indeterminate	boolean	false	Neither ticked nor unticked: a parent whose children disagree
required	boolean	false	Must be ticked before the form submits
name	string	—	Identifies the field when a form is submitted
readOnly	boolean	false	Shown but not changeable. Keeps its colour and edge, drains the saturation
disabled	boolean	false	Unavailable. Drops the colour family for neutral grey
classNames	NebaSlots<'label' | 'control' | 'description' | 'error' | 'indicator'>	—	Class names for the parts behind the root. The root itself is className, so there is no root key

label, description and error are props rather than children; children is not accepted.

For a setting that takes effect immediately, use Switch. A Checkbox is a value submitted alongside a Save button.

Examples

checked and onCheckedChange

checked with onCheckedChange makes it controlled; defaultChecked makes it uncontrolled.

disabled · readOnly · error

An error message also turns the checkbox invalid and re-points the colour family at danger: the tick, the focus ring and the message all turn over together.

import { Checkbox } from 'neba';

export default function CheckboxStates() {
  return (
    <div className="flex flex-col gap-3">
      <Checkbox label="Unchecked" />
      <Checkbox label="Checked" defaultChecked />
      <Checkbox label="Read-only" readOnly defaultChecked />
      <Checkbox label="Disabled" disabled />
      <Checkbox label="Disabled and checked" disabled defaultChecked />
      <Checkbox label="I agree to the terms" error="You have to agree to continue." />
    </div>
  );
}

indeterminate

A third appearance for a parent checkbox whose children disagree. The value underneath is still on or off; indeterminate only affects what is drawn.

import { useState } from 'react';
import { Checkbox } from 'neba';

const SCOPES = ['Read', 'Write', 'Delete'];

export default function CheckboxIndeterminate() {
  const [checked, setChecked] = useState([true, false, false]);
  const all = checked.every(Boolean);
  const some = checked.some(Boolean);

  return (
    <div className="flex flex-col gap-3">
      <Checkbox
        label="All permissions"
        checked={all}
        indeterminate={some && !all}
        onCheckedChange={(next) => setChecked(checked.map(() => next))}
      />
      <div className="ms-6 flex flex-col gap-3">
        {SCOPES.map((scope, index) => (
          <Checkbox
            key={scope}
            label={scope}
            checked={checked[index]}
            onCheckedChange={(next) =>
              setChecked(checked.map((value, i) => (i === index ? next : value)))
            }
          />
        ))}
      </div>
    </div>
  );
}

size

import { Checkbox } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function CheckboxSizes() {
  return (
    <div className="flex flex-col gap-3">
      {SIZES.map((size) => (
        <Checkbox key={size} size={size} label={size} defaultChecked />
      ))}
    </div>
  );
}

classNames

className lands on the field wrapper, not on the tick. The tick and the mark inside it are reached through classNames.

<Checkbox label="I agree" classNames={{ control: 'rounded-full', label: 'font-medium' }} />

The slots are label, control, indicator, description and error. control is the tick itself (the bordered box that fills when checked), and indicator is the mark inside it. See prop conventions for how a class name you pass resolves against the component's own.

Accessibility

• Renders role="checkbox" with a hidden <input> beside it, so giving it a name submits it with a form.
• The label is wired to the control, so clicking the text toggles the box.
• Without a label, give it an aria-label.
• indeterminate reports aria-checked="mixed".