Checkbox

Toggle an independent choice or select several options.

View component source ↗

Preview

Example

A minimal example to get started.

Email me product updates

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/checkbox.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

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

export default function Example() {
  return (
    <label className="flex items-center gap-2 text-sm">
      <Checkbox defaultChecked />
      Email me product updates
    </label>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

Checkbox

Checkbox properties
Prop	Type	Default	Description
`id`	string \| undefined string \| undefined	`—`	The id of the input element.
`name`	string \| undefined string \| undefined	`undefined`	Identifies the field when a form is submitted.
`form`	string \| undefined string \| undefined	`—`	Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
`checked`	boolean \| undefined boolean \| undefined	`undefined`	Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
`defaultChecked`	boolean \| undefined boolean \| undefined	`false`	Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead.
`disabled`	boolean \| undefined boolean \| undefined	`false`	Whether the component should ignore user interaction.
`onCheckedChange`	((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void) \| undefined ((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void) \| undefined	`—`	Event handler called when the checkbox is ticked or unticked.
`readOnly`	boolean \| undefined boolean \| undefined	`false`	Whether the user should be unable to tick or untick the checkbox.
`required`	boolean \| undefined boolean \| undefined	`false`	Whether the user must tick the checkbox before submitting a form.
`indeterminate`	boolean \| undefined boolean \| undefined	`false`	Whether the checkbox is in a mixed state: neither ticked, nor unticked.
`inputRef`	React.Ref<HTMLInputElement> \| undefined React.Ref<HTMLInputElement> \| undefined	`—`	A ref to access the hidden `<input>` element.
`parent`	boolean \| undefined boolean \| undefined	`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 \| undefined string \| undefined	`—`	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 \| undefined string \| undefined	`—`	The value of the selected checkbox.
`nativeButton`	boolean \| undefined boolean \| undefined	`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.
`className`	string \| ((state: CheckboxRootState) => string \| undefined) \| undefined string \| ((state: CheckboxRootState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`style`	React.CSSProperties \| ((state: CheckboxRootState) => React.CSSProperties \| undefined) \| un… React.CSSProperties \| ((state: CheckboxRootState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`ref`	React.Ref<HTMLSpanElement> \| undefined React.Ref<HTMLSpanElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLSpanElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLSpanElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLSpanElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, CheckboxRootState> \| undefined	`—`	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.

Usage notes

Always associate the checkbox with visible text. Use checked and onCheckedChange for a controlled field.