Toggle Group

The Toggle Group component allows you to group multiple toggle buttons together with shared styling and behavior. It supports both single and multiple selection modes, horizontal and vertical orientations, and inherits all the variants from the Toggle component.

Installation

CLI
Manual

npx shadcn@latest add @eo-n/toggle-group

Install dependencies

First, install the required packages:

npm install @base-ui/react class-variance-authority

Copy component code

Make sure you have the Toggle component installed first, then copy and paste the following code into your project at components/ui/toggle-group.tsx:

"use client";

import * as React from "react";
import { ToggleGroup as ToggleGroupRoot } from "@base-ui/react";
import { type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";
import { Toggle, toggleVariants } from "@/components/ui/toggle";

const ToggleGroupContext = React.createContext<
  VariantProps<typeof toggleVariants>
>({
  size: "default",
  variant: "default",
});

function ToggleGroup({
  className,
  variant,
  size,
  children,
  ...props
}: React.ComponentProps<typeof ToggleGroupRoot> &
  VariantProps<typeof toggleVariants>) {
  const contextValue = React.useMemo(
    () => ({
      size: size ?? "default",
      variant: variant ?? "default",
    }),
    [size, variant]
  );

  return (
    <ToggleGroupRoot
      data-slot="toggle-group"
      data-variant={variant}
      data-size={size}
      className={cn(
        "group/toggle-group flex w-fit items-center rounded-md data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[orientation=horizontal]:flex-row data-[orientation=vertical]:flex-col data-[variant=outline]:shadow-xs",
        className
      )}
      {...props}
    >
      <ToggleGroupContext.Provider value={contextValue}>
        {children}
      </ToggleGroupContext.Provider>
    </ToggleGroupRoot>
  );
}

function ToggleGroupItem({
  className,
  children,
  variant,
  size,
  ...props
}: React.ComponentProps<typeof Toggle> & VariantProps<typeof toggleVariants>) {
  const context = React.useContext(ToggleGroupContext);

  return (
    <Toggle
      data-slot="toggle-group-item"
      data-variant={context.variant || variant}
      data-size={context.size || size}
      className={cn(
        toggleVariants({
          variant: context.variant || variant,
          size: context.size || size,
        }),
        "min-w-0 flex-1 shrink-0 rounded-none shadow-none focus:z-10 focus-visible:z-10",
        "group-data-[orientation=horizontal]/toggle-group:first:rounded-l-md group-data-[orientation=vertical]/toggle-group:first:rounded-t-md group-data-[orientation=horizontal]/toggle-group:last:rounded-r-md group-data-[orientation=vertical]/toggle-group:last:rounded-b-md [[data-variant=outline][data-orientation=horizontal]_&]:border-l-0 [[data-variant=outline][data-orientation=horizontal]_&]:first:border-l [[data-variant=outline][data-orientation=vertical]_&]:border-t-0 [[data-variant=outline][data-orientation=vertical]_&]:first:border-t",
        className
      )}
      {...props}
    >
      {children}
    </Toggle>
  );
}

export { ToggleGroup, ToggleGroupItem };

Update imports

Update the import paths to match your project setup.

Usage

Import the toggle group components:

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

<ToggleGroup variant="outline">
  <ToggleGroupItem value="left" aria-label="Left align">
    <AlignLeft />
  </ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Center align">
    <AlignCenter />
  </ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Right align">
    <AlignRight />
  </ToggleGroupItem>
</ToggleGroup>

API Reference

ToggleGroup

The container component that wraps toggle items and manages their state. Props Extends React.ComponentProps<typeof ToggleGroupRoot> from Base UI.

Prop	Type	Default	Description
`variant`	`"default" \| "outline"`	`"default"`	The visual style variant for all items
`size`	`"default" \| "sm" \| "lg"`	`"default"`	The size of all items
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	The layout direction
`multiple`	`boolean`	`false`	Allow multiple items to be pressed
`defaultValue`	`string \| string[]`	-	Default selected value(s)
`value`	`string \| string[]`	-	Controlled selected value(s)
`onValueChange`	`(value: string \| string[]) => void`	-	Callback when selection changes
`disabled`	`boolean`	`false`	Disable all items

ToggleGroupItem

An individual toggle button within the group. Props Extends all Toggle props.

Prop	Type	Description
`value`	`string`	Required unique identifier for the item
`disabled`	`boolean`	Disable this specific item

Examples

Default (Single Selection)

By default, only one item can be selected at a time:

import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupDemo() {
  return (
    <ToggleGroup variant="outline">
      <ToggleGroupItem value="left" aria-label="Left align">
        <AlignLeft />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Center align">
        <AlignCenter />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Right align">
        <AlignRight />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

Multiple Selection

Allow multiple items to be selected simultaneously:

import { Bold, Italic, Underline } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupMultiple() {
  return (
    <ToggleGroup variant="outline" multiple>
      <ToggleGroupItem value="bold" aria-label="Toggle bold">
        <Bold />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic">
        <Italic />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Toggle underline">
        <Underline />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

Vertical Orientation

Stack toggle items vertically:

import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupVertical() {
  return (
    <ToggleGroup variant="outline" orientation="vertical">
      <ToggleGroupItem value="left" aria-label="Left align">
        <AlignLeft />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Center align">
        <AlignCenter />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Right align">
        <AlignRight />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

Sizes

Control the size of all items in the group:

import { Bold, Italic, Underline } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupSmall() {
  return (
    <ToggleGroup variant="outline" size="sm">
      <ToggleGroupItem value="bold">
        <Bold />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic">
        <Italic />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline">
        <Underline />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

Disabled

Disable the entire group or individual items:

import { Bold, Italic, Underline } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupDisabled() {
  return (
    <ToggleGroup variant="outline" disabled>
      <ToggleGroupItem value="bold">
        <Bold />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic">
        <Italic />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline">
        <Underline />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

Controlled

Control the selection state with React state:

import { useState } from "react";
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupControlled() {
  const [value, setValue] = useState("left");

  return (
    <div className="flex flex-col gap-2">
      <ToggleGroup variant="outline" value={value} onValueChange={setValue}>
        <ToggleGroupItem value="left" aria-label="Left align">
          <AlignLeft />
        </ToggleGroupItem>
        <ToggleGroupItem value="center" aria-label="Center align">
          <AlignCenter />
        </ToggleGroupItem>
        <ToggleGroupItem value="right" aria-label="Right align">
          <AlignRight />
        </ToggleGroupItem>
      </ToggleGroup>
      <p className="text-sm text-muted-foreground">
        Selected: {value}
      </p>
    </div>
  );
}

With Text Labels

Combine icons with text for better clarity:

import { Bold, Italic, Underline } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export default function ToggleGroupWithText() {
  return (
    <ToggleGroup variant="outline">
      <ToggleGroupItem value="bold">
        <Bold />
        Bold
      </ToggleGroupItem>
      <ToggleGroupItem value="italic">
        <Italic />
        Italic
      </ToggleGroupItem>
      <ToggleGroupItem value="underline">
        <Underline />
        Underline
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

Variants

Default

Transparent background with subtle hover states:

<ToggleGroup>
  <ToggleGroupItem value="1">Option 1</ToggleGroupItem>
  <ToggleGroupItem value="2">Option 2</ToggleGroupItem>
</ToggleGroup>

Outline

Bordered variant with connected items:

<ToggleGroup variant="outline">
  <ToggleGroupItem value="1">Option 1</ToggleGroupItem>
  <ToggleGroupItem value="2">Option 2</ToggleGroupItem>
</ToggleGroup>

Accessibility

Uses proper ARIA roles and attributes for toggle group pattern
Keyboard navigation with arrow keys between items
Space and Enter keys to toggle items
Clearly indicates pressed state to screen readers
Always include aria-label on icon-only toggle items

Base UI Reference

For more information about the underlying Base UI ToggleGroup component, see the Base UI documentation.

Getting Started

Guides

Form Components

Layout Components

Navigation Components

Overlay Components

Display Components

Utility Components

Installation

Usage

API Reference

ToggleGroup

ToggleGroupItem

Examples

Default (Single Selection)

Multiple Selection

Vertical Orientation

Sizes

Disabled

Controlled

With Text Labels

Variants

Default

Outline

Accessibility

Base UI Reference

Build docs developers (and LLMs) love

Getting Started

Guides

Form Components

Layout Components

Navigation Components

Overlay Components

Display Components

Utility Components

​Installation

​Usage

​API Reference

​ToggleGroup

​ToggleGroupItem

​Examples

​Default (Single Selection)

​Multiple Selection

​Vertical Orientation

​Sizes

​Disabled

​Controlled

​With Text Labels

​Variants

​Default

​Outline

​Accessibility

​Base UI Reference

Build docs developers (and LLMs) love

Installation

Usage

API Reference

ToggleGroup

ToggleGroupItem

Examples

Default (Single Selection)

Multiple Selection

Vertical Orientation

Sizes

Disabled

Controlled

With Text Labels

Variants

Default

Outline

Accessibility

Base UI Reference