HyRadioGroup

Usage examples on this page are written for Lit / plain HTML (<hy-radio-group>). The same component ships as HyRadioGroup in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A form-associated container component that manages a group of radio buttons as a cohesive unit. Provides centralized state management, keyboard navigation, accessibility features, and form integration via ElementInternals API. Automatically coordinates selection states and ensures only one radio button is selected at a time.

Form Integration

This component implements the Form-Associated Custom Elements API, making it the primary form control for the group. Individual hy-radio components within the group become presentational and do not participate in form submission - the group handles all form integration.

Validation

The component supports native HTML form validation through the required attribute. The validation is enforced during form submission and can be checked programmatically via checkValidity() and reportValidity(). The aria-required attribute is set for assistive technologies. Note: The radio-group itself does not display a visual required indicator (*), but individual radio buttons within the group may show their own required indicators if their required attribute is set.

Disabled State

When disabled, the radio group:

Shows a not-allowed cursor across the entire component area
Prevents all interactions via pointer-events: none on the radio list
Applies --hy-foreground-default-disabled color token to labels and help text
Delegates visual disabled styling (opacity, colors) to child radio buttons

The radio group implements the ARIA radio group pattern with full keyboard support:

Arrow Right/Down: Move to next radio and select it (wraps to first)
Arrow Left/Up: Move to previous radio and select it (wraps to last)
Home: Move to first radio and select it
End: Move to last radio and select it
Space: Select the currently focused radio (if not already selected)

Note: Unlike tab groups, all four arrow keys work in both horizontal and vertical orientations per the WAI-ARIA specification. Arrow navigation automatically selects the newly focused radio button and skips disabled radios.

Examples

Basic usage

html

<form>
  <hy-radio-group name="size" label="Select size" value="medium">
    <hy-radio value="small" label="Small"></hy-radio>
    <hy-radio value="medium" label="Medium"></hy-radio>
    <hy-radio value="large" label="Large"></hy-radio>
  </hy-radio-group>
  <button type="submit">Submit</button>
</form>

Horizontal layout

html

<hy-radio-group
  name="layout"
  label="Choose layout direction"
  orientation="horizontal"
  value="horizontal"
>
  <hy-radio value="horizontal" label="Horizontal"></hy-radio>
  <hy-radio value="vertical" label="Vertical"></hy-radio>
</hy-radio-group>

With validation

html

<hy-radio-group
  name="plan"
  label="Subscription Plan"
  help-text="Choose the plan that best fits your needs"
  required
>
  <hy-radio value="free" label="Free" help-text="Basic features"></hy-radio>
  <hy-radio value="pro" label="Pro ($9.99/month)" help-text="Advanced features"></hy-radio>
  <hy-radio value="enterprise" label="Enterprise" help-text="Full feature set"></hy-radio>
</hy-radio-group>

Disabled group

html

<hy-radio-group
  name="notification"
  label="Notification Settings"
  disabled
  value="email"
  help-text="Settings are currently locked"
>
  <hy-radio value="email" label="Email only"></hy-radio>
  <hy-radio value="sms" label="SMS only"></hy-radio>
  <hy-radio value="both" label="Email and SMS"></hy-radio>
</hy-radio-group>
<!-- When disabled: cursor shows not-allowed, all interactions blocked,
text colors use --hy-foreground-default-disabled token -->

Complete form integration

html

<form>
  <hy-radio-group name="payment" label="Payment Method" required>
    <hy-radio value="credit" label="Credit Card"></hy-radio>
    <hy-radio value="debit" label="Debit Card"></hy-radio>
    <hy-radio value="paypal" label="PayPal"></hy-radio>
  </hy-radio-group>

  <hy-radio-group name="shipping" label="Shipping Speed" value="standard">
    <hy-radio value="standard" label="Standard (5-7 days)"></hy-radio>
    <hy-radio value="express" label="Express (2-3 days)"></hy-radio>
    <hy-radio value="overnight" label="Overnight"></hy-radio>
  </hy-radio-group>
  <button type="submit">Submit</button>
</form>

Programmatic Methods

javascript

const group = document.querySelector('hy-radio-group');

// Set value programmatically
group.value = 'medium';

// Get current value
console.log(group.value); // 'medium'

// Form validation
group.checkValidity();
group.reportValidity();

// Focus management
group.focus(); // Focuses selected or first radio

API

Properties

