Radio

Base UI Source

A single-select control. The user picks exactly one option with the pointer or the keyboard; the selected radio carries an accent border and a dot that scales in, on a true-circle box that stays round at any radius setting. A real form control — it forwards name / form / required / readOnly and can flag an invalid choice.

Headless basis: Base UI
Internationalization: RTL-safe
Built on: ThemeScope
Consumed by: Filters

Comfortable

Compact

Spacious

Playground

Size

Orientation

Invalid

Basic

Compose Radio.Group (which owns the value) with one Radio.Field per option — each pairing a Radio box with its Radio.Label, the same first-class label idiom as Checkbox. The field wires the label to the box (clicking the label selects it, the label is the accessible name) and holds the box↔label gap; one size on the group sizes every row. Name the group with aria-label (or aria-labelledby), and drive it with value / onValueChange or an uncontrolled defaultValue.

Comfortable

Compact

Spacious

basic.tsx

"use client";

import { Radio } from "@stridge/noctis/radio";
import { useState } from "react";

const OPTIONS = [
    { value: "comfortable", label: "Comfortable" },
    { value: "compact", label: "Compact" },
    { value: "spacious", label: "Spacious" },
];

export default function RadioBasic() {
    const [value, setValue] = useState(OPTIONS[0].value);
    // One `size` on the group sizes every row; each row is a `Radio.Field` pairing the box with its
    // `Radio.Label` (the field wires the label to the box and holds the gap), mirroring `Checkbox.Field`.
    return (
        <Radio.Group aria-label="Density" size="sm" value={value} onValueChange={setValue}>
            {OPTIONS.map((option) => (
                <Radio.Field key={option.value}>
                    <Radio.Root value={option.value} />
                    <Radio.Label>{option.label}</Radio.Label>
                </Radio.Field>
            ))}
        </Radio.Group>
    );
}

Orientation

A group stacks vertically by default; orientation="horizontal" lays it out in a wrapping row. Arrow keys navigate both axes, and the row mirrors under RTL by construction.

List

Board

Calendar

orientation.tsx

"use client";

import { Radio } from "@stridge/noctis/radio";
import { useState } from "react";

const OPTIONS = [
    { value: "list", label: "List" },
    { value: "board", label: "Board" },
    { value: "calendar", label: "Calendar" },
];

// `orientation="horizontal"` lays the group out in a row (wrapping as needed); arrows navigate both axes
// and the row mirrors under RTL by construction.
export default function RadioOrientation() {
    const [value, setValue] = useState("board");
    return (
        <Radio.Group aria-label="View" orientation="horizontal" value={value} onValueChange={setValue}>
            {OPTIONS.map((option) => (
                <Radio.Field key={option.value}>
                    <Radio.Root value={option.value} />
                    <Radio.Label>{option.label}</Radio.Label>
                </Radio.Field>
            ))}
        </Radio.Group>
    );
}

Sizes

size on the group sets the box edge length of every radio — sm for dense rows, md (the default), or lg for cards and touch. The accent dot re-points with it, so it stays proportional.

sizes.tsx

"use client";

import { Radio } from "@stridge/noctis/radio";

const OPTIONS = [
    { value: "weekly", label: "Weekly" },
    { value: "monthly", label: "Monthly" },
];

// One `size` on the group sizes the boxes; the `Radio.Label` text tracks it automatically (mini /
// small / regular for sm / md / lg, the same scale Switch uses) — no per-row text class needed.
const SIZES = ["sm", "md", "lg"] as const;

export default function RadioSizes() {
    return (
        <div className="flex flex-col gap-6">
            {SIZES.map((size) => (
                <Radio.Group key={size} aria-label={`${size} cadence`} size={size} defaultValue="weekly">
                    {OPTIONS.map((option) => (
                        <Radio.Field key={option.value}>
                            <Radio.Root value={option.value} />
                            <Radio.Label>{option.label}</Radio.Label>
                        </Radio.Field>
                    ))}
                </Radio.Group>
            ))}
        </div>
    );
}

Descriptions

Add a Radio.Description per option for helper text, wired to its radio with aria-describedby. Keep the description a sibling of the Radio.Field so it isn't folded into the accessible name.

