Checkbox

Turns a single option on or off, or picks any number of options from a list.

@zenoxai/ui/components/checkboxBase UI Markdown

Email me when a critical alert opens

<Field orientation="horizontal" className="w-fit">
  <Checkbox id="notify-critical" defaultChecked />
  <FieldLabel htmlFor="notify-critical">
    Email me when a critical alert opens
  </FieldLabel>
</Field>

Usage

import { Checkbox } from "@zenoxai/ui/components/checkbox"
import { Field, FieldLabel } from "@zenoxai/ui/components/field"

<Field orientation="horizontal">
  <Checkbox id="notify-critical" defaultChecked />
  <FieldLabel htmlFor="notify-critical">Email me when a critical alert opens</FieldLabel>
</Field>

Use a checkbox for an option that takes effect when the form is saved, and for picking several options from a short list. For a setting that applies the moment it is flipped, use a Switch. For exactly one option out of a few, use a Radio Group.

Pair every checkbox with a visible label. A horizontal Field lays out the box and the label and dims both when the field is disabled.

Checkbox is uncontrolled with defaultChecked, or controlled with checked and onCheckedChange(checked). Set name and value to submit it with a native form.

Examples

With a description

Put the label and a FieldDescription in a FieldContent when the option needs a sentence of explanation. The box aligns with the first line of the label.

Close resolved alerts

Alerts with no new events for 7 days move to Closed.

<Field orientation="horizontal" className="max-w-sm">
  <Checkbox id="auto-close" />
  <FieldContent>
    <FieldLabel htmlFor="auto-close">Close resolved alerts</FieldLabel>
    <FieldDescription>
      Alerts with no new events for 7 days move to Closed.
    </FieldDescription>
  </FieldContent>
</Field>

Disabled

Set disabled on the checkbox and data-disabled on the Field, so the label dims with it.

Require single sign-on

Allow API access

<FieldGroup className="w-56 gap-3">
  <Field orientation="horizontal" data-disabled>
    <Checkbox id="sso-enforced" defaultChecked disabled />
    <FieldLabel htmlFor="sso-enforced">Require single sign-on</FieldLabel>
  </Field>
  <Field orientation="horizontal" data-disabled>
    <Checkbox id="api-access" disabled />
    <FieldLabel htmlFor="api-access">Allow API access</FieldLabel>
  </Field>
</FieldGroup>

Invalid

Set aria-invalid on the checkbox and data-invalid on the Field, and say what to do in a FieldError.

I understand that purged events cannot be restored

Confirm this to purge the events.

<Field orientation="horizontal" data-invalid className="max-w-sm">
  <Checkbox id="purge-ack" required aria-invalid />
  <FieldContent>
    <FieldLabel htmlFor="purge-ack">
      I understand that purged events cannot be restored
    </FieldLabel>
    <FieldError>Confirm this to purge the events.</FieldError>
  </FieldContent>
</Field>

Controlled list

Group related checkboxes in a FieldSet with a FieldLegend, and keep the selection in state when other parts of the view depend on it.

Notify on severity

Critical

High

Medium

Low

Notifying on 2 of 4 severities.

function CheckboxControlled() {
  const severities = ["Critical", "High", "Medium", "Low"]
  const [selected, setSelected] = React.useState(["Critical", "High"])

  return (
    <FieldSet className="w-fit">
      <FieldLegend variant="label">Notify on severity</FieldLegend>
      <FieldGroup className="gap-3">
        {severities.map((severity) => (
          <Field key={severity} orientation="horizontal">
            <Checkbox
              id={`severity-${severity}`}
              checked={selected.includes(severity)}
              onCheckedChange={(checked) =>
                setSelected((current) =>
                  checked
                    ? [...current, severity]
                    : current.filter((value) => value !== severity)
                )
              }
            />
            <FieldLabel htmlFor={`severity-${severity}`}>{severity}</FieldLabel>
          </Field>
        ))}
      </FieldGroup>
      <FieldDescription>
        {selected.length === 0
          ? "No notifications."
          : `Notifying on ${selected.length} of ${severities.length} severities.`}
      </FieldDescription>
    </FieldSet>
  )
}

Accessibility

The checkbox renders a <span role="checkbox"> with a hidden <input> beside it. The id goes to the hidden input, so <FieldLabel htmlFor> (or a wrapping label) names the checkbox and toggles it on click.
Space toggles the focused checkbox. aria-checked and data-checked follow the state.
indeterminate sets aria-checked="mixed" and draws a dash instead of a check mark: use it for a “select all” box when only some of the items are selected.
Put a group of checkboxes in a FieldSet with a FieldLegend so screen readers announce the group name with each option.

API reference

Generated from the TypeScript source. className, style and children are accepted everywhere and omitted below.

Checkbox

Checkbox turns one option on or off, or picks several options from a list. For a setting that takes effect at once, use Switch; for one choice out of several, RadioGroup.

Prop	Type	Default
`checked`	`boolean` Whether the checkbox is currently ticked.	`undefined`
`defaultChecked`	`boolean` Whether the checkbox is initially ticked.	`false`
`disabled`	`boolean` Whether the component should ignore user interaction.	`false`
`form`	`string` Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.	-
`id`	`string` The id of the input element.	-
`indeterminate`	`boolean` Whether the checkbox is in a mixed state: neither ticked, nor unticked.	`false`
`inputRef`	`Ref<HTMLInputElement>` A ref to access the hidden `<input>` element.	-
`name`	`string` Identifies the field when a form is submitted.	`undefined`
`nativeButton`	`boolean` Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).	`true`
`onCheckedChange`	`((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void)` Event handler called when the checkbox is ticked or unticked.	-
`parent`	`boolean` Whether the checkbox controls a group of child checkboxes.	`false`
`readOnly`	`boolean` Whether the user should be unable to tick or untick the checkbox.	`false`
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, CheckboxRootState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-
`required`	`boolean` Whether the user must tick the checkbox before submitting a form.	`false`
`uncheckedValue`	`string` The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.	-
`value`	`string` The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".	-