Checkbox

Overview

The Checkbox is a binary form control that lets users toggle an option on or off. It is composed of two recipe parts:

• useCheckboxRecipe() — the label wrapper that owns the inline layout (gap, alignment), label typography, and dims itself when the field is disabled.
• useCheckboxFieldRecipe() — the native styled input, a white SVG checkmark/dash painted as a background image, and the checked, indeterminate, focus, and disabled states.

The field is the real native input, so every state is driven by the browser: :checked and :indeterminate fill the box with @color.primary, :focus-visible shows a focus ring, and :disabled dims it. The color axis sets the unchecked surface (light, dark, neutral) and the checked fill stays @color.primary across all three.

The Checkbox recipes integrate directly with the default design tokens preset and generate type-safe utility classes at build time with zero runtime CSS.

To lay several checkboxes out as a set, see the Checkbox Group recipe.

Why use the Checkbox recipe?

The Checkbox recipe helps you:

• Ship faster with sensible defaults: Get 3 surface colors and 3 sizes out of the box with a single set of composable calls.
• Build on the native input: States ride on native pseudo-classes (:checked, :indeterminate, :disabled, :focus-visible), so the control stays keyboard-accessible and form-associated with zero runtime JavaScript.
• Maintain consistency: The checked fill, checkmark, focus ring, and dark-mode surfaces follow the same design rules everywhere.
• Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
• Stay type-safe: Full TypeScript support means your editor catches invalid color or size values at compile time.
• Integrate with your tokens: Every value references the design tokens preset, so theme changes propagate automatically.

Usage

import { styleframe } from 'virtual:styleframe';
import { useCheckboxRecipe, useCheckboxFieldRecipe } from '@styleframe/theme';

const s = styleframe();

const checkbox = useCheckboxRecipe(s);
const checkboxField = useCheckboxFieldRecipe(s);

export default s;

import { useEffect, useRef } from "react";
import { checkbox, checkboxField } from "virtual:styleframe";

interface CheckboxProps {
    color?: "light" | "dark" | "neutral";
    size?: "sm" | "md" | "lg";
    checked?: boolean;
    indeterminate?: boolean;
    disabled?: boolean;
    label?: string;
}

export function Checkbox({
    color = "neutral",
    size = "md",
    checked = false,
    indeterminate = false,
    disabled = false,
    label,
}: CheckboxProps) {
    const field = useRef<HTMLInputElement>(null);

    useEffect(() => {
        if (field.current) field.current.indeterminate = indeterminate;
    }, [indeterminate]);

    return (
        <label className={checkbox({ size })}>
            <input
                ref={field}
                type="checkbox"
                className={checkboxField({ color, size })}
                checked={checked}
                disabled={disabled}
                readOnly
            />
            <span>{label}</span>
        </label>
    );
}

Colors

The Checkbox field includes 3 color variants: light, dark, and neutral. Like the Input and Card recipes, these are neutral-spectrum surface colors rather than status colors — the color sets the unchecked box background and border, while the checked and indeterminate fill is always @color.primary.

The neutral color adapts automatically: a light surface in light mode and a dark surface in dark mode, making it the safest default for general-purpose forms.

Color Reference

Sizes

Three size variants from sm to lg control the box dimensions and border radius. The checkmark is a white SVG background-image sized with background-size: contain, so it stays crisp and scales with the box.

Size Reference

States

The field's states ride on native pseudo-classes, so they reflect the real <input> without extra wiring.

Checked

:checked fills the box with @color.primary and reveals the white SVG checkmark. Bind the native checked attribute (or v-model / controlled value) as usual.

Indeterminate

:indeterminate fills the box with @color.primary and shows a horizontal dash instead of the checkmark — use it for a "select all" control whose children are partially selected. Indeterminate is a DOM property only, so set el.indeterminate = true on the input via a ref (see Build the component).

Disabled

:disabled dims the box to 0.5 opacity and switches the cursor to not-allowed; the wrapper dims its label to match via :has(). Mirror it with the native disabled attribute so the input is also removed from the tab order.

Anatomy

The Checkbox is composed of two independent recipes: a label wrapper and the native input box.

<label class="checkbox(...)">
    <input type="checkbox" class="checkboxField(...)" />
    <span>Accept terms and conditions</span>
</label>

The wrapper dims its own label when it contains a disabled field, using :has(.checkbox-field:disabled), so a disabled checkbox and its text fade together without extra props.

Accessibility

• Label every checkbox. Wrap the input and its text in the <label> (as the wrapper does) or associate a separate <label for="...">. The recipe styles the control but does not provide a name.
• Keep the native input. Styling the real <input type="checkbox"> with appearance: none preserves keyboard operation (Space toggles), focus order, and form submission for free.
• Set indeterminate on the element. Indeterminate is a visual + accessibility state exposed only as a DOM property; set el.indeterminate = true so assistive technology reports "mixed".
• Mirror disabled on the input. Set the real disabled attribute in addition to the recipe state so the field leaves the tab order.
• Don't rely on color alone. The checked state is conveyed by the checkmark, not just the fill color, satisfying WCAG 1.4.1. Keep the adjacent label text descriptive.
• Verify contrast. The checkmark is @color.white on a @color.primary fill. Default tokens meet WCAG AA; if you override the primary color, verify with the WebAIM Contrast Checker.

Customization

Overriding Defaults

Each checkbox composable accepts an optional second argument to override any part of the recipe configuration. Overrides are deep-merged with the defaults, so you only need to specify the properties you want to change:

import { styleframe } from 'virtual:styleframe';
import { useCheckboxFieldRecipe } from '@styleframe/theme';

const s = styleframe();

const checkboxField = useCheckboxFieldRecipe(s, {
    base: {
        borderRadius: '@border-radius.md',
    },
    defaultVariants: {
        color: 'neutral',
        size: 'lg',
    },
});

export default s;

Filtering Variants

If you only need a subset of the available variants, use the filter option to limit which values are generated. This reduces the output CSS and keeps your component API focused:

import { styleframe } from 'virtual:styleframe';
import { useCheckboxFieldRecipe } from '@styleframe/theme';

const s = styleframe();

// Only generate the neutral color
const checkboxField = useCheckboxFieldRecipe(s, {
    filter: {
        color: ['neutral'],
    },
});

export default s;

API Reference

useCheckboxRecipe(s, options?)

Creates the checkbox wrapper recipe — the .checkbox <label> that lays out the box and label and dims the label when the nested field is disabled.

Parameters:

Variants:

useCheckboxFieldRecipe(s, options?)

Creates the checkbox field recipe — the .checkbox-field native <input type="checkbox"> that owns the box, SVG checkmark, surface color, and native states. Accepts the same parameters as useCheckboxRecipe.

Variants:

Learn more about recipes →

Best Practices

• Pass size to both parts: Spread the same size to the wrapper and the field so the label and box scale together.
• Use neutral for general forms: The neutral color adapts to light and dark mode automatically, making it the safest default.
• Mirror state on the native input: Set the real disabled attribute and the indeterminate DOM property in addition to styling.
• Group related checkboxes: Use the Checkbox Group recipe to lay out a set with consistent spacing.
• Filter what you don't need: If your forms use only the neutral color, pass a filter option to reduce generated CSS.

FAQ