Starter

1 project, community support.

Pro

Unlimited projects and history.

Team

Shared workspaces and roles.

with-description.tsx

"use client";

import { Radio } from "@stridge/noctis/radio";
import { useState } from "react";

const OPTIONS = [
    { value: "starter", label: "Starter", description: "1 project, community support." },
    { value: "pro", label: "Pro", description: "Unlimited projects and history." },
    { value: "team", label: "Team", description: "Shared workspaces and roles." },
];

// A `Radio.Description` adds helper text per option, wired to its radio with `aria-describedby` (the
// description is a sibling of the label so it isn't folded into the accessible name).
export default function RadioWithDescription() {
    const [value, setValue] = useState("pro");
    return (
        <Radio.Group aria-label="Plan" value={value} onValueChange={setValue}>
            {OPTIONS.map((option) => (
                <div key={option.value} className="flex flex-col">
                    <Radio.Field className="font-medium">
                        <Radio.Root value={option.value} aria-describedby={`${option.value}-desc`} />
                        <Radio.Label>{option.label}</Radio.Label>
                    </Radio.Field>
                    <Radio.Description id={`${option.value}-desc`} className="ms-6">
                        {option.description}
                    </Radio.Description>
                </div>
            ))}
        </Radio.Group>
    );
}

Validation

Mark the group required and flag it invalid to surface a validation error: the danger border paints on every radio and the error message is wired through aria-describedby. Validation fires at submit, not on blur — colour is never the only signal.

invalid.tsx

"use client";

import { Button } from "@stridge/noctis/button";
import { Radio } from "@stridge/noctis/radio";
import { useState } from "react";

const OPTIONS = [
    { value: "email", label: "Email" },
    { value: "sms", label: "SMS" },
    { value: "push", label: "Push" },
];

// `required` applies to the group (Geist), and validation fires at submit. Submit with nothing chosen to
// see the invalid state: the danger border paints on every radio and the error text is wired via
// `aria-describedby`. Reset returns to the empty state so the error is re-testable (a radio can't be
// unselected on its own).
export default function RadioInvalid() {
    const [value, setValue] = useState<string | undefined>(undefined);
    const [submitted, setSubmitted] = useState(false);
    const invalid = submitted && !value;
    return (
        <form
            className="flex flex-col items-start gap-3"
            onSubmit={(event) => {
                event.preventDefault();
                setSubmitted(true);
            }}
        >
            <Radio.Group
                aria-label="Notification channel"
                required
                invalid={invalid}
                value={value}
                onValueChange={setValue}
                aria-describedby={invalid ? "channel-error" : undefined}
            >
                {OPTIONS.map((option) => (
                    <Radio.Field key={option.value}>
                        <Radio.Root value={option.value} />
                        <Radio.Label>{option.label}</Radio.Label>
                    </Radio.Field>
                ))}
            </Radio.Group>
            {invalid ? (
                <p id="channel-error" className="text-small text-danger">
                    Choose a channel to continue.
                </p>
            ) : null}
            <div className="flex gap-2">
                <Button type="submit" size="sm">
                    Continue
                </Button>
                <Button
                    type="button"
                    size="sm"
                    variant="ghost"
                    onClick={() => {
                        setValue(undefined);
                        setSubmitted(false);
                    }}
                >
                    Reset
                </Button>
            </div>
        </form>
    );
}

Cards

Radio.Card is a selectable card: a sharp bordered target wrapping a radio, so the whole card toggles. Selecting it tints the edge to the accent; hover is a neutral surface shift and the focus ring moves to the card. The control sits at the leading edge by default, or the trailing edge via controlPosition.

Starter1 project, community support.ProUnlimited projects and history.TeamShared workspaces and roles.

cards.tsx

"use client";

import { Radio } from "@stridge/noctis/radio";
import { useState } from "react";

const PLANS = [
    { value: "starter", title: "Starter", note: "1 project, community support." },
    { value: "pro", title: "Pro", note: "Unlimited projects and history." },
    { value: "team", title: "Team", note: "Shared workspaces and roles." },
];

