or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

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

A set of two-state buttons that can be toggled on or off with single and multiple selection modes

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

To install, run

npx @tessl/cli install tessl/npm-radix-ui--react-toggle-group@1.1.0

Radix UI React Toggle Group

Radix UI React Toggle Group is an accessible React component library that provides toggle button groups supporting both single and multiple selection modes. It offers full keyboard navigation, customizable orientations, and maintains proper ARIA attributes while remaining completely unstyled for maximum design flexibility.

Package Information

Package Name: @radix-ui/react-toggle-group
Package Type: npm
Version: 1.1.11
Language: TypeScript
License: MIT
Homepage: https://radix-ui.com/primitives
Installation: npm install @radix-ui/react-toggle-group

Core Imports

import * as ToggleGroup from "@radix-ui/react-toggle-group";

Or with named imports:

import { 
  ToggleGroup,
  ToggleGroupItem,
  Root, 
  Item, 
  ToggleGroupSingleProps, 
  ToggleGroupMultipleProps,
  ToggleGroupItemProps,
  createToggleGroupScope
} from "@radix-ui/react-toggle-group";

Required peer dependencies:

import React from "react";

For type definitions (if using TypeScript):

import type { Scope } from "@radix-ui/react-context";
import type { Primitive } from "@radix-ui/react-primitive";
import type * as RovingFocusGroup from "@radix-ui/react-roving-focus";
import type { Toggle } from "@radix-ui/react-toggle";

For CommonJS:

const ToggleGroup = require("@radix-ui/react-toggle-group");

Basic Usage

import React from "react";
import * as ToggleGroup from "@radix-ui/react-toggle-group";

// Single selection mode
function SingleToggleGroup() {
  const [value, setValue] = React.useState("");
  
  return (
    <ToggleGroup.Root
      type="single"
      value={value}
      onValueChange={setValue}
    >
      <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
      <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
      <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
    </ToggleGroup.Root>
  );
}

// Multiple selection mode
function MultipleToggleGroup() {
  const [value, setValue] = React.useState<string[]>([]);
  
  return (
    <ToggleGroup.Root
      type="multiple"
      value={value} 
      onValueChange={setValue}
    >
      <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
      <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
      <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item>
    </ToggleGroup.Root>
  );
}

Advanced Usage

Using Default Values

// Single selection with default value
function DefaultSingleToggle() {
  return (
    <ToggleGroup.Root
      type="single"
      defaultValue="center"
    >
      <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
      <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
      <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
    </ToggleGroup.Root>
  );
}

// Multiple selection with default values
function DefaultMultipleToggle() {
  return (
    <ToggleGroup.Root
      type="multiple"
      defaultValue={["bold", "italic"]}
    >
      <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
      <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
      <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item>
    </ToggleGroup.Root>
  );
}

Disabled and Configuration Options

function ConfiguredToggleGroup() {
  return (
    <ToggleGroup.Root
      type="single"
      disabled={true}
      orientation="vertical"
      dir="rtl"
      loop={false}
      rovingFocus={false}
    >
      <ToggleGroup.Item value="option1">Option 1</ToggleGroup.Item>
      <ToggleGroup.Item value="option2">Option 2</ToggleGroup.Item>
      <ToggleGroup.Item value="option3" disabled={false}>Option 3 (enabled)</ToggleGroup.Item>
    </ToggleGroup.Root>
  );
}

Horizontal vs Vertical Orientation

// Horizontal toggle group (default)
function HorizontalToggle() {
  return (
    <ToggleGroup.Root type="single" orientation="horizontal">
      <ToggleGroup.Item value="prev">Previous</ToggleGroup.Item>
      <ToggleGroup.Item value="next">Next</ToggleGroup.Item>
    </ToggleGroup.Root>
  );
}

// Vertical toggle group
function VerticalToggle() {
  return (
    <ToggleGroup.Root type="single" orientation="vertical">
      <ToggleGroup.Item value="top">Top</ToggleGroup.Item>
      <ToggleGroup.Item value="middle">Middle</ToggleGroup.Item>
      <ToggleGroup.Item value="bottom">Bottom</ToggleGroup.Item>
    </ToggleGroup.Root>
  );
}

Architecture

The component is built on Radix UI's primitive system with several key integrations:

Context Management: Uses @radix-ui/react-context for internal state sharing
Roving Focus: Integrates @radix-ui/react-roving-focus for keyboard navigation
Toggle Primitives: Built on @radix-ui/react-toggle for individual item behavior
Controllable State: Uses @radix-ui/react-use-controllable-state for controlled/uncontrolled patterns
Directional Support: Integrates @radix-ui/react-direction for RTL/LTR layouts

Accessibility

Radix UI React Toggle Group follows the WAI-ARIA guidelines and provides comprehensive accessibility features:

ARIA Attributes

Toggle Group Container:

Automatically sets role="group" on the root container
Properly manages dir attribute for RTL/LTR support

Single Selection Mode:

Individual items use role="radio" for radio button semantics
Sets aria-checked to indicate selection state
Removes default aria-pressed attribute to avoid conflicts

Multiple Selection Mode:

Individual items use default toggle button semantics with aria-pressed
Multiple items can be selected simultaneously

Keyboard Navigation

Roving Focus (enabled by default):

Arrow keys navigate between toggle items
Tab enters/exits the group
Focus management respects orientation (horizontal/vertical)
loop prop controls whether focus wraps around

Focus Management:

disabled items are excluded from focus sequence
Focus is properly maintained when items are added/removed
Supports custom focus behavior via rovingFocus={false}

Error Handling

The component includes built-in error handling:

Throws clear error when required type prop is missing
Gracefully handles undefined/null values in controlled mode
Maintains consistent state even with invalid configurations

Capabilities

Toggle Group Root Component

Main container component that manages the selection state and provides context to child items.

const ToggleGroup: React.ForwardRefExoticComponent<
  (ToggleGroupSingleProps | ToggleGroupMultipleProps) & React.RefAttributes<ToggleGroupElement>
>;

const Root: typeof ToggleGroup;

Toggle Group Item Component

Individual toggle button that can be pressed/unpressed within the group.

const ToggleGroupItem: React.ForwardRefExoticComponent<
  ToggleGroupItemProps & React.RefAttributes<ToggleGroupItemElement>
>;

const Item: typeof ToggleGroupItem;

Context Scope Creation

Utility function for creating scoped contexts when composing with other Radix components.

const createToggleGroupScope: () => Scope;

Types

Single Selection Props

Props interface for toggle groups that allow only one selected item at a time.

interface ToggleGroupImplSingleProps extends ToggleGroupImplProps {
  /** The controlled stateful value of the item that is pressed */
  value?: string;
  /** The value of the item that is pressed when initially rendered */
  defaultValue?: string;
  /** The callback that fires when the value of the toggle group changes */
  onValueChange?(value: string): void;
}

interface ToggleGroupSingleProps extends ToggleGroupImplSingleProps {
  /** Selection mode - must be 'single' */
  type: 'single';
}

Multiple Selection Props

Props interface for toggle groups that allow multiple selected items simultaneously.

interface ToggleGroupImplMultipleProps extends ToggleGroupImplProps {
  /** The controlled stateful value of the items that are pressed */
  value?: string[];
  /** The value of the items that are pressed when initially rendered */
  defaultValue?: string[];
  /** The callback that fires when the state of the toggle group changes */
  onValueChange?(value: string[]): void;
}

interface ToggleGroupMultipleProps extends ToggleGroupImplMultipleProps {
  /** Selection mode - must be 'multiple' */
  type: 'multiple';
}

Common Implementation Props

Base props shared between single and multiple selection modes.

type RovingFocusGroupProps = React.ComponentPropsWithoutRef<typeof RovingFocusGroup.Root>;
type PrimitiveDivProps = React.ComponentPropsWithoutRef<typeof Primitive.div>;

interface ToggleGroupImplProps extends PrimitiveDivProps {
  /** Whether the group is disabled from user interaction. @defaultValue false */
  disabled?: boolean;
  /** Whether the group should maintain roving focus of its buttons. @defaultValue true */
  rovingFocus?: boolean;
  /** Whether focus should loop from last to first item. @defaultValue true */
  loop?: RovingFocusGroupProps['loop'];
  /** The orientation of the toggle group */
  orientation?: RovingFocusGroupProps['orientation'];
  /** The reading direction of the toggle group */
  dir?: RovingFocusGroupProps['dir'];
}

Toggle Group Item Props

Props interface for individual toggle items within the group.

type ToggleProps = React.ComponentPropsWithoutRef<typeof Toggle>;

interface ToggleGroupItemImplProps extends Omit<ToggleProps, 'defaultPressed' | 'onPressedChange'> {
  /** A string value for the toggle group item. All items within a toggle group should use a unique value */
  value: string;
}

interface ToggleGroupItemProps extends Omit<ToggleGroupItemImplProps, 'pressed'> {}

Element Type Aliases

Type definitions for component element references.

type ToggleGroupImplElement = React.ComponentRef<typeof Primitive.div>;
type ToggleGroupElement = ToggleGroupImplSingleElement | ToggleGroupImplMultipleElement;
type ToggleGroupImplSingleElement = ToggleGroupImplElement;
type ToggleGroupImplMultipleElement = ToggleGroupImplElement;

type ToggleGroupItemImplElement = React.ComponentRef<typeof Toggle>;
type ToggleGroupItemElement = ToggleGroupItemImplElement;

Context Utilities

Context-related types for advanced composition patterns with other Radix components.

type Scope = Record<string, React.Context<any>>;