HyRadioGroup

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

Keyboard Navigation

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

<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

<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

<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

<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

<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

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

Events

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

Slots

• default - The radio buttons to include in this group

Methods

willUpdate()

Generates unique IDs before the first render to prevent update-after-update warnings. IDs are generated client-side only to prevent SSR/client hydration mismatches.

checkValidity()

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

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.

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

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.

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