// `Radio.Card` is a selectable card: the whole sharp bordered chip is the target, the edge tints to the
// accent when selected, and hover is a neutral surface shift. The group lays the cards out in a wrapping
// row.
export default function RadioCards() {
    const [value, setValue] = useState("pro");
    return (
        <Radio.Group
            aria-label="Plan"
            orientation="horizontal"
            value={value}
            onValueChange={setValue}
            className="max-w-lg w-full"
        >
            {PLANS.map((plan) => (
                <Radio.Card key={plan.value} value={plan.value} className="flex-1 basis-44">
                    <span className="flex flex-col gap-1">
                        <span className="font-medium text-foreground">{plan.title}</span>
                        <Radio.Description>{plan.note}</Radio.Description>
                    </span>
                </Radio.Card>
            ))}
        </Radio.Group>
    );
}

Disabled

Set disabled on a single Radio to lock one option inside an otherwise enabled group — arrow navigation skips it. Set disabled on the whole Radio.Group to dim and lock every option at once.

Credit card

Bank transfer

Invoice

disabled.tsx

"use client";

import { Radio } from "@stridge/noctis/radio";

// A single disabled option inside an otherwise enabled group: arrow navigation skips it, and it can't be
// selected, but the rest of the group works normally.
const OPTIONS = [
    { value: "card", label: "Credit card", disabled: false },
    { value: "transfer", label: "Bank transfer", disabled: true },
    { value: "invoice", label: "Invoice", disabled: false },
];

export default function RadioDisabled() {
    return (
        <Radio.Group aria-label="Payment method" defaultValue="card">
            {OPTIONS.map((option) => (
                // `disabled` on the field dims and locks the label; on the box it stops selection — together
                // the whole row reads as disabled.
                <Radio.Field key={option.value} disabled={option.disabled}>
                    <Radio.Root value={option.value} disabled={option.disabled} />
                    <Radio.Label>{option.label}</Radio.Label>
                </Radio.Field>
            ))}
        </Radio.Group>
    );
}

Standalone

A radio can be named by aria-label instead of visible text — an icon-style picker where the option is self-evident. It is still a group, so arrows and single-select apply.

standalone.tsx

"use client";

import { Radio } from "@stridge/noctis/radio";
import { useState } from "react";

// Standalone, label-less radios: each is named by `aria-label` rather than visible text — for an
// icon-style picker where the option is self-evident. Still a group, so arrows and single-select apply.
export default function RadioStandalone() {
    const [value, setValue] = useState("system");
    return (
        <Radio.Group aria-label="Theme" orientation="horizontal" value={value} onValueChange={setValue}>
            <Radio.Root value="light" aria-label="Light theme" />
            <Radio.Root value="dark" aria-label="Dark theme" />
            <Radio.Root value="system" aria-label="System theme" />
        </Radio.Group>
    );
}

Keyboard

Key	Action
`Tab`	Move focus into the group, landing on the selected radio (or the first); `Tab` again leaves the group.
`←` / `→` / `↑` / `↓`	Move to the next / previous radio and select it (selection follows focus), wrapping at the ends. Arrows mirror under RTL.
`Space`	Select the focused radio.

A disabled option inside an enabled group is skipped by the arrows. A radio group is a single composite tab stop — Tab advances to the next field, not the next radio.

Accessibility

Roles. Radio.Group is a radiogroup (named by aria-label / aria-labelledby / a <legend>); each Radio is a radio, named by its Radio.Label (or an aria-label for a label-less radio). aria-orientation reflects the orientation prop.
Validation. invalid sets aria-invalid on the group; pair it with an error message wired by aria-describedby. The danger border is a reinforcement, never the only signal.
Read-only. A read-only radio stays focusable and announced — reflected visually but never removed from the accessibility tree.
Descriptions. Radio.Description is associated to its radio with aria-describedby (the consumer sets the matching id).
Motion. The dot scales / fades in on select; under prefers-reduced-motion: reduce it appears instantly, meaning preserved.

Anatomy

Compose the control from its parts. Radio.Group is a Base UI RadioGroup, so selection, roving focus, arrow-key navigation, and the form surface (name / form / required / readOnly) come for free.