Property	Attribute	Type	Default	Description
`label`	`label`	`string`	`''`	The label displayed above the radio group.
`helpText`	`help-text`	`string`	`''`	Help text displayed below the radio group to provide additional context.
`name`	`name`	`string`	`''`	The name attribute for form submission.
`value`	`value`	`string`	`''`	The currently selected value in the radio group.
`orientation`	`orientation`	`'horizontal' \| 'vertical'`	`'vertical'`	The visual layout of the radio buttons: 'horizontal' or 'vertical'. `horizontal` collapses back to vertical below a 30rem container width via a container query. Being an inline-size query container, the group fills its container's inline size (`inline-size: 100%`) instead of sizing to its content — in a flex/grid parent, constrain the parent (or the group) rather than expecting shrink-wrap.
`size`	`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	The size of the radio buttons in the group.
`disabled`	`disabled`	`boolean`	`false`	Disables the entire radio group and all radio buttons within it. When disabled: - Cursor changes to not-allowed across the entire component - All interactions are prevented via pointer-events: none - Labels and help text use --hy-foreground-default-disabled color token - Child radio buttons apply their own disabled visual styling
`required`	`required`	`boolean`	`false`	Marks the radio group as required for form validation. Note: The radio-group itself does not display a visual required indicator, but validation is enforced and aria-required is set for assistive technologies.
`invalid`	`invalid`	`boolean`	`false`	Visually marks the group as invalid.
`errorMessage`	`error-message`	`string`	`''`	Error message shown below the radio list when invalid.
`layout`	`layout`	`'block' \| 'inline'`	`'block'`	Row layout: `block` (default) stacks label above the radio list; `inline` puts label on the left and list on the right. Helper/error always sit under the list (col 2–end), never under the label. Set `--hy-radio-group-label-column-width` on a wrapping container so stacked groups align.
`ariaDescribedby`	`aria-describedby`	`string`	`''`	Additional element IDs that describe the radio group for accessibility.
`form`	—	`HTMLFormElement \| null`	—	Returns the form element this radio group is associated with via ElementInternals.
`validity`	—	`ValidityState`	—	Returns the ValidityState object for this radio group via ElementInternals.
`validationMessage`	—	`string`	—	Returns the validation message for this radio group via ElementInternals.

Events

Event	Detail	Description
`change`	—	Fired when the selected radio button changes. Detail: `{ value: string, name: string, reason: StateChangeReason }`
`input`	—	Standard form input event for compatibility

Slots

Slot	Description
`default`	The radio buttons to include in this group

CSS Parts

Part	Description
`base`	The radio group's base wrapper element
`label`	The group label element
`radio-list`	The container for the radio buttons
`help-text`	The help text element
`error-message`	The error message element shown when invalid

CSS Custom Properties

Property	Description
`--hy-radio-group-label-column-width`	Width of the label column in `layout="inline"` mode. No default — set on a wrapping container so stacked groups align.

Methods

checkValidity()

Checks the validity of the radio group against validation constraints. Integrates with native HTML form validation via ElementInternals.

javascript

const group = document.querySelector('hy-radio-group[required]');
if (!group.checkValidity()) {
  console.log('Required radio group has no selection');
}

reportValidity()

Checks the validity of the radio group and shows validation messages if invalid. Triggers the browser's built-in validation UI via ElementInternals.

javascript

const group = document.querySelector('hy-radio-group[required]');
group.reportValidity(); // Shows native validation message if invalid

setCustomValidity()

Sets a custom validation message for the radio group.

Parameters:

message - The custom validation message

javascript

const group = document.querySelector('hy-radio-group');
group.setCustomValidity('Please select a premium option');

focus()

Sets focus on the selected radio button, or the first radio button if none is selected.

javascript

const radioGroup = document.querySelector('hy-radio-group');
radioGroup.focus(); // Focus the selected or first radio button

HyRadioGroup ​

Form Integration ​

Validation ​

Disabled State ​

Keyboard Navigation ​

Examples ​

Basic usage ​

Horizontal layout ​

With validation ​

Disabled group ​

Complete form integration ​

Programmatic Methods ​

API ​

Properties ​

Events ​

Slots ​

CSS Parts ​

CSS Custom Properties ​

Methods ​

checkValidity() ​

reportValidity() ​

setCustomValidity() ​

focus() ​

HyRadioGroup

Form Integration

Validation

Disabled State

Keyboard Navigation

Examples

Basic usage

Horizontal layout

With validation

Disabled group

Complete form integration

Programmatic Methods

API

Properties

Events

Slots

CSS Parts

CSS Custom Properties

Methods

checkValidity()

reportValidity()

setCustomValidity()

focus()