Search docs

Radio Group

A set of options where only one can be selected.

Radio Group follows the Radio Group WAI-ARIA design pattern (the roving tabindex version).

Plan
import { component$, useStyles$ } from '@builder.io/qwik';
import { RadioGroup } from '@leve-ui/radio-group';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <RadioGroup.Root class="radio-group-default-root">
      <RadioGroup.Label class="radio-group-default-label">Plan</RadioGroup.Label>
      <RadioGroup.Item value="free" class="radio-group-default-item">
        <RadioGroup.Indicator class="radio-group-default-indicator" />
        Free
      </RadioGroup.Item>
      <RadioGroup.Item value="starter" class="radio-group-default-item">
        <RadioGroup.Indicator class="radio-group-default-indicator" />
        Starter
      </RadioGroup.Item>
      <RadioGroup.Item value="pro" class="radio-group-default-item">
        <RadioGroup.Indicator class="radio-group-default-indicator" />
        Pro
      </RadioGroup.Item>
    </RadioGroup.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/radio-group

Anatomy#

import { RadioGroup } from '@leve-ui/radio-group'; // or '@leve-ui/core'

<RadioGroup.Root>
  <RadioGroup.Label />
  <RadioGroup.Item>
    <RadioGroup.Indicator />
  </RadioGroup.Item>
  <RadioGroup.HiddenInput />
</RadioGroup.Root>
PartElementDescription
RadioGroup.Root<div>The group, with role="radiogroup". Holds the selected value.
RadioGroup.Label<span>The label. Names the group.
RadioGroup.Item<button>One option, with role="radio".
RadioGroup.Indicator<span>Holds the dot or other icons. Always rendered.
RadioGroup.HiddenInput<input type="radio">Optional. Sends the selected value with a native <form>.

Examples#

Controlled#

bind:value controls the selected value with a signal. The buttons outside the group change it, and setting it to null clears the selection.

Favorite fruit

Current value: banana

Default Value#

defaultValue sets the initially selected value.

Plan

Disabled#

disabled on the Root disables every item.

Disabled group

Disabled Item#

disabled on an Item disables only that option. Arrow keys skip it.

Shipping method

Horizontal#

orientation="horizontal" lays the group out in a row. It sets aria-orientation and data-orientation.

Payment method

With Field#

Inside a Field, the group uses the Field's IDs, and reads its invalid, disabled and required states. Field.Description and Field.ErrorMessage are linked with aria-describedby. Name the group with RadioGroup.Label, not Field.Label: a <label> cannot name a group.

Shipping
Express arrives in one business day.

With Form#

Add RadioGroup.HiddenInput with name to submit the selected value with a native <form>.

Subscription billing

API Reference#

Root#

PropDefaultType
ids–{ label?: string; root?: string }

Overrides the element IDs of the parts. Inside a Field, the Field's IDs are used instead.

defaultValuenullstring | null

The value selected initially (uncontrolled).

bind:value–Signal<string | null>

A signal with the selected value (controlled).

onValueChange$–QRL<(value: string) => void>

Called when the user selects a value.

orientation'vertical''horizontal' | 'vertical'

The orientation of the group.

looptrueboolean

Whether arrow keys wrap from the last item to the first and vice versa.

disabledfalseboolean

Disables all radio buttons.

requiredfalseboolean

Marks the group as required.

Also accepts all <div> attributes.

Data attributeValue
data-leve-radio-groupAlways present
data-orientation"vertical" | "horizontal"
data-disabledPresent when disabled
data-invalidPresent when the surrounding Field is invalid

The selected value is uncontrolled with defaultValue, or controlled with bind:value. onValueChange$ is called when the user selects a value. orientation only changes aria-orientation and data-orientation: all four arrow keys move the selection in both orientations.

Label#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-radio-group-labelAlways present
data-disabledPresent when the group is disabled

The Label's id comes from the Root. To change it, pass ids={{ label: '...' }} to the Root (an id on the Label is also used, but then pass the same ID to the Root's aria-labelledby). Inside a Field, the Field's label ID is used.

Item#

PropDefaultType
value (required)–string

The value of this radio button.

disabledfalseboolean

Disables this radio button.

Also accepts all <button> attributes.

Data attributeValue
data-leve-radio-group-itemAlways present
data-state"checked" | "unchecked"
data-disabledPresent when the item or the group is disabled
data-orientation"vertical" | "horizontal"

Indicator#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-radio-group-indicatorAlways present
data-state"checked" | "unchecked"
data-disabledPresent when the item or the group is disabled

The indicator is always rendered. Show or hide its contents with CSS, for example [data-leve-radio-group-indicator][data-state="checked"].

HiddenInput#

PropDefaultType
form–string

The id of the form element to associate the input with.

Also accepts all <input> attributes.

Data attributeValue
data-leve-radio-group-hidden-inputAlways present
data-state"checked" when a value is selected, otherwise "unchecked"
data-disabledPresent when the group is disabled

The hidden input holds the selected value and follows the required and disabled states of the Root, so native form submission and required validation work (ADR 0026). It is positioned absolutely with an inline style, so give RadioGroup.Root position: relative.

Accessibility#

Complies with the Radio Group WAI-ARIA design pattern.

  • Name the group with RadioGroup.Label, or aria-label / aria-labelledby on RadioGroup.Root.
  • RadioGroup.Root renders role="radiogroup", aria-orientation, and aria-required / aria-disabled when required or disabled. Inside a Field, it also renders aria-describedby for Field.Description / Field.ErrorMessage and aria-invalid="true" while the Field is invalid.
  • Each RadioGroup.Item is a <button type="button"> with role="radio" and aria-checked. Its text content is its accessible name. Disabled items use the native disabled attribute, so they are not focusable.
  • Only one item is in the tab sequence: the selected item, or the first enabled item when nothing is selected.
  • RadioGroup.Indicator and RadioGroup.HiddenInput are hidden from assistive technologies with aria-hidden="true".

Keyboard Interactions#

KeyDescription
TabMoves focus into the group (to the selected item, or the first enabled item), or out of the group.
SpaceSelects the focused item. Enter does nothing.
ArrowDown / ArrowRightMoves focus to the next enabled item and selects it. Wraps to the first item when loop is true.
ArrowUp / ArrowLeftMoves focus to the previous enabled item and selects it. Wraps to the last item when loop is true.
HomeMoves focus to the first enabled item and selects it.
EndMoves focus to the last enabled item and selects it.