Radio.Group — the group; owns the selected value (value / onValueChange, or uncontrolled defaultValue), the shared size, and the orientation. Forwards name / form / required / readOnly to Base UI; flag the value in error with invalid; disable everything with disabled.
Radio — one radio box. Pass its value (and optional readOnly / required); it renders the accent dot (Radio.Indicator) for itself when selected.
Radio.Field — the labelled row pairing a box with its label (Base UI's Field.Root), mirroring Checkbox.Field. Inherits the group's size unless it sets its own, and cascades it to the box.
Radio.Label — the box's visible accessible name (Base UI's Field.Label); clicking it selects the box, and it mirrors the field's disabled / invalid state. For a label-less radio (an icon picker), give the Radio an aria-label instead.
Radio.Indicator — the accent dot; kept mounted so it scales in on select. Radio renders it automatically.
Radio.Description — muted helper text for a radio, wired by aria-describedby.
Radio.Card — a selectable card target wrapping a radio, its label, and an optional description.

Every rendered part carries a data-slot (noctis-radio-group, noctis-radio, noctis-radio-indicator, noctis-radio-field, noctis-radio-label, noctis-radio-description, noctis-radio-card) for host-side styling — pair it with the Base UI radio state attributes (data-checked, data-unchecked, data-disabled, data-readonly, data-invalid) and the data-size / data-orientation axes.

On surfaces

The same control re-tuned across the elevation scopes — the root canvas, an elevated panel, a menu, and a sunken well. It stays legible on every layer.

Theme scope

ThemeScope re-tunes a whole region's shape — corner radius, density, and type scale — through the cascade, with no per-component prop and without touching the app-wide theme. Tweak the knobs below and watch every radio inside the scope retune together. See Customization for nesting, reset, and the portal caveat.

RadiusDensityFont scale

Comfortable

Compact

Spacious

theme-scope.tsx

"use client";

import { DENSITY_PRESETS, FONT_SCALE_PRESETS, RADIUS_PRESETS, ThemeScope } from "@stridge/noctis";
import { Radio } from "@stridge/noctis/radio";
import { Select } from "@stridge/noctis/select";
import { useState } from "react";

/** Title-case a preset key for its select label. */
const label = (key: string) => key.charAt(0).toUpperCase() + key.slice(1);

/** One labelled preset picker — its options are a shipped `ThemeScope` preset map, so the playground's
 *  vocab is exactly what the primitive accepts. */
function Knob({
    name,
    presets,
    value,
    onChange,
}: {
    name: string;
    presets: Record<string, number>;
    value: string;
    onChange: (value: string) => void;
}) {
    const keys = Object.keys(presets);
    const items = Object.fromEntries(keys.map((key) => [key, label(key)]));
    return (
        <label className="flex flex-col gap-1.5">
            <span className="text-mini font-medium text-subtle">{name}</span>
            <Select.Root items={items} value={value} onValueChange={(next) => onChange(String(next))}>
                <Select.Trigger aria-label={name} className="w-40">
                    <Select.Value />
                    <Select.Icon />
                </Select.Trigger>
                <Select.Popup>
                    {keys.map((key) => (
                        <Select.Item key={key} value={key}>
                            {label(key)}
                        </Select.Item>
                    ))}
                </Select.Popup>
            </Select.Root>
        </label>
    );
}

/**
 * A live `ThemeScope` playground: the three seed knobs (radius, density, type scale) drive a scope
 * wrapping a radio group, so every control inside re-tunes together — spacing and text size — with no
 * per-radio prop and without touching the app-wide theme. Radio boxes are true circles, so radius has
 * limited visible effect on the box itself; density and font scale are the primary dials here.
 */
