Components

Checkbox Group

A fieldset that groups a set of checkboxes under a legend, with shared orientation and spacing. Supports vertical and horizontal layouts, three sizes and a select-all box through the recipe system.

Overview

The Checkbox Group is a layout component that arranges related checkboxes into a single, consistently spaced set, named by its legend. The useCheckboxGroupRecipe() composable creates a fully configured recipe with orientation and size options for a <fieldset> that stacks checkboxes vertically or lays them out in a wrapping row.

The Checkbox Group recipe integrates directly with the Checkbox recipe and generates type-safe utility classes at build time with zero runtime CSS.

Why use the Checkbox Group recipe?

The Checkbox Group recipe helps you:

  • Lay out sets consistently: Stack checkboxes vertically or wrap them in a row with a single orientation prop.
  • Control spacing with one axis: The size variant sets the gap between rows, the legend's size and the select-all indent, so a whole group scales together.
  • Compose, don't couple: The group handles layout, its legend and its group-wide states, while each child checkbox keeps its own color, size, and state.
  • Stay type-safe: Full TypeScript support means your editor catches invalid orientation or size values at compile time.

Usage

Register the recipe

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

src/components/checkbox-group.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import {
    useCheckboxRecipe,
    useCheckboxFieldRecipe,
    useCheckboxGroupRecipe,
} from '@styleframe/theme';

const s = styleframe();

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

export default s;

Build the component

Import the checkboxGroup runtime function from the virtual module, put it on a <fieldset>, and name the group with a <legend>:

src/components/CheckboxGroup.tsx
import { checkboxGroup } from "virtual:styleframe";

interface CheckboxGroupProps {
    orientation?: "vertical" | "horizontal";
    size?: "sm" | "md" | "lg";
    legend: string;
    children?: React.ReactNode;
}

export function CheckboxGroup({
    orientation = "vertical",
    size = "md",
    legend,
    children,
}: CheckboxGroupProps) {
    const classes = checkboxGroup({ orientation, size });

    return (
        <fieldset className={classes}>
            <legend>{legend}</legend>
            {children}
        </fieldset>
    );
}

See it in action

Orientation

The Checkbox Group supports two orientation variants that control the layout direction.

Vertical

The default orientation. Checkboxes are stacked top-to-bottom in a column — the most common layout for option lists.

Horizontal

Checkboxes are laid out in a wrapping row, aligned to the center, with @1.5 (24px) between the options of a row, so it's clear which label each box belongs to. Useful for two or three short options that fit inline.

Orientation Reference

OrientationDirectionNotes
verticalTop to bottom (column)Default; one option per line
horizontalInline direction (row, wraps)Center-aligned, @1.5 between options, wraps to the next line when out of space

Sizes

Three size variants set the gap between rows, the legend's size and the select-all indent, letting you tighten or loosen a group to match its surroundings. Set the same size on each child checkbox so the controls and the spacing scale together.

SizeRow gapLegendSelect-all indent
sm@0.5@font-size.xs0.875rem + @0.375
md@0.75@font-size.sm1rem + @0.5
lg@1@font-size.md1.25rem + @0.625

The legend is the same size as the options' text in the Checkbox recipe of the same size, in @font-weight.semibold, and the indent is that checkbox's box and gap.

Good to know: The group's size doesn't reach its checkboxes. Pass the same size to each child <Checkbox> so the boxes, the legend and the spacing scale as a set.

Parts and states

The group styles the parts of its fieldset from the setup callback, since they're plain elements:

PartSelectorStyle
Legend.checkbox-group > legend@font-weight.semibold, @color.text, sized per group size
Select all.checkbox-group > [data-slot="select-all"]A line of its own
Options.checkbox-group > [data-slot="options"]The group's direction and gaps, and the indent after a select-all box

Select all

