Checkbox Group

A set of checkboxes, where more than one of the checkbox can be checked at a time.

Import

ts
import { CheckboxGroup } from "@kobalte/core/checkbox-group";
// or
import { Root, Label, ... } from "@kobalte/core/checkbox-group";
// or (deprecated)
import { CheckboxGroup } from "@kobalte/core";

ts
import { CheckboxGroup } from "@kobalte/core/checkbox-group";
// or
import { Root, Label, ... } from "@kobalte/core/checkbox-group";
// or (deprecated)
import { CheckboxGroup } from "@kobalte/core";

Features

Each checkbox is built with a native HTML <input> element, which is visually hidden to allow custom styling.
Syncs with form reset events.
Group and checkbox labeling support for assistive technology.
Can be controlled or uncontrolled.

Anatomy

The checkbox group consists of:

CheckboxGroup: The root container for the checkbox group.
CheckboxGroup.Label: The label that gives the user information on the checkbox group.
CheckboxGroup.Description: The description that gives the user more information on the checkbox group.
CheckboxGroup.ErrorMessage: The error message that gives the user information about how to fix a validation error on the checkbox group.

The checkbox item consists of:

CheckboxGroup.Item: The root container for a checkbox.
CheckboxGroup.ItemInput: The native html input that is visually hidden in the checkbox.
CheckboxGroup.ItemControl: The element that visually represents a checkbox.
CheckboxGroup.ItemIndicator: The visual indicator rendered when the checkbox is in a checked state.
CheckboxGroup.ItemLabel: The label that gives the user information on the checkbox.
CheckboxGroup.ItemDescription: The description that gives the user more information on the checkbox.

tsx
<CheckboxGroup>
	<CheckboxGroup.Label />
	<CheckboxGroup.Item>
		<CheckboxGroup.ItemInput />
		<CheckboxGroup.ItemControl>
			<CheckboxGroup.ItemIndicator />
		</CheckboxGroup.ItemControl>
		<CheckboxGroup.ItemLabel />
		<CheckboxGroup.ItemDescription />
	</CheckboxGroup.Item>
	<CheckboxGroup.Description />
	<CheckboxGroup.ErrorMessage />
</CheckboxGroup>

tsx
<CheckboxGroup>
	<CheckboxGroup.Label />
	<CheckboxGroup.Item>
		<CheckboxGroup.ItemInput />
		<CheckboxGroup.ItemControl>
			<CheckboxGroup.ItemIndicator />
		</CheckboxGroup.ItemControl>
		<CheckboxGroup.ItemLabel />
		<CheckboxGroup.ItemDescription />
	</CheckboxGroup.Item>
	<CheckboxGroup.Description />
	<CheckboxGroup.ErrorMessage />
</CheckboxGroup>

Example

Subscribe to topics

News

Updates

Offers

Usage

// FIXME: finalize and update all examples below

Default value

An initial, uncontrolled value can be provided using the defaultValue prop, which accepts a value corresponding with the value prop of each checkbox.

Subscribe to topics

News

Updates

Offers

tsx
<CheckboxGroup defaultValues={["News"]}>
	<CheckboxGroup.Label>Subscribe to topics</CheckboxGroup.Label>
	<div role="presentation">
		<For each={["News", "Updates", "Offers"]}>
			{topic => (
				<CheckboxGroup.Item id={topic} value={topic}>
					<CheckboxGroup.ItemInput />
					<CheckboxGroup.ItemControl>
						<CheckboxGroup.ItemIndicator>
							<CheckIcon />
						</CheckboxGroup.ItemIndicator>
					</CheckboxGroup.ItemControl>
					<CheckboxGroup.ItemLabel>{topic}</CheckboxGroup.ItemLabel>
				</CheckboxGroup.Item>
			)}
		</For>
	</div>
</CheckboxGroup>

tsx
<CheckboxGroup defaultValues={["News"]}>
	<CheckboxGroup.Label>Subscribe to topics</CheckboxGroup.Label>
	<div role="presentation">
		<For each={["News", "Updates", "Offers"]}>
			{topic => (
				<CheckboxGroup.Item id={topic} value={topic}>
					<CheckboxGroup.ItemInput />
					<CheckboxGroup.ItemControl>
						<CheckboxGroup.ItemIndicator>
							<CheckIcon />
						</CheckboxGroup.ItemIndicator>
					</CheckboxGroup.ItemControl>
					<CheckboxGroup.ItemLabel>{topic}</CheckboxGroup.ItemLabel>
				</CheckboxGroup.Item>
			)}
		</For>
	</div>
