Checkbox
Turn one independent option on or off.
Overview
Checkbox is a native binary form control for one independent choice. Use CheckboxGroup when related options can be selected independently as a set.
onChange, not onCheckedChange. Use indeterminate, not checked="indeterminate"; checked accepts only a boolean.Use when
A choice is independent and can be on or off alongside other choices.
Use instead
Use RadioGroup or SegmentedControl for one choice from a mutually exclusive set.
Usage
import { Checkbox } from "@smoothie-framework/whisk-react";
<Checkbox
name="releaseNotes"
label="Send me release notes"
defaultChecked
/>Examples
Variants
Choose the treatment that fits the surrounding form surface.
import { Checkbox, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={3}>
<Checkbox variant="solid" label="Solid" defaultChecked />
<Checkbox variant="subtle" label="Subtle" defaultChecked />
<Checkbox variant="outline" label="Outline" defaultChecked />
</Stack>Sizes
Match the checkbox size to the density of the surrounding controls.
import { Checkbox, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={3}>
<Checkbox size="sm" label="Small" defaultChecked />
<Checkbox size="md" label="Medium" defaultChecked />
<Checkbox size="lg" label="Large" defaultChecked />
</Stack>States
Use disabled when a choice is unavailable and readOnly when its current value must remain visible without changing. Pair invalid state with Field error feedback.
import { Checkbox, Field, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={3}>
<Checkbox label="Checked" defaultChecked />
<Checkbox label="Disabled" disabled />
<Checkbox label="Read-only" defaultChecked readOnly />
<Field error="Choose whether to receive security notices.">
<Checkbox label="Security notices" />
</Field>
</Stack>Label position
Put a label before the control only when the surrounding layout makes that reading order clearer.
import { Checkbox, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={3}>
<Checkbox label="Label at the end" />
<Checkbox label="Label at the start" labelPosition="start" />
</Stack>Composition
Use the compound parts only when the default checkbox anatomy does not fit the layout. Keep the native input inside Root and use Label to associate the text.
import { Checkbox } from "@smoothie-framework/whisk-react";
<Checkbox.Field>
<Checkbox.Root defaultChecked>
<Checkbox.Input />
<Checkbox.Control>
<Checkbox.Indicator />
</Checkbox.Control>
</Checkbox.Root>
<Checkbox.Label>Enable release notes</Checkbox.Label>
</Checkbox.Field>Forms
Use react-hook-form for registration and validation. register works because Checkbox forwards its ref and native input props.
import { useForm } from "react-hook-form";
import { Box, Button, Checkbox, Field, Stack } from "@smoothie-framework/whisk-react";
type TermsValues = { terms: boolean };
function onSubmit(values: TermsValues) {
// Save values in your application.
}
export function TermsForm() {
const { register, handleSubmit, formState: { errors } } = useForm<TermsValues>();
return (
<Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
<Stack gap={3}>
<Field required invalid={errors.terms !== undefined} error={errors.terms?.message}>
<Checkbox
label="I agree to the terms of service"
required
{...register("terms", { required: "Accept the terms to continue." })}
/>
</Field>
<Button type="submit">Save</Button>
</Stack>
</Box>
);
}Group
Use CheckboxGroup for related independent choices. It supplies the fieldset and legend, and owns the selected value array, name, and required group validation.
import { Checkbox, CheckboxGroup } from "@smoothie-framework/whisk-react";
<CheckboxGroup
label="Notify me about"
description="Choose every type of update you want to receive."
name="notifications"
defaultValue={["releases"]}
>
<Checkbox value="releases" label="Product releases" />
<Checkbox value="security" label="Security notices" />
<Checkbox value="events" label="Community events" />
</CheckboxGroup>Group forms
Use react-hook-form with Controller because CheckboxGroup owns an array through value and onValueChange.
import { Controller, useForm } from "react-hook-form";
import { Box, Button, Checkbox, CheckboxGroup, Stack } from "@smoothie-framework/whisk-react";
type NotificationValues = { notifications: string[] };
function onSubmit(values: NotificationValues) {
// Save values in your application.
}
export function NotificationTopicsForm() {
const { control, handleSubmit } = useForm<NotificationValues>({
defaultValues: { notifications: [] },
});
return (
<Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
<Stack gap={3}>
<Controller
name="notifications"
control={control}
rules={{ validate: (value) => value.length > 0 || "Choose at least one notification." }}
render={({ field, fieldState }) => (
<CheckboxGroup
label="Notify me about"
required
value={field.value}
invalid={fieldState.error !== undefined}
error={fieldState.error?.message}
onValueChange={field.onChange}
>
<Checkbox value="releases" label="Product releases" />
<Checkbox value="security" label="Security notices" />
</CheckboxGroup>
)}
/>
<Button type="submit">Save</Button>
</Stack>
</Box>
);
}Indeterminate
Use indeterminate when a parent control represents a mixture of selected and unselected child items. The application owns that calculation. The state is visual and does not submit a third value.
import { useState } from "react";
import { Checkbox, Stack } from "@smoothie-framework/whisk-react";
const projects = [
{ value: "framework", label: "Framework" },
{ value: "website", label: "Website" },
{ value: "studio", label: "Studio" },
];
export function ProjectSelection() {
const [selected, setSelected] = useState(["framework", "website"]);
const allSelected = selected.length === projects.length;
const someSelected = selected.length > 0 && !allSelected;
return (
<Stack gap={2}>
<Checkbox
label="Select all projects"
checked={allSelected}
indeterminate={someSelected}
onChange={(event) => {
setSelected(event.currentTarget.checked ? projects.map((project) => project.value) : []);
}}
/>
<Stack gap={2} paddingStart={6}>
{projects.map((project) => (
<Checkbox
key={project.value}
label={project.label}
checked={selected.includes(project.value)}
onChange={(event) => {
const checked = event.currentTarget.checked;
setSelected((current) => checked
? [...current, project.value]
: current.filter((value) => value !== project.value));
}}
/>
))}
</Stack>
</Stack>
);
}Description
Add a description when the result of a choice needs explanation.
import { Checkbox } from "@smoothie-framework/whisk-react";
<Checkbox
label="Send security notices"
description="Important account changes are sent to your email."
/>Link
Checkbox labels accept renderable content. Clicking the link follows its destination without toggling the checkbox; keep the link text specific so people can review the related policy.
import { Checkbox, Link } from "@smoothie-framework/whisk-react";
<Checkbox
label={
<>
I agree to the <Link href="/legal/terms" size="sm">terms of service</Link>.
</>
}
/>Props
Component props
Shared props
CheckboxGroup props
Accessibility
Checkbox uses a native checkbox input, so Space toggles it and the browser supplies standard form and keyboard behavior. Give each standalone checkbox a visible label or another accessible name; descriptions add context but do not replace the label. CheckboxGroup renders a fieldset and legend for a related set, so do not wrap it in a single-control Field. Use indeterminate only to communicate an aggregate state and keep it synchronized with the child selections.
Content guidance
Use positive phrasing that states the option being chosen. Add a description only when the consequence needs explanation.