Wrap a select-all checkbox in [data-slot="select-all"], and the options after it in [data-slot="options"]. The options sit in from it by its box and gap, on the inline-start side, so their boxes line up with its label. Keep its checked and mixed state in step with the options from your component.

Invalid

While the group has an error message, set aria-invalid="true" on the fieldset, describe it with the message, and set aria-invalid="true" on each checkbox too, so each one reads invalid. Every box takes the checkbox's invalid border, @color.error doubled by a 1px inset shadow, so no box grows, and the group's attribute alone is enough for the look. The focus ring keeps @color.focus.

Disabled

Disable the fieldset, and the browser disables every checkbox in it. Each checkbox dims itself and its label, and the group dims its legend to match.

Accessibility

The Checkbox Group recipe does its part of every stylesheet rule on the Open Components Checkbox Group page, together with the Checkbox recipes, which cover the checkboxes themselves: the box, the marks, focus, target size, forced colors and more contrast. The legend's question, the error message and when it shows are up to the form that uses it.

  • Contrast. The legend is @color.text, at least 4.5:1 against the page in light and dark mode (WCAG 1.4.3). The contrast test, checkboxGroupContrast.test.ts, checks it, and the invalid border's 3:1 against the page and every box color, in both modes.
  • Layout. Options run in a column by default, at least 8px apart, and a horizontal row puts 24px between its options and wraps rather than overflowing. Options under a select-all box sit in from it by its box and gap.
  • Fit the column. The fieldset's minimum width is reset to 0, and the legend, gaps and indent are in rem, so a long legend or a row of options wraps instead of overflowing at 200% zoom.
  • Disabled state. A <fieldset disabled> matches :disabled, which dims the legend to 50% opacity, and in forced colors mode turns it GrayText at full opacity. Each checkbox dims itself from its own :disabled.
  • Invalid state. The group's aria-invalid="true" gives every box the @color.error border, through the border and an inset shadow, never the focus ring, which stays @color.focus. The recipe never styles :invalid, which matches a required box before anyone has touched it.
  • Stable size. No state changes the group's size or position: disabled changes the legend's opacity, and invalid adds an inset shadow rather than a wider border.
  • Right to left. The group lays its checkboxes out with flexbox and gap, and indents with padding-inline-start, so a row and the indent follow dir.
  • Name the group with a <legend>. Put the recipe on a <fieldset> and ask the question in its first child, a <legend>, so assistive technology announces it with each checkbox.
  • Keep each checkbox labelled. Every child still needs its own label (see the Checkbox recipe).

Customization

Overriding Defaults

The useCheckboxGroupRecipe() 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-group.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import { useCheckboxGroupRecipe } from '@styleframe/theme';

const s = styleframe();

const checkboxGroup = useCheckboxGroupRecipe(s, {
    defaultVariants: {
        orientation: 'horizontal',
        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-group.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import { useCheckboxGroupRecipe } from '@styleframe/theme';

const s = styleframe();

// Only generate the vertical orientation
const checkboxGroup = useCheckboxGroupRecipe(s, {
    filter: {
        orientation: ['vertical'],
    },
});

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

useCheckboxGroupRecipe(s, options?)

Creates a checkbox group recipe for a <fieldset>, with orientation and size variants.

Parameters:

ParameterTypeDescription
sStyleframeThe Styleframe instance
optionsDeepPartial<RecipeConfig>Optional overrides for the recipe configuration
options.baseVariantDeclarationsBlockCustom base styles for the group
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
orientationvertical, horizontalvertical
sizesm, md, lgmd

Learn more about recipes →

Best Practices

  • Pair with the Checkbox recipe: The group handles layout; each child should use the Checkbox recipe for consistent controls.
  • Match sizes: Use the same size on the group and its child checkboxes so spacing and boxes scale together.
  • Keep groups scannable: Prefer vertical layout for longer option lists; reserve horizontal for two or three short options.
  • Label the set: Always describe the group's purpose with a <legend>, so screen readers communicate the relationship between options.

FAQ