Radio
Overview
The Radio is a form control that lets users select a single option from a set. It is composed of two recipe parts:
useRadioRecipe()— the label wrapper that owns the inline layout (gap, alignment, minimum height), label typography, and dims itself when the field is disabled.useRadioFieldRecipe()— the native styled input, a white SVG dot painted as a background image, and the checked, focus, and disabled states.
The field is the real native input, so every state is driven by the browser: :checked fills the circle with @color.primary, :focus-visible shows a focus ring in @color.focus, and :disabled dims it. The color axis sets the unchecked surface (light, dark, neutral) and the checked fill stays @color.primary across all three.
Radios become mutually exclusive when they share a name attribute — the browser then allows only one selection per group and wires up arrow-key navigation. The recipe is purely presentational; grouping is native.
The Radio 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 radios out as a set, see the Radio Group recipe.
Why use the Radio recipe?
The Radio 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,:disabled,:focus-visible), so the control stays keyboard-accessible and form-associated with zero runtime JavaScript. - Maintain consistency: The checked fill, dot, 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 Radio 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:
import { styleframe } from 'virtual:styleframe';
import { useRadioRecipe, useRadioFieldRecipe } from '@styleframe/theme';
const s = styleframe();
const radio = useRadioRecipe(s);
const radioField = useRadioFieldRecipe(s);
export default s;
Build the component
Put the radio wrapper on the <label> and the radioField circle on the native <input type="radio">. Give every radio in the same set the same name so the browser keeps the selection mutually exclusive:
import { radio, radioField } from "virtual:styleframe";
interface RadioProps {
color?: "light" | "dark" | "neutral";
size?: "sm" | "md" | "lg";
checked?: boolean;
disabled?: boolean;
name?: string;
label?: string;
}
export function Radio({
color = "neutral",
size = "md",
checked = false,
disabled = false,
name,
label,
}: RadioProps) {
return (
<label className={radio({ size })}>
<input
type="radio"
className={radioField({ color, size })}
name={name}
checked={checked}
disabled={disabled}
readOnly
/>
<span>{label}</span>
</label>
);
}
See it in action
Colors
The Radio 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 circle background and border, while the checked 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
| Color | Token | Use Case |
|---|---|---|
light | @color.white / @color.gray-450 | Light surfaces, stays light in dark mode |
dark | @color.gray-900 / @color.gray-500 | Dark surfaces, stays dark in light mode |
neutral | Adaptive (light ↔ dark) | Default color, adapts to the current color scheme |
neutral as your default radio 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 circle dimensions, in rem, and the row's minimum height, which is the minimum height the Open Components standard gives the Input of the same size. The dot is a white SVG background-image sized with background-size: contain, so it stays crisp and scales with the circle. Every size uses a fully rounded border radius (@border-radius.full) so the control renders as a circle.
Size Reference
| Size | Circle Size | Row Min Height | Border Radius |
|---|---|---|---|
sm | 0.875rem | 2rem | @border-radius.full |
md | 1rem | 2.25rem | @border-radius.full |
lg | 1.25rem | 2.5rem | @border-radius.full |
size to the radio wrapper and the radioField circle so the label typography, gap, and circle scale together.States
The field's states ride on native pseudo-classes, so they reflect the real <input> without extra wiring.
Checked
:checked fills the circle with @color.primary and reveals the white SVG dot. Bind the native checked attribute (or v-model / controlled value) as usual, and give radios in the same set a shared name so only one stays selected.
Focus
On :focus-visible, the field draws a 2px solid outline in @color.focus, 2px outside the circle. It's the same ring in every state, invalid included. Press Tab to reach a radio and see it.
Disabled
:disabled dims the circle to 0.5 opacity and switches the cursor to not-allowed; the wrapper dims its label to match via :has(). Forced colors mode can't show opacity, so there the label turns GrayText instead, and the browser draws its own disabled radio. Mirror it with the native disabled attribute so the input is also removed from the tab order.
Anatomy
The Radio is composed of two independent recipes: a label wrapper and the native input circle.
| Part | Recipe | Role |
|---|---|---|
| Wrapper | useRadioRecipe() | The .radio <label> — owns inline layout (gap, alignment, minimum height), label typography, and disabled-label dimming |
| Field | useRadioFieldRecipe() | The .radio-field native <input type="radio"> — owns the circle, dot, color surface, and checked / disabled / focus states |
<label class="radio(...)">
<input type="radio" name="plan" class="radioField(...)" />
<span>Free plan</span>
</label>
The wrapper dims its own label when it contains a disabled field, using :has(.radio-field:disabled), so a disabled radio and its text fade together without extra props.
Accessibility
The Radio recipes do their part of every stylesheet rule on the Open Components Radio Group page, together with the Radio Group recipe. Labels, the legend and the error message are up to the form that uses them.
- Contrast. The label is
@color.text, at least 4.5:1 against the page. The ring of an unchecked radio is at least 3:1 against the page and its own fill in light and dark mode, thelightanddarkcolors included, and so is the@color.primaryfill of a checked one, with its white dot at 3:1 against the fill (WCAG 1.4.3, 1.4.11).radioGroupContrast.test.tschecks every color in both modes. - Checked shape. A checked radio is filled and dotted, so it differs from an unchecked one by more than its color (WCAG 1.4.1).
- Focus. A 2px solid outline with a 2px offset in
@color.focusdraws around the circle on:focus-visible, in every state (WCAG 2.4.7). Thecolor.focustoken defaults to@color.primary, so override it to change the ring of every component at once. - Size and touch. The label is the radio's target. Each size gives it a
min-heightin rem, the standard's Input height for that size, so it's at least 24px tall and grows with larger text or a label that wraps beside the circle. On touch screens (@media (any-pointer: coarse)), each row is at least 44px tall (WCAG 2.5.5). The circle is sized in rem too, and no state changes its size or position. - States. Checked and disabled come from the native
:checkedand:disabled, and invalid from the group'saria-invalid="true"(see Radio Group). The recipes never style:invalid, which matches a required radio before anyone has answered. - Hover. The recipes have no hover style, so a tap on a touch screen never leaves a radio looking hovered. Add one behind the
hover-capablemodifier (&:hover-capable:hover, which emits@media (hover: hover)). - Forced colors and more contrast. Forced colors mode drops the fill, which would leave the white dot on the system's canvas, so the
forced-colorsmodifier hands the circle back to the browser (appearance: auto), which draws its own radio in the user's colors, with aHighlightfocus ring. Withprefers-contrast: more, every unchecked ring is drawn at full strength, in the field'scolor:@color.gray-900on a light surface and@color.whiteon a dark one. - Right to left. The gap sits between the circle and its label, and the field has no margin of its own, so the circle stays before its label in right-to-left layouts.
- Label every radio. Wrap the input and its text in the
<label>, as the wrapper does. The recipe styles the control but does not provide a name. - Group with a shared
name. Radios that share anameform one group: the browser enforces single selection and moves focus between them with the arrow keys. Put the group in a<fieldset>with a<legend>, as the Radio Group recipe does. - Keep the native input. Styling the real
<input type="radio">withappearance: nonepreserves keyboard operation (arrow keys move within the group, Space selects), focus order, and form submission for free. - Mirror
disabledon the input. Set the realdisabledattribute so the radio leaves the tab order and the recipe's:disabledstyles apply.
Customization
Overriding Defaults
Each radio 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 { useRadioFieldRecipe } from '@styleframe/theme';
const s = styleframe();
const radioField = useRadioFieldRecipe(s, {
base: {
borderWidth: '@border-width.medium',
},
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:
import { styleframe } from 'virtual:styleframe';
import { useRadioFieldRecipe } from '@styleframe/theme';
const s = styleframe();
// Only generate the neutral color
const radioField = useRadioFieldRecipe(s, {
filter: {
color: ['neutral'],
},
});
export default s;
API Reference
useRadioRecipe(s, options?)
Creates the radio wrapper recipe — the .radio <label> that lays out the circle and label and dims the label when the nested field is disabled.
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 wrapper |
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 |
|---|---|---|
size | sm, md, lg | md |
useRadioFieldRecipe(s, options?)
Creates the radio field recipe — the .radio-field native <input type="radio"> that owns the circle, SVG dot, surface color, and native states. Accepts the same parameters as useRadioRecipe.
Variants:
| Variant | Options | Default |
|---|---|---|
color | light, dark, neutral | neutral |
size | sm, md, lg | md |
Best Practices
- Pass
sizeto both parts: Spread the samesizeto the wrapper and the field so the label and circle scale together. - Use
neutralfor general forms: The neutral color adapts to light and dark mode automatically, making it the safest default. - Give grouped radios a shared
name: Radios only become mutually exclusive when they share anameattribute — set it on every option in a set. - Group related radios: Use the Radio 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
filteroption to reduce generated CSS.
FAQ
<input type="radio"> with appearance: none keeps the control fully native: arrow keys move between options in the group, Space selects, it participates in form submission, and :checked / :disabled / :focus-visible drive the styling with zero runtime JavaScript. A custom <div> would need ARIA roles and keyboard handlers to match.name attribute. The browser then allows only one selection per name and wires up arrow-key navigation between them. The recipe is presentational — grouping is the native name, not a recipe option.color axis controls the unchecked circle surface, which reflects the form's surface rather than a status. The checked fill is always @color.primary, the conventional accent for a selected control. This mirrors the Input recipe's color model.neutral color sets a dark unchecked surface under &:dark, which gains attribute-selector specificity when you toggle a [data-theme="dark"] theme. To keep the checked circle @color.primary in that case, the recipe re-asserts the fill under &:dark:checked, so the accent always wins over the dark surface.filter option, compound variants that reference filtered-out colors are automatically removed, and default variants are adjusted if they reference a removed value — so the recipe stays consistent and only emits the CSS you use.OTP
A one-time-password / pin input — a row of single-character cells with light, dark, and neutral surface colors, default, soft, and ghost styles, three sizes, and invalid, disabled, and focus states through the recipe system.
Radio Group
A fieldset for a set of radios, with its legend, hint and error message, an invalid state, vertical and horizontal layouts, and three gap sizes through the recipe system.