Radio Group

Select a single option from a list of choices with keyboard navigation and accessibility support.

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { RadioGroup } from "@kunai-consulting/qwik";
import { LuCircle } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);
  const items = Array.from({ length: 4 }, (_, i) => `Item ${i + 1}`);

  return (
    <RadioGroup.Root class="radio-group">
      <RadioGroup.Label class="radio-group-label">Items</RadioGroup.Label>
      {items.map((item, index) => (
        <RadioGroup.Item class="radio-group-item" key={item} value={item}>
          <RadioGroup.Label>{item}</RadioGroup.Label>
          <RadioGroup.Trigger class="radio-group-trigger" value={item}>
            <RadioGroup.Indicator class="radio-group-indicator" value={item}>
              <LuCircle />
            </RadioGroup.Indicator>
          </RadioGroup.Trigger>
        </RadioGroup.Item>
      ))}
    </RadioGroup.Root>
  );
});

//  styles
import styles from "./radio-group.css?inline";

Features

Anatomy

Examples

Basic Usage

The most basic radio group implementation requires a RadioGroup.Root component containing RadioGroup.Item components with their associated values.

import { component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { RadioGroup } from "@kunai-consulting/qwik";
import { LuCircle } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);
  const items = Array.from({ length: 4 }, (_, i) => `Item ${i + 1}`);
  const value = useSignal<string | undefined>("Item 2");

  return (
    <RadioGroup.Root class="radio-group" value={value.value}>
      <RadioGroup.Label class="radio-group-label">Items</RadioGroup.Label>
      {items.map((item, index) => (
        <RadioGroup.Item class="radio-group-item" key={item} value={item}>
          <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
            <RadioGroup.Label>{item}</RadioGroup.Label>
            <RadioGroup.Trigger class="radio-group-trigger" value={item}>
              <RadioGroup.Indicator class="radio-group-indicator" value={item}>
                <LuCircle />
              </RadioGroup.Indicator>
            </RadioGroup.Trigger>
          </div>
        </RadioGroup.Item>
      ))}
    </RadioGroup.Root>
  );
});

//  styles
import styles from "./radio-group.css?inline";

This example demonstrates:

• Using value prop on RadioGroup.Root to set the selected option
• RadioGroup.Label for group identification
• RadioGroup.Trigger and RadioGroup.Indicator for selection interaction
• Individual RadioGroup.Item components with unique values

Error Handling

Radio groups can display error messages when validation fails, such as when no option is selected.

import { $, component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { RadioGroup } from "@kunai-consulting/qwik";
import { LuCircle } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);
  const items = Array.from({ length: 4 }, (_, i) => `Item ${i + 1}`);

  return (
    <div class="flex justify-start">
      <RadioGroup.Root class="radio-group">
        <RadioGroup.Label class="radio-group-label">Items</RadioGroup.Label>
        {items.map((item, index) => (
          <RadioGroup.Item class="radio-group-item" key={item} value={item}>
            <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
              <RadioGroup.Label>{item}</RadioGroup.Label>
              <RadioGroup.Trigger class="radio-group-trigger" value={item}>
                <RadioGroup.Indicator class="radio-group-indicator" value={item}>
                  <LuCircle />
                </RadioGroup.Indicator>
              </RadioGroup.Trigger>
            </div>
          </RadioGroup.Item>
        ))}
        <RadioGroup.ErrorMessage class="error-message-container">
          Error: Please select an item.
        </RadioGroup.ErrorMessage>
      </RadioGroup.Root>
    </div>
  );
});

//  styles
import styles from "./radio-group.css?inline";

This example shows:

• RadioGroup.ErrorMessage component for displaying validation feedback
• Error state automatically managed through the isErrorSig context
• Error message visibility controlled by data-visible attribute
• ARIA attributes automatically updated for accessibility The error message appears when no option is selected and disappears when a selection is made, providing clear feedback to users. Note: The examples available demonstrate core functionality like controlled values and error handling. Additional examples for visual features and advanced usage would typically be included but are not available in the provided example set.

Component State

Using Component State

The Radio Group component provides several ways to manage its state through props on the RadioGroup.Root component.

1. Controlled Value As shown in the controlledValue example above, you can control the selected value using the value prop:

const value = useSignal<string>("Item 2");
<RadioGroup.Root value={value.value}>
  // Radio items
</RadioGroup.Root>

2. Uncontrolled Value You can set an initial uncontrolled value using the defaultValue prop:

<RadioGroup.Root defaultValue="Item 1">
  // Radio items
</RadioGroup.Root>

3. Required State Make the radio group required by setting the required prop:

<RadioGroup.Root required>
  // Radio items
</RadioGroup.Root>