</CheckboxGroup>

The role="presentation" is required for all non content elements between the CheckboxGroup and CheckboxGroup.Item due to a bug in Chromium based browsers that incorrectly parse semantics and break screen readers.

Controlled value

The value prop, which accepts a value corresponding with the value prop of each checkbox, can be used to make the value controlled. The onChange event is fired when the user selects a checkbox, and receives the new value.

What would you like to subscribe to?

News

Updates

Offers

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal(["News"]);
	return (
		<CheckboxGroup values={value()} onChange={setValue}>
			<CheckboxGroup.Label>What would you like to subscribe to?</CheckboxGroup.Label>
			<div role="presentation">
				<For each={["News", "Updates", "Offers"]}>
					{option => (
						<CheckboxGroup.Item id={option} value={option}>
							<CheckboxGroup.ItemInput />
							<CheckboxGroup.ItemControl>
								<CheckboxGroup.ItemIndicator>
									<CheckIcon />
								</CheckboxGroup.ItemIndicator>
							</CheckboxGroup.ItemControl>
							<CheckboxGroup.ItemLabel>{option}</CheckboxGroup.ItemLabel>
						</CheckboxGroup.Item>
					)}
				</For>
			</div>
		</CheckboxGroup>
	);
}

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal(["News"]);
	return (
		<CheckboxGroup values={value()} onChange={setValue}>
			<CheckboxGroup.Label>What would you like to subscribe to?</CheckboxGroup.Label>
			<div role="presentation">
				<For each={["News", "Updates", "Offers"]}>
					{option => (
						<CheckboxGroup.Item id={option} value={option}>
							<CheckboxGroup.ItemInput />
							<CheckboxGroup.ItemControl>
								<CheckboxGroup.ItemIndicator>
									<CheckIcon />
								</CheckboxGroup.ItemIndicator>
							</CheckboxGroup.ItemControl>
							<CheckboxGroup.ItemLabel>{option}</CheckboxGroup.ItemLabel>
						</CheckboxGroup.Item>
					)}
				</For>
			</div>
		</CheckboxGroup>
	);
}

Description

The CheckboxGroup.Description component can be used to associate additional help text with a checkbox group.

What would you like to subscribe to?

News

Updates

Offers

Select the types of updates you'd like to receive.

tsx
<CheckboxGroup>
	<CheckboxGroup.Label>What would you like to subscribe to?</CheckboxGroup.Label>
	<div role="presentation">
		<For each={["News", "Updates", "Offers"]}>
			{option => (
				<CheckboxGroup.Item value={option}>
					<CheckboxGroup.ItemInput />
					<CheckboxGroup.ItemControl>
						<CheckboxGroup.ItemIndicator>
							<CheckIcon />
						</CheckboxGroup.ItemIndicator>
					</CheckboxGroup.ItemControl>
					<CheckboxGroup.ItemLabel>{option}</CheckboxGroup.ItemLabel>
				</CheckboxGroup.Item>
			)}
		</For>
	</div>
	<CheckboxGroup.Description>
		Select the types of updates you'd like to receive.
	</CheckboxGroup.Description>
</CheckboxGroup>

tsx
<CheckboxGroup>
	<CheckboxGroup.Label>What would you like to subscribe to?</CheckboxGroup.Label>
	<div role="presentation">
		<For each={["News", "Updates", "Offers"]}>
			{option => (
				<CheckboxGroup.Item value={option}>
					<CheckboxGroup.ItemInput />
					<CheckboxGroup.ItemControl>
						<CheckboxGroup.ItemIndicator>
							<CheckIcon />
						</CheckboxGroup.ItemIndicator>
					</CheckboxGroup.ItemControl>
					<CheckboxGroup.ItemLabel>{option}</CheckboxGroup.ItemLabel>
				</CheckboxGroup.Item>
			)}
		</For>
	</div>
	<CheckboxGroup.Description>
		Select the types of updates you'd like to receive.
	</CheckboxGroup.Description>
