Radio Group

v0.5.2

Documentation Under Review

Installation

npm install @pmi/catalyst-radio-group

Default

The Radio Group component is a form control that allows users to select exactly one option from a set of mutually exclusive choices. It provides keyboard navigation, proper focus management, and screen reader support.

With Label

Add a heading label for the entire radio group using aria-labelledby.

With Helper Text

Add helpful information below the radio group using the HelperText component.

With Helper Text (Danger)

Show error messages when validation fails.

Danger State

Apply error styling to the entire radio group.

Disabled State

Disable the entire radio group or individual items.

Size Variants

Radio groups support three sizes: small, medium (default), and large.

Custom Styling

Customize the appearance using custom classes for unique branding or design requirements.

Radio Cards

Create rich card-based selection interfaces where entire cards act as clickable radio buttons.

Radio Cards with Custom Styling

Combine card layouts with custom styling for unique designs.

Settings Panel Configuration

A realistic example showing configuration options in a settings interface.

Form with Validation

Example showing form integration with validation states and error handling.

API Reference

RadioGroupRoot

The root container that manages the radio group state and context.

RadioGroupItem

An individual radio button in the group.

RadioGroupIndicator

Renders when the radio item is checked. Can be styled or contain an icon.

Data Attributes

• [data-state]: "checked" | "unchecked" - Applied to RadioGroupItem
• [data-disabled]: Present when disabled - Applied to RadioGroupItem
• [data-size]: "sm" | "md" | "lg" - Applied to RadioGroupRoot
• [data-danger]: Present when danger=true - Applied to RadioGroupRoot

Accessibility

The Radio Group component implements WCAG 2.1 AA accessibility standards:

• Keyboard Navigation: Arrow keys move between radio buttons, Space selects, Tab moves to next element
• Focus Management: Clear focus indicators on all interactive elements
• Screen Readers: Proper ARIA roles and labels for radio group and items
• Label Association: Labels linked via htmlFor/id for clickable labels
• State Announcement: Checked/unchecked states announced to assistive technology

Best Practices

• Always provide a label for each radio item using the Label component
• Use descriptive labels that clearly indicate the choice
• Link labels to radio items using htmlFor and id attributes
• Add a heading or label for the entire radio group using aria-labelledby
• Use HelperText for additional context or error messages
• Ensure sufficient color contrast in custom styling (4.5:1 for text)
• Test keyboard navigation (arrow keys, space, tab)
• Verify screen reader announcements