Components

Checkbox

A custom checkbox built on the native input, with a CSS checkmark, checked, indeterminate, disabled, read-only, invalid, and focus states, light, dark, and neutral surface colors, and three sizes through the recipe system.

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, the box's hit area, 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, disabled, read-only, and invalid 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

Register the recipes

Add the Checkbox recipes to a local Styleframe instance. The global styleframe.config.ts provides design tokens and utilities, while the component-level file registers the recipes themselves:

src/components/checkbox.styleframe.ts
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;

Build the component

Put the checkbox wrapper on the <label> and the checkboxField box on the native <input type="checkbox">. The indeterminate state is a DOM property (not an HTML attribute), so set it on the element via a ref:

src/components/Checkbox.tsx
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>
    );
}

See it in action

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

ColorTokenUse Case
light@color.white / @color.gray-450Light surfaces, stays light in dark mode
dark@color.gray-900 / @color.gray-500Dark surfaces, stays dark in light mode
neutralAdaptive (light ↔ dark)Default color, adapts to the current color scheme
Pro tip: Use neutral as your default checkbox color. It adapts to the user's color scheme automatically, so you don't need to manage light and dark surfaces separately.

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

SizeBox SizeHit AreaBorder Radius
sm0.875rem1.5rem@border-radius.sm
md1rem1.5rem@border-radius.sm
lg1.25rem1.5rem@border-radius.md

Sizes are in rem, so the box grows with the text at 200% zoom. Whatever its size, the wrapper draws a 1.5rem hit area around the box with &:before, and pads each label to at least that height, so two stacked checkboxes never share one.

Good to know: Pass the same size to the checkbox wrapper and the checkboxField box so the label typography, gap, and box scale together. Each field size centres the box on the first line of the matching wrapper size's label.

States

Checked, indeterminate and disabled ride on native pseudo-classes, so they follow the real <input> on their own. Read-only and invalid come from the aria-readonly and aria-invalid attributes, which you set on the input, and a read-only box also needs its click cancelled.

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

The :disabled state dims the box to 0.5 opacity and switches the cursor to not-allowed. Inside the wrapper, the wrapper dims the box and its label together via :has(), so the box doesn't dim twice. Mirror it with the native disabled attribute so the input is also removed from the tab order. A <fieldset disabled> disables every checkbox inside it, and they look disabled too, since :disabled matches them.

Read-only

A read-only checkbox shows a choice people can see but not change, like a setting their organisation manages. HTML ignores readonly on a checkbox, and :read-only matches every checkbox, so the recipe styles [aria-readonly="true"] instead: a dashed border, with the fill kept inside it, and a default cursor on the box and its label. Set aria-readonly="true" on the input and cancel the click that would toggle it, which also covers its label and Space:

<label class="checkbox(...)">
    <input type="checkbox" class="checkboxField(...)" checked aria-readonly="true" />
    <span>Email me updates</span>
</label>

<script type="module">
    document.addEventListener("click", (event) => {
        if (event.target.matches('.checkbox-field[aria-readonly="true"]')) event.preventDefault();
    });
</script>

Invalid

The [aria-invalid="true"] attribute draws the border in @color.error, with a second pixel inside the box as an inset shadow, so the box doesn't grow. Set aria-invalid="true" when the error message shows, and link the message with aria-describedby. The recipe never styles :invalid, which matches an unchecked required box before anyone has touched it.

Anatomy

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

PartRecipeRole
WrapperuseCheckboxRecipe()The .checkbox <label> — owns inline layout (gap, alignment), label typography, the 1.5rem hit area, and disabled-label dimming
FielduseCheckboxFieldRecipe()The .checkbox-field native <input type="checkbox"> — owns the box, checkmark, color surface, and checked / indeterminate / disabled / read-only / invalid / focus states
<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

The recipes follow the stylesheet rules of the Open Components Checkbox standard. The rules that need script, like keyboard handling and the read-only click, stay with your component.

  • 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.
  • Focus. The :focus-visible state draws a 2px solid outline in @color.focus, 2px outside the box, the same focus colour every component uses (WCAG 2.4.7). It stays @color.focus when the box is invalid.
  • Contrast. The label uses @color.text at 4.5:1. The unchecked border (@color.gray-450 on light surfaces, @color.gray-500 on dark ones), the @color.primary fill, the white mark on that fill, the @color.error invalid border and the focus ring all have at least 3:1 against what they sit on, in the light and dark themes (WCAG 1.4.11). The checkboxContrast.test.ts test checks every pair, so check the same pairs if you change the tokens.
  • Hit area. The wrapper's &:before adds a 1.5rem square around the box, and a press anywhere in it toggles the box, since it's part of the <label> (WCAG 2.5.8). It's placed with inset-inline-start, so it follows the box in right-to-left text.
  • Size and direction. The box, gap and hit area are in rem. The wrapper aligns the box with the first line of its label, so a long label wraps beside the box rather than being clipped, and the flex layout puts the box at the start of the line in either direction.
  • Distinct marks. Checked shows a check and indeterminate a dash, so the two never rely on colour (WCAG 1.4.1). Set el.indeterminate = true on the element so assistive technology reports "mixed".
  • States. States are styled from the input: :checked, :indeterminate, :disabled, [aria-readonly="true"] through the aria-readonly modifier, and [aria-invalid="true"] through the aria-invalid modifier. No state changes the box's size or position.
  • Hover. The recipes have no hover styles, so a tap never leaves a box looking hovered.
  • More contrast. Under the contrast-more modifier (prefers-contrast: more), the border is drawn at full strength: @color.text for neutral, @color.gray-900 for light and @color.white for dark.
  • Forced colours. Under the forced-colors modifier, a checked or indeterminate box is filled with Highlight, its mark gains a dark outline so it shows on any highlight colour, the focus ring is Highlight, and a disabled box and its label use GrayText instead of an opacity. The read-only box keeps its dashed border. The invalid border's second pixel is a shadow, which forced colours drop, so the error message is what tells people something's wrong there.

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:

src/components/checkbox.styleframe.ts
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:

src/components/checkbox.styleframe.ts
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;
Good to know: Filtering also removes compound variants and adjusts default variants that reference filtered-out values, so your recipe stays consistent.

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:

ParameterTypeDescription
sStyleframeThe Styleframe instance
optionsDeepPartial<RecipeConfig>Optional overrides for the recipe configuration
options.baseVariantDeclarationsBlockCustom base styles for the wrapper
options.variantsVariantsCustom variant definitions for the recipe
options.defaultVariantsRecord<keyof Variants, string>Default variant values for the recipe
options.filterRecord<string, string[]>Limit which variant values are generated

Variants:

VariantOptionsDefault
sizesm, md, lgmd

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:

VariantOptionsDefault
colorlight, dark, neutralneutral
sizesm, md, lgmd

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