Skip to content
Browse documentation
whisk/ui

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.

Coming from another library?
Use native 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.

Choose whether to receive security notices.
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.

Notify me about
Choose every type of update you want to receive.
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.

Notify me about
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.

Important account changes are sent to your email.
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

PropTypeDefaultDescription
checkedbooleanfalseControl the native checked state. It accepts only true or false; use indeterminate for the mixed presentation.
defaultCheckedbooleanfalseInitialize the native checked state without controlling later changes.
labelReactNodenoneProvide the visible choice name.
descriptionReactNodenoneAdd optional supporting context without replacing the label.
labelPositionstart | endendPlace the label before or after the visual control.
namestringnoneName the checkbox for native form submission.
valuestringonSet the value submitted when the checkbox is checked.
formstringnoneAssociate the checkbox with a native form by ID.
requiredbooleanfalseRequire this checkbox to be checked before native form submission.
indeterminatebooleanfalseShow the host-controlled mixed state. It does not create a third submitted value; checked still owns form submission.
sizesm | md | lgmdChoose the checkbox's visual size.
variantsolid | subtle | outlinesolidChoose the checkbox's visual treatment.
invalidbooleanfalseExpose invalid state. Pair it with Field error text that explains how to fix the problem.
readOnlybooleanfalseKeep a visible value that cannot be changed in the current context.
disabledbooleanfalsePrevent interaction when the choice is unavailable.
onChangenative input change handlernoneHandle a native event and read event.currentTarget.checked. Checkbox has no onCheckedChange prop.
CheckboxGrouprelated componentnoneUse for related independent options. It owns a fieldset, legend, group value/defaultValue array, name, form, and optional at-least-one validation.
Checkbox.Rootcompound partnoneOwn the input and visual control when a custom checkbox anatomy is required.
Checkbox.Inputcompound partnoneRender the native input inside Checkbox.Root.
Checkbox.Controlcompound partnoneRender the visual control around Checkbox.Indicator.
Checkbox.Indicatorcompound partnoneRender the checked and mixed-state glyphs inside Checkbox.Control.
Checkbox.Fieldcompound partnoneAssociate a Checkbox.Root and Checkbox.Label in the established field layout.
Checkbox.Labelcompound partnoneRender a label associated with the Checkbox.Input in its sibling Root.

Shared props

PropSupportedNotes
as / asChildNoCheckbox owns its native input and visual control structure.
Style propsNoCheckbox exposes semantic form and appearance props instead of the shared style-prop surface. See Style props.
className / styleYesApplied to the visual checkbox root.
refYesForwards to the native input.
Native HTML attributesYesNative input attributes are forwarded, except Checkbox-owned type, checked state, and ARIA attributes.

CheckboxGroup props

PropTypeDefaultDescription
labelReactNodenoneName the related set of independent choices.
descriptionReactNodenoneAdd supporting context for the whole group.
valuereadonly string[]noneControl the selected item values. Do not provide defaultValue at the same time.
defaultValuereadonly string[]noneInitialize selected item values without controlling later changes.
onValueChange(value: string[]) => voidnoneReceive the next selected item values after an item changes.
namestringgenerated group IDName every grouped checkbox for native form submission.
formstringnoneAssociate the group with a native form by ID.
requiredbooleanfalseRequire at least one enabled choice before native form submission.
orientationvertical | horizontalverticalChoose the visual arrangement of grouped choices.
errorReactNodenoneShow validation feedback when the group is invalid.
invalidbooleanfalseExpose invalid state and associate the error message when present.
disabledbooleanfalsePrevent interaction with every item in the group.
readOnlybooleanfalseKeep the group visible without allowing its selected values to change.

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.

PropDoDon't
labellabel="Email me updates"label="Don't email me"