Checkbox primitive

Use the Checkbox primitive when your layout owns the label, such as a table row, or when the label needs custom content. For a normal labelled checkbox, use CheckboxField.

import {
	CheckboxControl,
	CheckboxIndicator,
	CheckboxLabel,
	CheckboxRoot,
} from '@luke-ui/react/primitives/checkbox';
import { InlineField } from '@luke-ui/react/primitives/field';

export default () => {
	return (
		<CheckboxRoot>
			<InlineField description="Example description">
				<CheckboxLabel>
					<CheckboxControl>
						<CheckboxIndicator />
					</CheckboxControl>
					Example checkbox
				</CheckboxLabel>
			</InlineField>
		</CheckboxRoot>
	);
};

Anatomy

CheckboxRoot is the semantic root. It owns the selection, state, validation, form, and size props. id, className, and ref target the root element. inputId and inputRef target the input.

CheckboxLabel is the clickable native <label>. It holds the hidden input, CheckboxControl, and usually the label text. Like React Aria's CheckboxButton, it takes className, style, and children as functions of the checkbox state, as well as render, slot, and event handlers.

CheckboxControl sizes the visual affordance to the label's first line, and CheckboxIndicator draws the box and its selected and indeterminate states. Put the control before the label text.

Description and error

Wrap CheckboxLabel in InlineField to add a description and an errorMessage. The errorMessage shows while the root is invalid. For a custom arrangement, place FieldDescription and FieldError inside the root instead of InlineField.

Labels

CheckboxLabel is a native <label>, so it takes textual, non-interactive content only. Place links and buttons outside it.

When another part of the layout draws the visible label, leave the text out of CheckboxLabel. Place a FieldLabel and a FieldDescription anywhere inside CheckboxRoot. The root connects them to the input, so the label names the checkbox, clicking it toggles the checkbox, and the description describes it. Pass no ids. The Switch primitive shows the same pattern.

Put the label text in either CheckboxLabel or FieldLabel, not both. The checkbox's name joins the text from each. Pass aria-label when no visible text names the checkbox.

CheckboxLabel draws no required marker. With isRequired on CheckboxRoot, a FieldLabel does, as Required fields describes. Show the required state in your own content when you use CheckboxLabel for the text.

Text in the label

Set slot={null} on each Text you place in CheckboxLabel, so it renders as label content rather than a description or error.

import {
	CheckboxControl,
	CheckboxIndicator,
	CheckboxLabel,
	CheckboxRoot,
} from '@luke-ui/react/primitives/checkbox';
import { Stack } from '@luke-ui/react/stack';
import { Text } from '@luke-ui/react/text';

export default () => {
	return (
		<CheckboxRoot>
			<CheckboxLabel>
				<CheckboxControl>
					<CheckboxIndicator />
				</CheckboxControl>
				<Stack gap="space.4">
					<Text slot={null} typography="label">
						Example checkbox
					</Text>
					<Text color="secondary" slot={null} typography="caption">
						Supporting text inside the label
					</Text>
				</Stack>
			</CheckboxLabel>
		</CheckboxRoot>
	);
};

API

CheckboxRootProps

CheckboxLabelProps

CheckboxControlProps

CheckboxIndicatorProps