Checkbox

An easily stylable checkbox component.

Preview

Enable notifications

Design guidance

Use Checkbox for an independent boolean. Use RadioGroup for one choice from a set and Switch for an immediate setting.

Need	Choose
Confirm a boolean	Checkbox records a checked or unchecked value.
Change a setting immediately	Switch applies the setting when toggled.

Installation

Install the local ghost-kit source bundle while the registry runs at localhost:3110. It contains this component and its source dependencies. Prepare the local registry first so token dependencies also resolve locally.

Install

npx shadcn@latest add http://localhost:3110/r/ghost-kit.json

Basic usage

123import { Checkbox } from "@/components/ui/checkbox";

<Checkbox.Root aria-label="Receive updates"><Checkbox.Indicator /></Checkbox.Root>

Structures

Examples

Interactive style

Use variant="interactive" to add row hover feedback and an inner control fill. Both styles fill the core control on hover. The default keeps the row and text unchanged. Set the variant on Checkbox.Row to style the control and its companion text. Checkbox.Root can override the control style. Keyboard focus remains visible in both styles.

Enable notifications

Basic checkbox

Use a checkbox for one independent choice. Click its label to toggle the value.

Enable notifications

With a field label

Field connects the label and description to the checkbox. The control stays beside the label, and the whole row remains clickable.

Send weekly updatesReceive the Monday summary by email.

Native button

Render the checkbox as a native button with nativeButton and render. The button still behaves as a checkbox.

Enable notifications

Control states

Checked, mixed, and disabled states preserve the same control geometry. A mixed state is useful for a parent that represents partially selected descendants.

CheckedMixedNot interactive

checkbox-states.tsx

1234567891011121314151617181920212223242526import { Checkbox } from "@/components/ui/checkbox";

export default function CheckboxStates() {
  return (
    <div style={{ display: "grid", gap: 10, minWidth: 0 }}>
      <Checkbox.Row>
        <Checkbox.Root defaultChecked>
          <Checkbox.Indicator />
        </Checkbox.Root>
        Checked
      </Checkbox.Row>
      <Checkbox.Row>
        <Checkbox.Root indeterminate>
          <Checkbox.Indicator />
        </Checkbox.Root>
        Mixed
      </Checkbox.Row>
      <Checkbox.Row>
        <Checkbox.Root disabled>
          <Checkbox.Indicator />
        </Checkbox.Root>
        Not interactive
      </Checkbox.Row>
    </div>
  );
}

API reference

variant accepts "default" | "interactive" and defaults to "default". Checkbox.Row sets the row and control style; Checkbox.Root can override the control. Both inherit a containing CheckboxGroup style when unset.

For inherited behavior and additional part properties, see the Base UI Checkbox API.

Checkbox.Root properties
Prop	Type	Default	Description
`className`	`string \| ((state: CheckboxRootState) => string)`		CSS class applied to the element, or a function that returns a class based on the component's state.
`defaultChecked`	`boolean`	`false`	Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead.
`style`	`CSSProperties \| ((state: CheckboxRootState) => React.CSSProperties)`		Style applied to the element, or a function that returns a style object based on the component's state.
`form`	`string`		Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
`disabled`	`boolean`	`false`	Whether the component should ignore user interaction.
`name`	`string`	`undefined`	Identifies the field when a form is submitted.
`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".
`id`	`string`		The id of the input element.
`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.
`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. Accepts a `ReactElement` or a function that returns the element to render.
`checked`	`boolean`	`undefined`	Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
`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.
`onCheckedChange`	`((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => 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.
`parent`	`boolean`	`false`	Whether the checkbox controls a group of child checkboxes. Must be used in a [Checkbox Group](https://base-ui.com/react/components/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.