Checkbox Group
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:
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>:
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
| Orientation | Direction | Notes |
|---|---|---|
vertical | Top to bottom (column) | Default; one option per line |
horizontal | Inline 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.
| Size | Row gap | Legend | Select-all indent |
|---|---|---|---|
sm | @0.5 | @font-size.xs | 0.875rem + @0.375 |
md | @0.75 | @font-size.sm | 1rem + @0.5 |
lg | @1 | @font-size.md | 1.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.
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:
| Part | Selector | Style |
|---|---|---|
| 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 inrem, 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 itGrayTextat full opacity. Each checkbox dims itself from its own:disabled. - Invalid state. The group's
aria-invalid="true"gives every box the@color.errorborder, 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 withpadding-inline-start, so a row and the indent followdir. - 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:
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:
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;
API Reference
useCheckboxGroupRecipe(s, options?)
Creates a checkbox group recipe for a <fieldset>, with orientation and size variants.
Parameters:
| Parameter | Type | Description |
|---|---|---|
s | Styleframe | The Styleframe instance |
options | DeepPartial<RecipeConfig> | Optional overrides for the recipe configuration |
options.base | VariantDeclarationsBlock | Custom base styles for the group |
options.variants | Variants | Custom variant definitions for the recipe |
options.defaultVariants | Record<keyof Variants, string> | Default variant values for the recipe |
options.filter | Record<string, string[]> | Limit which variant values are generated |
Variants:
| Variant | Options | Default |
|---|---|---|
orientation | vertical, horizontal | vertical |
size | sm, md, lg | md |
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
sizeon 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
color and size. Pass the same size to the group and its children if you want the boxes, the legend and the spacing to scale together.horizontal for short sets of two or three options that read well inline. It lays the checkboxes out in a centered, wrapping row, 24px apart. For longer option lists, the default vertical orientation is easier to scan.<fieldset>. The recipe resets the fieldset's border, padding and margin, and styles its <legend> and its disabled state, which only a fieldset has. A <div> needs role="group" and an aria-labelledby to be announced as a group.filter option, variant values you exclude are not generated, and default variants are adjusted if they reference a removed value — so the recipe stays consistent and only emits the CSS you use.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.
Color Picker
A color selection control composed of a saturation/value selector square, a vertical hue track, and shared draggable thumbs. Renders any color through a CSS variable and gradients, with five sizes through the recipe system.