</CheckboxGroup>

Error message

The CheckboxGroup.ErrorMessage component can be used to help the user fix a validation error. It should be combined with the validationState prop to semantically mark the checkbox group as invalid for assistive technologies.

By default, it will render only when the validationState prop is set to invalid, use the forceMount prop to always render the error message (ex: for usage with animation libraries).

What would you like to subscribe to?

News

Updates

Offers

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal(["News"]);
	return (
		<CheckboxGroup
			values={value()}
			onChange={setValue}
			validationState={!value().includes("News") ? "invalid" : "valid"}
		>
			<CheckboxGroup.Label>What would you like to subscribe to?</CheckboxGroup.Label>
			<div role="presentation">
				<For each={["News", "Updates", "Offers"]}>
					{option => (
						<CheckboxGroup.Item id={option} value={option}>
							<CheckboxGroup.ItemInput />
							<CheckboxGroup.ItemControl>
								<CheckboxGroup.ItemIndicator>
									<CheckIcon />
								</CheckboxGroup.ItemIndicator>
							</CheckboxGroup.ItemControl>
							<CheckboxGroup.ItemLabel>{option}</CheckboxGroup.ItemLabel>
						</CheckboxGroup.Item>
					)}
				</For>
			</div>
			<CheckboxGroup.ErrorMessage>Please select News to stay informed.</CheckboxGroup.ErrorMessage>
		</CheckboxGroup>
	);
}

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal(["News"]);
	return (
		<CheckboxGroup
			values={value()}
			onChange={setValue}
			validationState={!value().includes("News") ? "invalid" : "valid"}
		>
			<CheckboxGroup.Label>What would you like to subscribe to?</CheckboxGroup.Label>
			<div role="presentation">
				<For each={["News", "Updates", "Offers"]}>
					{option => (
						<CheckboxGroup.Item id={option} value={option}>
							<CheckboxGroup.ItemInput />
							<CheckboxGroup.ItemControl>
								<CheckboxGroup.ItemIndicator>
									<CheckIcon />
								</CheckboxGroup.ItemIndicator>
							</CheckboxGroup.ItemControl>
							<CheckboxGroup.ItemLabel>{option}</CheckboxGroup.ItemLabel>
						</CheckboxGroup.Item>
					)}
				</For>
			</div>
			<CheckboxGroup.ErrorMessage>Please select News to stay informed.</CheckboxGroup.ErrorMessage>
		</CheckboxGroup>
	);
}

HTML forms

The checkbox group name prop, paired with the checkbox value prop, can be used for integration with HTML forms.

