or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-radix-ui--react-radio-group

A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@radix-ui/react-radio-group@1.3.x

To install, run

npx @tessl/cli install tessl/npm-radix-ui--react-radio-group@1.3.0

Radix UI React Radio Group

A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time. This package provides a comprehensive and accessible RadioGroup component for React applications with full keyboard navigation support, ARIA compliance, and flexible orientation options.

Package Information

Package Name: @radix-ui/react-radio-group
Package Type: npm
Language: TypeScript
Installation: npm install @radix-ui/react-radio-group

Core Imports

import { RadioGroup, RadioGroupItem, RadioGroupIndicator } from "@radix-ui/react-radio-group";

Alternative import with aliases:

import { Root, Item, Indicator } from "@radix-ui/react-radio-group";

For CommonJS:

const { RadioGroup, RadioGroupItem, RadioGroupIndicator } = require("@radix-ui/react-radio-group");

Basic Usage

import { useState } from "react";
import { RadioGroup, RadioGroupItem, RadioGroupIndicator } from "@radix-ui/react-radio-group";

function PaymentForm() {
  const [paymentMethod, setPaymentMethod] = useState("card");

  return (
    <RadioGroup value={paymentMethod} onValueChange={setPaymentMethod}>
      <div style={{ display: "flex", alignItems: "center" }}>
        <RadioGroupItem value="card" id="card">
          <RadioGroupIndicator />
        </RadioGroupItem>
        <label htmlFor="card">Credit Card</label>
      </div>
      
      <div style={{ display: "flex", alignItems: "center" }}>
        <RadioGroupItem value="paypal" id="paypal">
          <RadioGroupIndicator />
        </RadioGroupItem>
        <label htmlFor="paypal">PayPal</label>
      </div>
      
      <div style={{ display: "flex", alignItems: "center" }}>
        <RadioGroupItem value="bank" id="bank">
          <RadioGroupIndicator />
        </RadioGroupItem>
        <label htmlFor="bank">Bank Transfer</label>
      </div>
    </RadioGroup>
  );
}

Architecture

The RadioGroup component follows Radix UI's compound component pattern:

RadioGroup (Root): Container that manages state, focus, and keyboard navigation using roving focus
RadioGroupItem: Individual selectable radio button with automatic ARIA attributes
RadioGroupIndicator: Visual indicator that appears only when the parent item is selected
Context System: Internal context providers handle state sharing between components
Focus Management: Arrow key navigation with automatic focus management via roving focus
Form Integration: Native HTML form behavior with hidden input elements for form submission

Capabilities

RadioGroup Root Component

The root container that manages radio group state, focus behavior, and keyboard navigation.

interface RadioGroupProps extends React.ComponentPropsWithoutRef<"div"> {
  /**
   * The name of the radio group. Submitted with its owning form as part of a name/value pair.
   */
  name?: string;
  
  /**
   * When true, indicates that the user must select a value before the owning form can be submitted.
   */
  required?: boolean;
  
  /**
   * When true, prevents the user from interacting with radio items.
   */
  disabled?: boolean;
  
  /**
   * The reading direction of the radio group. If omitted, inherits globally from DirectionProvider or assumes LTR (left-to-right) reading mode.
   */
  dir?: "ltr" | "rtl";
  
  /**
   * The orientation of the component.
   */
  orientation?: "horizontal" | "vertical";
  
  /**
   * When true, keyboard navigation will loop from last item to first, and vice versa.
   * @defaultValue true
   */
  loop?: boolean;
  
  /**
   * The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items.
   */
  defaultValue?: string;
  
  /**
   * The controlled value of the radio item to check. Should be used in conjunction with onValueChange.
   */
  value?: string | null;
  
  /**
   * Event handler called when the value changes.
   */
  onValueChange?: (value: string) => void;
}

const RadioGroup: React.ForwardRefExoticComponent<
  RadioGroupProps & React.RefAttributes<HTMLDivElement>
>;

RadioGroupItem Component

Individual radio button component that integrates with the RadioGroup's state management.

interface RadioGroupItemProps extends Omit<React.ComponentPropsWithoutRef<"button">, "onCheck" | "name"> {
  /**
   * The value given as data when submitted with a name.
   */
  value: string;
}

const RadioGroupItem: React.ForwardRefExoticComponent<
  RadioGroupItemProps & React.RefAttributes<HTMLButtonElement>
>;

RadioGroupIndicator Component

Visual indicator component that renders only when its parent RadioGroupItem is in the checked state.

interface RadioGroupIndicatorProps extends React.ComponentPropsWithoutRef<"span"> {
  /**
   * Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
   */
  forceMount?: true;
}

const RadioGroupIndicator: React.ForwardRefExoticComponent<
  RadioGroupIndicatorProps & React.RefAttributes<HTMLSpanElement>
>;

Scope Creation Utility

Advanced utility for creating isolated contexts when composing with other Radix primitives.

/**
 * Creates a scope for RadioGroup context isolation.
 * Used for advanced composition scenarios with other Radix primitives.
 * @returns Scope creation function for context isolation
 */
function createRadioGroupScope(): Scope;

Component Aliases

Alternative exports with shorter names for convenience.

/**
 * Alias for RadioGroup component
 */
const Root: typeof RadioGroup;

/**
 * Alias for RadioGroupItem component
 */
const Item: typeof RadioGroupItem;

/**
 * Alias for RadioGroupIndicator component
 */
const Indicator: typeof RadioGroupIndicator;

Form Integration Example

Proper form integration with name attribute and form submission:

import { useState } from "react";
import { RadioGroup, RadioGroupItem, RadioGroupIndicator } from "@radix-ui/react-radio-group";

function FormExample() {
  const [method, setMethod] = useState("card");

  const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    const formData = new FormData(event.currentTarget);
    console.log('Payment method:', formData.get('paymentMethod'));
  };

  return (
    <form onSubmit={handleSubmit}>
      <RadioGroup 
        name="paymentMethod" 
        value={method} 
        onValueChange={setMethod}
        required
      >
        <div style={{ display: "flex", alignItems: "center" }}>
          <RadioGroupItem value="card" id="card">
            <RadioGroupIndicator />
          </RadioGroupItem>
          <label htmlFor="card">Credit Card</label>
        </div>
        
        <div style={{ display: "flex", alignItems: "center" }}>
          <RadioGroupItem value="paypal" id="paypal">
            <RadioGroupIndicator />
          </RadioGroupItem>
          <label htmlFor="paypal">PayPal</label>
        </div>
      </RadioGroup>
      
      <button type="submit">Submit</button>
    </form>
  );
}

Exported Types

All component prop types are exported for TypeScript usage:

export type {
  RadioGroupProps,
  RadioGroupItemProps,
  RadioGroupIndicatorProps
};

Key Features

Accessibility

Full ARIA compliance with proper roles and attributes
Screen reader support with descriptive announcements
Keyboard navigation using arrow keys
Focus management with visual focus indicators

Keyboard Navigation

Arrow Keys: Navigate between radio items
Tab: Move focus into and out of the radio group
Space: Select the focused radio item
Enter: Prevented (following WAI-ARIA patterns)

State Management

Controlled: Use value and onValueChange props
Uncontrolled: Use defaultValue prop
Automatic state synchronization between items

Form Integration

Native HTML form behavior
Hidden input elements for proper form submission (via internal RadioBubbleInput component)
Support for name attribute and form validation
Event bubbling and form change events

Customization

Flexible styling via CSS classes and data attributes
Support for custom components via asChild pattern (internal)
Animation support through forceMount on indicators
Orientation and direction control