Checkbox component

Accept terms and conditions

import { Checkbox } from 'gnome-ui/checkbox';
import { Check } from 'lucide-react';

export function CheckboxDefault() {
  return (
    <label className="flex select-none items-center gap-3 text-sm font-medium text-foreground cursor-pointer">
      <Checkbox.Root className="flex size-5 shrink-0 items-center justify-center rounded-md border border-input bg-card text-card-foreground shadow-sm transition-colors duration-150 hover:border-border focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring data-[checked]:border-primary data-[checked]:bg-primary data-[checked]:text-primary-foreground disabled:cursor-not-allowed disabled:opacity-50">
        <Checkbox.Indicator className="flex items-center justify-center">
          <Icons.Check className="size-3.5" strokeWidth={3} />
        </Checkbox.Indicator>
      </Checkbox.Root>
      Accept terms and conditions
    </label>
  );
}

Anatomy

import { Checkbox } from 'gnome-ui/checkbox';

<Checkbox.Root>
  <Checkbox.Indicator />
</Checkbox.Root>

Examples

Disabled

The checkbox can be disabled to prevent user interaction.

Checkbox component

Disabled optionChecked and disabled option

import { Checkbox } from 'gnome-ui/checkbox';
import { Check } from 'lucide-react';

export function CheckboxDisabled() {
  return (
    <div className="flex flex-col gap-4">
      <label className="flex select-none items-center gap-3 text-sm font-medium text-muted-foreground cursor-not-allowed">
        <Checkbox.Root disabled className="flex size-5 shrink-0 items-center justify-center rounded-md border border-input bg-card text-card-foreground shadow-sm transition-colors duration-150 hover:border-border focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring data-[checked]:border-primary data-[checked]:bg-primary data-[checked]:text-primary-foreground disabled:cursor-not-allowed disabled:opacity-50">
          <Checkbox.Indicator className="flex items-center justify-center">
            <Icons.Check className="size-3.5" strokeWidth={3} />
          </Checkbox.Indicator>
        </Checkbox.Root>
        Disabled option
      </label>

      <label className="flex select-none items-center gap-3 text-sm font-medium text-muted-foreground cursor-not-allowed">
        <Checkbox.Root disabled defaultChecked className="flex size-5 shrink-0 items-center justify-center rounded-md border border-input bg-card text-card-foreground shadow-sm transition-colors duration-150 hover:border-border focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring data-[checked]:border-primary data-[checked]:bg-primary data-[checked]:text-primary-foreground disabled:cursor-not-allowed disabled:opacity-50">
          <Checkbox.Indicator className="flex items-center justify-center">
            <Icons.Check className="size-3.5" strokeWidth={3} />
          </Checkbox.Indicator>
        </Checkbox.Root>
        Checked and disabled option
      </label>
    </div>
  );
}

Indeterminate

The checkbox supports an indeterminate state for mixed selection scenarios.

Checkbox component

Partial selection

import * as React from 'react';
import { Checkbox } from 'gnome-ui/checkbox';
import { Check, Minus } from 'lucide-react';

export function CheckboxIndeterminate() {
  const [checked, setChecked] = React.useState<boolean | 'indeterminate'>('indeterminate');

  return (
    <label className="flex select-none items-center gap-3 text-sm font-medium text-foreground cursor-pointer">
      <Checkbox.Root
        checked={checked}
        onCheckedChange={(c) => setChecked(c)}
        className="flex size-5 shrink-0 items-center justify-center rounded-md border border-input bg-card text-card-foreground shadow-sm transition-colors duration-150 hover:border-border focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring data-[checked]:border-primary data-[checked]:bg-primary data-[checked]:text-primary-foreground disabled:cursor-not-allowed disabled:opacity-50"
      >
        <Checkbox.Indicator className="flex items-center justify-center">
          {checked === 'indeterminate' ? (
            <Icons.Minus className="size-3.5" strokeWidth={3} />
          ) : (
            <Icons.Check className="size-3.5" strokeWidth={3} />
          )}
        </Checkbox.Indicator>
      </Checkbox.Root>
      Partial selection
    </label>
  );
}

Props

Checkbox.Root

Prop	Type	Default	Description
className	`string	(...) => string)`	—
defaultChecked	`boolean`	`false`	Whether the checkbox is initially ticked. To render a controlled checkbox, use the checked prop instead.
id	`string`	—	The id of the input element.
render	`ReactElement>	ComponentRenderFn`	—
value	`string`	—	The value of the selected checkbox.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
name	`string`	`undefined`	Identifies the field when a form is submitted.
nativeButton	`boolean`	`false`	Whether the component renders a native `<button>` element when replacing it via the render prop. Set to true if the rendered element is a native button.
required	`boolean`	`false`	Whether the user must tick the checkbox before submitting a form.
readOnly	`boolean`	`false`	Whether the user should be unable to tick or untick the checkbox.
inputRef	`Ref<HTMLInputElement>`	—	A ref to access the hidden `<input>` element.
checked	`boolean`	`undefined`	Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the defaultChecked prop instead.
indeterminate	`boolean`	`false`	Whether the checkbox is in a mixed state: neither ticked, nor unticked.
onCheckedChange	`(...) => void`	—	Event handler called when the checkbox is ticked or unticked.
parent	`boolean`	`false`	Whether the checkbox controls a group of child checkboxes. Must be used in a Checkbox Group.
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.