tsx
function HTMLFormExample() {
	let formRef: HTMLFormElement | undefined;
	const onSubmit = (e: SubmitEvent) => {
		e.preventDefault();
		e.stopPropagation();
		const formData = new FormData(formRef);
		const subscriptions = Array.from(formData.getAll("subscriptions"));
		const result = {
			...Object.fromEntries(formData),
			subscriptions,
		};
		alert(JSON.stringify(result, null, 2));
	};
	return (
		<form ref={formRef} onSubmit={onSubmit}>
			<CheckboxGroup name="subscriptions">
				<CheckboxGroup.Label>What would you like to subscribe to?</CheckboxGroup.Label>
				<div role="presentation">
					<For each={["News", "Updates", "Offers"]}>
						{option => (
							<CheckboxGroup.Item id={option} value={option}>
								<CheckboxGroup.ItemInput />
								<CheckboxGroup.ItemControl>
									<CheckboxGroup.ItemIndicator>
										<CheckIcon />
									</CheckboxGroup.ItemIndicator>
								</CheckboxGroup.ItemControl>
								<CheckboxGroup.ItemLabel>{option}</CheckboxGroup.ItemLabel>
							</CheckboxGroup.Item>
						)}
					</For>
				</div>
			</CheckboxGroup>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

tsx
function HTMLFormExample() {
	let formRef: HTMLFormElement | undefined;
	const onSubmit = (e: SubmitEvent) => {
		e.preventDefault();
		e.stopPropagation();
		const formData = new FormData(formRef);
		const subscriptions = Array.from(formData.getAll("subscriptions"));
		const result = {
			...Object.fromEntries(formData),
			subscriptions,
		};
		alert(JSON.stringify(result, null, 2));
	};
	return (
		<form ref={formRef} onSubmit={onSubmit}>
			<CheckboxGroup name="subscriptions">
				<CheckboxGroup.Label>What would you like to subscribe to?</CheckboxGroup.Label>
				<div role="presentation">
					<For each={["News", "Updates", "Offers"]}>
						{option => (
							<CheckboxGroup.Item id={option} value={option}>
								<CheckboxGroup.ItemInput />
								<CheckboxGroup.ItemControl>
									<CheckboxGroup.ItemIndicator>
										<CheckIcon />
									</CheckboxGroup.ItemIndicator>
								</CheckboxGroup.ItemControl>
								<CheckboxGroup.ItemLabel>{option}</CheckboxGroup.ItemLabel>
							</CheckboxGroup.Item>
						)}
					</For>
				</div>
			</CheckboxGroup>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

API Reference

CheckboxGroup

CheckboxGroup is equivalent to the Root import from @kobalte/core/checkbox-group (and deprecated CheckboxGroup.Root).

Prop	Description
values	`string[]` The controlled values of the checkboxes to check.
defaultValues	`string[]` The value of the checkboxes that should be checked when initially rendered. Useful when you do not need to control the state of the checkboxes.
onChange	`(value: string) => void` Event handler called when the value changes.
orientation	`'horizontal' \| 'vertical'` The axis the checkbox group items should align with.
name	`string` The name of the checkbox group. Submitted with its owning form as part of a name/value pair.
validationState	`'valid' \| 'invalid'` Whether the checkbox group should display its "valid" or "invalid" visual styling.
required	`boolean` Whether the user must check a checkbox group item before the owning form can be submitted.
disabled	`boolean` Whether the checkbox group is disabled.
readOnly	`boolean` Whether the checkbox group items can be selected but not changed by the user.

Data attribute	Description
data-valid	Present when the checkbox group is valid according to the validation rules.
data-invalid	Present when the checkbox group is invalid according to the validation rules.
data-required	Present when the user must check a checkbox group item before the owning form can be submitted.
data-disabled	Present when the checkbox group is disabled.
data-readonly	Present when the checkbox group is read only.

CheckboxGroup.Label, CheckboxGroup.Description and CheckboxGroup.ErrorMesssage shares the same data-attributes.

CheckboxGroup.ErrorMessage

Prop	Description
forceMount	`boolean` Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries.

CheckboxGroup.Item

Prop	Description
value	`string` The value of the checkbox, used when submitting an HTML form. See MDN.
disabled	`boolean` Whether the checkbox is disabled or not.

Data attribute	Description
data-valid	Present when the parent checkbox group is valid according to the validation rules.
data-invalid	Present when the parent checkbox group is invalid according to the validation rules.
data-checked	Present when the checkbox is checked.
data-disabled	Present when the checkbox is disabled.

CheckboxGroup.ItemInput, CheckboxGroup.ItemControl, CheckboxGroup.ItemIndicator and CheckboxGroup.ItemLabel shares the same data-attributes.

CheckboxGroup.ItemIndicator

Prop	Description
forceMount	`boolean` Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries.

Rendered elements

Component	Default rendered element
`CheckboxGroup`	`div`
`CheckboxGroup.Label`	`span`
`CheckboxGroup.Description`	`div`
`CheckboxGroup.ErrorMessage`	`div`
`CheckboxGroup.Item`	`div`
`CheckboxGroup.ItemInput`	`input`
`CheckboxGroup.ItemControl`	`div`
`CheckboxGroup.ItemIndicator`	`div`
`CheckboxGroup.ItemLabel`	`label`
`CheckboxGroup.ItemDescription`	`div`

Accessibility

Keyboard Interactions

Key	Description
`Tab`	Moves focus to either the checked checkbox or the first checkbox in the group.
`Space`	When focus is on an unchecked checkbox, checks it.
`ArrowDown`	Moves focus and checks the next checkbox in the group.
`ArrowRight`	Moves focus and checks the next checkbox in the group.
`ArrowUp`	Moves focus and checks the previous checkbox in the group.
`ArrowLeft`	Moves focus and checks the previous checkbox in the group.