Checkbox

<Description> A control that allows the user to toggle between checked and not checked. </Description> <HeroContainer> <CheckboxDemo /> </HeroContainer> <HeroCodeBlock folder="Checkbox" />

Installation

Install the component from your command line.

bash

npm install @radix-ui/react-checkbox

Anatomy

Import all parts and piece them together.

jsx

import { Checkbox } from "radix-ui";

export default () => (
	<Checkbox.Root>
		<Checkbox.Indicator />
	</Checkbox.Root>
);

API Reference

Root

Contains all the parts of a checkbox. An input will also render when used within a form to ensure events propagate correctly.

<PropsTable data={[ { name: "asChild", required: false, type: "boolean", default: "false", description: ( <> Change the default rendered element for the one passed as a child, merging their props and behavior.

				Read our <a href="../guides/composition">Composition</a> guide for
				more details.
			</>
		),
	},
	{
		name: "defaultChecked",
		type: `boolean | 'indeterminate'`,
		description:
			"The checked state of the checkbox when it is initially rendered. Use when you do not need to control its checked state.",
	},
	{
		name: "checked",
		type: `boolean | 'indeterminate'`,
		description: (
			<span>
				The controlled checked state of the checkbox. Must be used in
				conjunction with <Code>onCheckedChange</Code>.
			</span>
		),
	},
	{
		name: "onCheckedChange",
		type: `(checked: boolean | 'indeterminate') => void`,
		typeSimple: "function",
		description:
			"Event handler called when the checked state of the checkbox changes.",
	},
	{
		name: "disabled",
		type: "boolean",
		description: (
			<span>
				When <Code>true</Code>, prevents the user from interacting with the
				checkbox.
			</span>
		),
	},
	{
		name: "required",
		type: "boolean",
		description: (
			<span>
				When <Code>true</Code>, indicates that the user must check the
				checkbox before the owning form can be submitted.
			</span>
		),
	},
	{
		name: "name",
		type: "string",
		description:
			"The name of the checkbox. Submitted with its owning form as part of a name/value pair.",
	},
	{
		name: "value",
		type: "string",
		default: "on",
		description: (
			<span>
				The value given as data when submitted with a <Code>name</Code>.
			</span>
		),
	},
]}

Indicator

Renders when the checkbox is in a checked or indeterminate state. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.

				Read our <a href="../guides/composition">Composition</a> guide for
				more details.
			</>
		),
	},
	{
		name: "forceMount",
		type: "boolean",
		description:
			"Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.",
	},
]}

Examples

Indeterminate

You can set the checkbox to indeterminate by taking control of its state.

jsx

import { DividerHorizontalIcon, CheckIcon } from "@radix-ui/react-icons";
import { Checkbox } from "radix-ui";

export default () => {
	const [checked, setChecked] = React.useState("indeterminate");

	return (
		<>
			<StyledCheckbox checked={checked} onCheckedChange={setChecked}>
				<Checkbox.Indicator>
					{checked === "indeterminate" && <DividerHorizontalIcon />}
					{checked === true && <CheckIcon />}
				</Checkbox.Indicator>
			</StyledCheckbox>

			<button
				type="button"
				onClick={() =>
					setChecked((prevIsChecked) =>
						prevIsChecked === "indeterminate" ? false : "indeterminate",
					)
				}
			>
				Toggle indeterminate
			</button>
		</>
	);
};

Accessibility

Adheres to the tri-state Checkbox WAI-ARIA design pattern.

Keyboard Interactions