Checkbox.Indicator

Prop	Type	Default	Description
className	`string	(...) => string)`	—
render	`ReactElement>	ComponentRenderFn`	—
keepMounted	`boolean`	`false`	Whether to keep the element in the DOM when the checkbox is not checked.

Checkbox.Group

Prop	Type	Default	Description
className	`string	(...) => string)`	—
defaultValue	`string[]`	—	Names of the checkboxes in the group that should be initially ticked. To render a controlled checkbox group, use the value prop instead.
render	`ReactElement>	ComponentRenderFn`	—
value	`string[]`	—	Names of the checkboxes in the group that should be ticked. To render an uncontrolled checkbox group, use the defaultValue prop instead.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
onValueChange	`(...) => void`	—	Event handler called when a checkbox in the group is ticked or unticked. Provides the new value as an argument.
allValues	`string[]`	—	Names of all checkboxes in the group. Use this when creating a parent checkbox.

API reference

Root

Represents the checkbox itself. Renders a <span> element and a hidden <input> beside.

Root Props:

Prop	Type	Default	Description
name	`string`	`undefined`	Identifies the field when a form is submitted.
defaultChecked	`boolean`	`false`	Whether the checkbox is initially ticked.To render a controlled checkbox, use the `checked` prop instead.
checked	`boolean`	`undefined`	Whether the checkbox is currently ticked.To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
onCheckedChange	`((checked: boolean, eventDetails: Checkbox.Root.ChangeEventDetails) => void)`	-	Event handler called when the checkbox is ticked or unticked.
indeterminate	`boolean`	`false`	Whether the checkbox is in a mixed state: neither ticked, nor unticked.
value	`string`	-	The value of the selected checkbox.
nativeButton	`boolean`	`false`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
parent	`boolean`	`false`	Whether the checkbox controls a group of child checkboxes.Must be used in a Checkbox Group.
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.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
readOnly	`boolean`	`false`	Whether the user should be unable to tick or untick the checkbox.
required	`boolean`	`false`	Whether the user must tick the checkbox before submitting a form.
inputRef	`Ref<HTMLInputElement>`	-	A ref to access the hidden `<input>` element.
id	`string`	-	The id of the input element.
className	`string \| ((state: Checkbox.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Checkbox.Root.State) => CSSProperties \| undefined)`	-	-
render	`ReactElement \| ((props: HTMLProps, state: Checkbox.Root.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Root Data Attributes:

Attribute	Type	Description
data-checked	-	Present when the checkbox is checked.
data-unchecked	-	Present when the checkbox is not checked.
data-disabled	-	Present when the checkbox is disabled.
data-readonly	-	Present when the checkbox is readonly.
data-required	-	Present when the checkbox is required.
data-valid	-	Present when the checkbox is in valid state (when wrapped in Field.Root).
data-invalid	-	Present when the checkbox is in invalid state (when wrapped in Field.Root).
data-dirty	-	Present when the checkbox's value has changed (when wrapped in Field.Root).
data-touched	-	Present when the checkbox has been touched (when wrapped in Field.Root).
data-filled	-	Present when the checkbox is checked (when wrapped in Field.Root).
data-focused	-	Present when the checkbox is focused (when wrapped in Field.Root).
data-indeterminate	-	Present when the checkbox is in an indeterminate state.

Indicator

Indicates whether the checkbox is ticked. Renders a <span> element.

Indicator Props:

Prop	Type	Default	Description
className	`string \| ((state: Checkbox.Indicator.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component’s state.
style	`CSSProperties \| ((state: Checkbox.Indicator.State) => CSSProperties \| undefined)`	-	-
keepMounted	`boolean`	`false`	Whether to keep the element in the DOM when the checkbox is not checked.
render	`ReactElement \| ((props: HTMLProps, state: Checkbox.Indicator.State) => ReactElement)`	-	Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a `ReactElement` or a function that returns the element to render.

Indicator Data Attributes:

Attribute	Type	Description
data-checked	-	Present when the checkbox is checked.
data-unchecked	-	Present when the checkbox is not checked.
data-disabled	-	Present when the checkbox is disabled.
data-readonly	-	Present when the checkbox is readonly.
data-required	-	Present when the checkbox is required.
data-valid	-	Present when the checkbox is in valid state (when wrapped in Field.Root).
data-invalid	-	Present when the checkbox is in invalid state (when wrapped in Field.Root).
data-dirty	-	Present when the checkbox's value has changed (when wrapped in Field.Root).
data-touched	-	Present when the checkbox has been touched (when wrapped in Field.Root).
data-filled	-	Present when the checkbox is checked (when wrapped in Field.Root).
data-focused	-	Present when the checkbox is focused (when wrapped in Field.Root).
data-indeterminate	-	Present when the checkbox is in an indeterminate state.
data-starting-style	-	Present when the checkbox indicator is animating in.
data-ending-style	-	Present when the checkbox indicator is animating out.

Checkbox

On this page