Radio Group
Overview
The Radio Group arranges related radios into a single, consistently spaced set. The useRadioGroupRecipe() composable creates a fully configured recipe with orientation and size options for a <fieldset> — a flex container that stacks radios vertically or lays them out in a wrapping row. It resets the fieldset's border, padding and margin, and styles its <legend>, a hint (data-slot="hint") and an error message (data-slot="error").
Single selection comes from the native input: give every child radio the same name, and the browser enforces one choice per group and wires up arrow-key navigation. The <legend> names the group, and aria-invalid="true" on the fieldset turns every radio's ring red while the group has an error.
The Radio Group recipe integrates directly with the Radio recipe and generates type-safe utility classes at build time with zero runtime CSS.
Why use the Radio Group recipe?
The Radio Group recipe helps you:
- Lay out sets consistently: Stack radios vertically or wrap them in a row with a single orientation prop.
- Style the whole question: The legend, hint and error message get their typography and contrast from the recipe.
- 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 handles layout and the invalid state; each child radio 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 Radio Group recipe to a local Styleframe instance alongside the radio 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 {
useRadioRecipe,
useRadioFieldRecipe,
useRadioGroupRecipe,
} from '@styleframe/theme';
const s = styleframe();
const radio = useRadioRecipe(s);
const radioField = useRadioFieldRecipe(s);
const radioGroup = useRadioGroupRecipe(s);
export default s;
Build the component
Import the radioGroup runtime function from the virtual module and put it on a <fieldset> around your radios, with a <legend> that asks the question. Give every child radio the same name. Give the fieldset role="radiogroup", named by its legend through aria-labelledby. While the group has an error, set aria-invalid="true" on it and link the message with aria-describedby:
import { useId } from "react";
import { radioGroup } from "virtual:styleframe";
interface RadioGroupProps {
orientation?: "vertical" | "horizontal";
size?: "sm" | "md" | "lg";
legend: string;
error?: string;
children?: React.ReactNode;
}
export function RadioGroup({
orientation = "vertical",
size = "md",
legend,
error,
children,
}: RadioGroupProps) {
const id = useId();
const classes = radioGroup({ orientation, size });
return (
<fieldset
className={classes}
role="radiogroup"
aria-labelledby={`${id}-legend`}
aria-invalid={error ? "true" : undefined}
aria-describedby={error ? `${id}-error` : undefined}
>
<legend id={`${id}-legend`}>{legend}</legend>
{children}
{error && (
<p id={`${id}-error`} data-slot="error">
{error}
</p>
)}
</fieldset>
);
}
See it in action
Orientation
The Radio Group supports two orientation variants that control the layout direction.
Vertical
The default orientation. Radios are stacked top-to-bottom in a column — the most common layout for option lists.
Horizontal
Radios are laid out left-to-right in a wrapping row, aligned to the center. Useful for short option sets that fit inline.
Orientation Reference
| Orientation | Direction | Notes |
|---|---|---|
vertical | Top to bottom (column) | Default; one option per line |
horizontal | Left to right (row, wraps) | Center-aligned, wraps to the next line when out of space. The hint and error message take a row of their own |
Sizes
Three size variants control the gap between radios, letting you tighten or loosen a group to match its surroundings. Set the same size on each child radio so the controls and the spacing scale together.
| Size | Gap |
|---|---|
sm | @0.5 |
md | @0.75 |
lg | @1 |
size controls only the gap between items. Pass the same size to each child <Radio> so the circles 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 | .radio-group > legend | @font-size.sm, @font-weight.medium, @color.text |
| Hint | .radio-group > [data-slot="hint"] | @font-size.sm, @color.text-weak |
| Error message | .radio-group > [data-slot="error"] | @font-size.sm, @color.error, and @color.error-400 in dark mode |
Hint
A hint for the whole group sits under the legend. Link it to the fieldset with aria-describedby.
Invalid
While the group has an error message, set aria-invalid="true" on the fieldset and describe it with the message. Every radio's ring turns @color.error, a checked one's too, doubled by a 1px inset shadow, so no circle grows. The focus ring keeps @color.focus.
Disabled
Disable the fieldset, and the browser disables every radio in it. Each radio dims itself and its label.
Accessibility
The Radio Group recipe does its part of every stylesheet rule on the Open Components Radio Group page, together with the Radio recipes, which cover the radios themselves: the ring, the dot, focus, target size, forced colors and more contrast. The legend's question, the error message's text and when it shows are up to the form that uses it.
- Contrast. The legend is
@color.textand the hint@color.text-weak, both at least 4.5:1 against the page in light and dark mode. The error message is@color.error, and@color.error-400in dark mode, where@color.errorfalls short of 4.5:1 (WCAG 1.4.3).radioGroupContrast.test.tschecks them in both modes. - Invalid state. The group's
aria-invalid="true"turns every ring@color.error, at least 3:1 against the page, through the border and an inset shadow, never the focus ring, which stays@color.focus. The recipe never styles:invalid, which matches a required group before anyone has answered it. - Stable size. No state changes a radio's size or position: invalid adds an inset shadow rather than a wider border.
- Fit the column. The fieldset's minimum width is reset to
0, so a long legend or label wraps instead of overflowing a narrow column. - Right to left. The group lays its radios out with flexbox and
gap, so a horizontal group runs from right to left in right-to-left layouts. - Name the group with a
<legend>. Put the recipe on a<fieldset>withrole="radiogroup", and ask the question in its<legend>, linked witharia-labelledby, so assistive technology announces it with each radio and can reportaria-invalid. - Share a
nameacross children. Single selection and arrow-key navigation come from giving every child radio the samename. - Keep each radio labelled. Every child still needs its own label (see the Radio recipe).
Customization
Overriding Defaults
The useRadioGroupRecipe() 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 { useRadioGroupRecipe } from '@styleframe/theme';
const s = styleframe();
const radioGroup = useRadioGroupRecipe(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 { useRadioGroupRecipe } from '@styleframe/theme';
const s = styleframe();
// Only generate the vertical orientation
const radioGroup = useRadioGroupRecipe(s, {
filter: {
orientation: ['vertical'],
},
});
export default s;
API Reference
useRadioGroupRecipe(s, options?)
Creates a radio group recipe — a flex <fieldset> with orientation and size (gap) variants, and the styles for its legend, hint, error message and invalid state.
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 Radio recipe: The group handles layout; each child should use the Radio recipe for consistent controls.
- Share a
name: Give every child radio the samenameso the set behaves as one mutually-exclusive group. - Match sizes: Use the same
sizeon the group and its child radios so spacing and circles scale together. - Keep groups scannable: Prefer vertical layout for longer option lists; reserve horizontal for two or three short options.
- Label the set: Always ask the group's question in a
<legend>so screen readers communicate the relationship between options.
FAQ
name and the browser enforces one choice per group. Pass the same size to the group and its children if you want the spacing and the circles to scale together.horizontal for short sets of two or three options that read well inline. It lays the radios out in a centered, wrapping row. For longer option lists, the default vertical orientation is easier to scan.<fieldset> with a <legend> is the grouping every browser and screen reader understands, and disabling it disables every radio. On another element, add role="radiogroup" and name it with aria-labelledby.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.Radio
A custom radio built on the native input, with a CSS dot indicator, checked, disabled, and focus states, light, dark, and neutral surface colors, and three sizes through the recipe system.
Select
A multi-select form control composed of a trigger, a floating listbox panel, selectable options, dismissable value chips, a chevron indicator, group labels, and separators. Supports light, dark, and neutral colors, per-part visual styles, and three sizes through the recipe system.