Radio Group

v0.6.0

Ready for Production

Catalyst Radio Group extends Radix UI's Radio Group primitive with built-in CVA variants, design tokens, and accessible keyboard navigation — giving you a production-ready single-choice selector with zero configuration.

Installation

npm install @pmi/catalyst-radio-group

import { RadioGroupRoot, RadioGroupItem, RadioGroupIndicator } from '@pmi/catalyst-radio-group';

Variants

Danger

Apply the danger prop to RadioGroupRoot to show an error state across the entire group.

Disabled

Pass disabled to RadioGroupRoot to prevent interaction on all radio items.

Sizes

Three sizes are available — sm, md (default), and lg — controlled via the size prop on RadioGroupRoot.

Common Patterns

With Label

Use aria-labelledby on RadioGroupRoot to associate a visible heading with the group for screen readers.

With Helper Text

Pair with the HelperText component to provide additional context below the group.

With Helper Text (Danger)

Combine danger helper text with a validation-failed state to surface error messages clearly.

Form with Validation

Use controlled state alongside danger and HelperText to build a validated form field.

Product Variant

npm install @pmi/catalyst-radio-group

import { RadioGroupRoot, RadioGroupItem, RadioGroupIndicator } from '@pmi/catalyst-radio-group';

API Reference

Radio Group is a compound component built on Radix UI primitives. The sections below summarize the shared API surface for each part of the component.

RadioGroupRoot

The container component that manages state, size, and danger context for all child items.

Accepts all standard Radix Radio Group Root props and forwards ref to the underlying element.

RadioGroupItem

An individual radio button within the group. Must be a descendant of RadioGroupRoot.

Accepts all standard Radix Radio Group Item props and forwards ref.

RadioGroupIndicator

Renders the filled dot inside the radio item when it is in the checked state.

Accepts all standard Radix Radio Group Indicator props and forwards ref.

Accessibility

Radio Group is designed to meet WCAG 2.2 AA standards. The sections below document keyboard behavior and ARIA semantics.

Keyboard Interactions

ARIA

• RadioGroupRoot renders with role="radiogroup". Always provide aria-label or aria-labelledby to name the group for screen readers.
• Each RadioGroupItem renders with role="radio" and aria-checked ("true" / "false").
• Disabled items receive aria-disabled="true" and data-disabled, preventing pointer interaction automatically via data-[disabled]:pointer-events-none.
• HelperText with details or error messages associated with the radio group should have an id that matches the aria-describedby of the RadioGroupRoot. Use an appropriate role ("status" / "alert") or aria-live pattern for announcing dynamically displayed success/error messages.

See the Radix Radio Group accessibility docs for inherited baseline behavior.

Choosing the Right Component

Use Radio Group when users must pick exactly one option from a small set of visible choices. Reach for a different component when:

Related

• Checkbox
• Select
• Label
• Helper Text
• Radio Cards