Checkbox Group

Overview

The Checkbox Group is a layout component that arranges related checkboxes into a single, consistently spaced set. The useCheckboxGroupRecipe() composable creates a fully configured recipe with orientation and size options — a flex container 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 items, so a whole group scales together.
• Compose, don't couple: The group only handles layout; 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

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;

import { checkboxGroup } from "virtual:styleframe";

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

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

    return (
        <div className={classes} role="group">
            {children}
        </div>
    );
}

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 left-to-right in a wrapping row, aligned to the center. Useful for short option sets that fit inline.

Orientation Reference

Sizes

Three size variants control the gap between checkboxes, 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.

Accessibility

• Group related options. Wrap the checkboxes in an element with role="group" and an aria-label (or aria-labelledby) describing the set, so assistive technology announces the context.
• Prefer a fieldset for forms. When the group is part of a form, a native <fieldset> with a <legend> is the most robust grouping — apply the recipe class to the fieldset.
• Keep each checkbox labelled. The group provides layout only; 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 — a flex container with orientation and size (gap) variants.

Parameters:

Variants:

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 aria-label or a <legend> so screen readers communicate the relationship between options.

FAQ