4. Disabled State Disable the entire radio group using the disabled prop:

<RadioGroup.Root disabled>
  // Radio items
</RadioGroup.Root>

State Interactions

1. Handling Selection Changes Listen for selection changes using the onChange$ prop:

<RadioGroup.Root 
  onChange$={(value) => {
    // Handle the new selected value
    console.log('Selected:', value);
  }}
>
  // Radio items
</RadioGroup.Root>

2. Error State As shown in the error example above, the Radio Group automatically manages error states when validation fails. The error state is cleared when a valid selection is made.
3. Description State Enable description support by setting the isDescription prop:

<RadioGroup.Root isDescription>
  <RadioGroup.Description>
    Additional context about the radio group
  </RadioGroup.Description>
  // Radio items
</RadioGroup.Root>

The state management in Radio Group is designed to handle common use cases while maintaining accessibility and providing clear feedback to users through visual indicators and ARIA attributes.

Based on the provided implementation and examples, I'll document the core configuration options for the Radio Group component.

Core Configuration

Value Management

The Radio Group can be configured in both controlled and uncontrolled modes. The value can be managed through the value prop on RadioGroup.Root. As shown in the controlledValue example above, you can control the selected value by passing a value prop:

The value prop accepts a string and determines which radio option is currently selected.

Required Validation

The Radio Group supports required field validation through the required prop on RadioGroup.Root. When enabled, it enforces selection before form submission. As shown in the error example above, the component displays an error message when no option is selected and the field is required.

Description Support

The Radio Group can be configured to display additional descriptive text through the isDescription prop on RadioGroup.Root.

When isDescription is true but no description is provided, a warning will be logged to the console.

Disabled State

The entire Radio Group can be disabled using the disabled prop on RadioGroup.Root. When disabled:

type DisabledConfig = {
  disabled?: boolean; // Disables all radio options when true
}

Event Handling

The Radio Group supports change event handling through the onChange$ prop:

type ChangeHandler = {
  onChange$?: QRL<(checked: string) => void>;
}

This handler is called whenever a radio option is selected, receiving the new value as an argument.

Hidden Input Configuration

For form submission, the component includes a hidden native radio input that can be configured with:

type HiddenInputConfig = {
  name?: string;      // Form field name
  required?: boolean; // Required field validation
  value?: string;     // Current value
}

These configurations ensure proper form integration while maintaining accessibility and native form behavior.

Forms

The Radio Group component includes form integration features through the RadioGroup.HiddenNativeInput component and built-in validation support.

Form Validation

The Radio Group provides built-in validation with error handling through the RadioGroup.ErrorMessage component.

import { $, component$, useSignal, useStyles$ } from "@builder.io/qwik";
import { RadioGroup } from "@kunai-consulting/qwik";
import { LuCircle } from "@qwikest/icons/lucide";

export default component$(() => {
  useStyles$(styles);
  const items = Array.from({ length: 4 }, (_, i) => `Item ${i + 1}`);

  return (
    <div class="flex justify-start">
      <RadioGroup.Root class="radio-group">
        <RadioGroup.Label class="radio-group-label">Items</RadioGroup.Label>
        {items.map((item, index) => (
          <RadioGroup.Item class="radio-group-item" key={item} value={item}>
            <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
              <RadioGroup.Label>{item}</RadioGroup.Label>
              <RadioGroup.Trigger class="radio-group-trigger" value={item}>
                <RadioGroup.Indicator class="radio-group-indicator" value={item}>
                  <LuCircle />
                </RadioGroup.Indicator>
              </RadioGroup.Trigger>
            </div>
          </RadioGroup.Item>
        ))}
        <RadioGroup.ErrorMessage class="error-message-container">
          Error: Please select an item.
        </RadioGroup.ErrorMessage>
      </RadioGroup.Root>
    </div>
  );
});

//  styles
import styles from "./radio-group.css?inline";

In this example, the following form-specific features are demonstrated:

• RadioGroup.ErrorMessage displays validation feedback when no option is selected
• The error message is automatically shown/hidden based on selection state
• The data-visible attribute on RadioGroup.ErrorMessage controls visibility
• Form validation state is managed internally by the component

Form Integration

The component includes a hidden native radio input through RadioGroup.HiddenNativeInput that enables form submission and browser-native validation. Key form integration features:

• The required prop can be passed to RadioGroup.Root to make selection mandatory
• The name prop on RadioGroup.Root sets the form field name
• The value prop determines the submitted form value
• Native form validation is supported through the hidden input The error example above demonstrates these form capabilities working together to provide a complete form field solution. Note: The controlledValue example shows controlled form state management but since it was covered in the state management section, it is not repeated here.