Create Next App

Docs

toggle group

A set of two-state buttons that can be toggled on or off.

Installation

Usage

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

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

<ToggleGroup type="single">
  <ToggleGroupItem value="a">A</ToggleGroupItem>
  <ToggleGroupItem value="b">B</ToggleGroupItem>
  <ToggleGroupItem value="c">C</ToggleGroupItem>
</ToggleGroup>

<ToggleGroup type="single">
  <ToggleGroupItem value="a">A</ToggleGroupItem>
  <ToggleGroupItem value="b">B</ToggleGroupItem>
  <ToggleGroupItem value="c">C</ToggleGroupItem>
</ToggleGroup>

Examples

Default

Outline

Single

Small

Large

Disabled

API Reference

ToggleGroup

variant (string, optional, default: 'default'): Visual style variant for the toggles (passed down to items).
size (string, optional): Size variant for the toggles (passed down to items).
type ('single' | 'multiple', optional): Determines selection behavior. 'single' allows only one toggle selected at a time; 'multiple' allows multiple toggles selected.
onValueChange ((value: string) => void, optional): Callback invoked when a toggle item is selected or deselected.
...props (React.HTMLProps<HTMLUListElement>): Additional native props forwarded to the root <ul> element.

Behavior: Renders a group of toggle items as a flex container. Manages internal refs for all toggle items and tracks selected toggles depending on the type (single or multiple). Selection state is synchronized via ARIA attributes and the native checked property on underlying inputs. The onValueChange callback is called with the value of the selected toggle(s). Supports variant and size styling passed down to child toggles.

ToggleGroupItem

variant (string, optional): Visual style variant for the toggle item.
size (string, optional): Size variant for the toggle item.
value (string, required): The unique value identifying this toggle item.
...props (React.ComponentProps<typeof Toggle.Toggle>): Additional props forwarded to the internal Toggle.Toggle component.

Behavior: Represents an individual toggle item inside a ToggleGroup. Receives style and behavior context from the parent group via React context. The item updates the group's selection state on interaction and synchronizes its own checked state and ARIA attributes accordingly. The duck-toggle-group-item attribute is added for targeting.

Toggle Tooltip