Components

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.

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:

src/components/radio.styleframe.ts
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:

src/components/Radio.tsx
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

ColorTokenUse Case
light@color.white / @color.gray-450Light surfaces, stays light in dark mode
dark@color.gray-900 / @color.gray-500Dark surfaces, stays dark in light mode
neutralAdaptive (light ↔ dark)Default color, adapts to the current color scheme
Pro tip: Use 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

SizeCircle SizeRow Min HeightBorder Radius
sm0.875rem2rem@border-radius.full
md1rem2.25rem@border-radius.full
lg1.25rem2.5rem@border-radius.full
Good to know: Pass the same 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.

PartRecipeRole
WrapperuseRadioRecipe()The .radio <label> — owns inline layout (gap, alignment, minimum height), label typography, and disabled-label dimming
FielduseRadioFieldRecipe()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, the light and dark colors included, and so is the @color.primary fill of a checked one, with its white dot at 3:1 against the fill (WCAG 1.4.3, 1.4.11). radioGroupContrast.test.ts checks 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.focus draws around the circle on :focus-visible, in every state (WCAG 2.4.7). The color.focus token 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-height in 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 :checked and :disabled, and invalid from the group's aria-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-capable modifier (&: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-colors modifier hands the circle back to the browser (appearance: auto), which draws its own radio in the user's colors, with a Highlight focus ring. With prefers-contrast: more, every unchecked ring is drawn at full strength, in the field's color: @color.gray-900 on a light surface and @color.white on 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 a name form 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"> with appearance: none preserves keyboard operation (arrow keys move within the group, Space selects), focus order, and form submission for free.
  • Mirror disabled on the input. Set the real disabled attribute so the radio leaves the tab order and the recipe's :disabled styles 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:

src/components/radio.styleframe.ts
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:

src/components/radio.styleframe.ts
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;
Good to know: Filtering also removes compound variants and adjusts default variants that reference filtered-out values, so your recipe stays consistent.

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:

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

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:

VariantOptionsDefault
colorlight, dark, neutralneutral
sizesm, md, lgmd

Learn more about recipes →

Best Practices

  • Pass size to both parts: Spread the same size to the wrapper and the field so the label and circle scale together.
  • Use neutral for 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 a name attribute — 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 filter option to reduce generated CSS.

FAQ