export default function RadioThemeScope() {
    const [radius, setRadius] = useState<keyof typeof RADIUS_PRESETS>("pill");
    const [density, setDensity] = useState<keyof typeof DENSITY_PRESETS>("default");
    const [fontScale, setFontScale] = useState<keyof typeof FONT_SCALE_PRESETS>("default");
    const [value, setValue] = useState("comfortable");

    return (
        <div className="flex flex-col gap-5">
            <div className="flex flex-wrap gap-3">
                <Knob name="Radius" presets={RADIUS_PRESETS} value={radius} onChange={(v) => setRadius(v as typeof radius)} />
                <Knob
                    name="Density"
                    presets={DENSITY_PRESETS}
                    value={density}
                    onChange={(v) => setDensity(v as typeof density)}
                />
                <Knob
                    name="Font scale"
                    presets={FONT_SCALE_PRESETS}
                    value={fontScale}
                    onChange={(v) => setFontScale(v as typeof fontScale)}
                />
            </div>

            <div className="rounded-md border border-dashed border-border p-4">
                <ThemeScope radius={radius} density={density} fontScale={fontScale}>
                    <Radio.Group aria-label="Display density" value={value} onValueChange={setValue}>
                        <Radio.Field>
                            <Radio.Root value="comfortable" />
                            <Radio.Label>Comfortable</Radio.Label>
                        </Radio.Field>
                        <Radio.Field>
                            <Radio.Root value="compact" />
                            <Radio.Label>Compact</Radio.Label>
                        </Radio.Field>
                        <Radio.Field>
                            <Radio.Root value="spacious" />
                            <Radio.Label>Spacious</Radio.Label>
                        </Radio.Field>
                    </Radio.Group>
                </ThemeScope>
            </div>
        </div>
    );
}

Design tokens

Generated from the component's declaration — the same graph that mints the CSS, so a variable name or its resolution default can't drift. The minted tokens are the public override seam: set one on any ancestor and every radio in that region retunes — e.g. .dense { --noctis-radio-group-gap: 0.375rem; } tightens the stack beneath it. Knobs that aren't minted are reached through the part's data-slot. See Customization for the full override ladder and Tokens for the whole graph.

TokenResolves toPart

API reference

Generated from the component's types — every prop, type, default, and description comes straight from the source. Each part gets its own table; the Group forwards the Base UI RadioGroup props it owns selection through. Expand a row for the full type and description.

Radio.Group

PropTypeDefault

Radio.Root

PropTypeDefault

Radio.Indicator

PropTypeDefault

Radio.Description

PropTypeDefault

Radio.Card

PropTypeDefault

AttributeDescription

data-slotThe styling/testing hook: the part's stable slot name.

data-sizeSize axis on the radio box — `sm` | `md` | `lg`; re-points the box and dot edges.

data-orientationLayout axis on the group — `vertical` | `horizontal`; switches the row/column flow.

data-checkedPresent on the selected radio box (and its indicator).

data-uncheckedPresent on an unselected radio box.

data-disabledPresent on a disabled radio or group.

data-readonlyPresent on a read-only radio — valid and announced, but not editable.

data-invalidPresent on an invalid radio (and on a group flagged `invalid`); also honours `aria-invalid`.

data-controlOn a `Radio.Card`, where the control sits — `leading` | `trailing`.

data-control-hiddenOn a `Radio.Card` with `hideControl`, marks the dot hidden so the accent edge is the only signal.

Radio

Playground

--noctis-radio-size1.125remroot

--noctis-radio-border-width1pxroot

--noctis-radio-border-radius9999pxroot

--noctis-radio-indicator-size0.5remindicator

--noctis-radio-group-gap0.625remgroup

--noctis-radio-field-gap0.5remfield

--noctis-radio-description-gap0.25remdescription

--noctis-radio-card-padding0.75remcard

Radio.Group

sizeUnion—

orientation"vertical" | "horizontal""vertical"

invalidboolean—

classNamestring—

renderReactElement | function—

styleReact.CSSProperties | function—

Radio.Root

radiusUnion—

densityUnion—

fontScaleUnion—

classNamestring—

renderReactElement | function—

styleReact.CSSProperties | function—

Radio.Indicator

classNamestring—

Radio.Description

styleCSSProperties—

Radio.Card

value*string—

disabledboolean—

readOnlyboolean—

requiredboolean—

controlPosition"leading" | "trailing""leading"

hideControlbooleanfalse

childrenReactNode—

styleCSSProperties—