Toggle Group

Group of toggles with single or multiple selection.

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

export function ToggleGroupDemo() {
  return (
    <ToggleGroup defaultValue={['open']} variant="outline" spacing={0} aria-label="Case status">
      <ToggleGroupItem value="all">All</ToggleGroupItem>
      <ToggleGroupItem value="open">Open</ToggleGroupItem>
      <ToggleGroupItem value="waiting">Waiting for resident</ToggleGroupItem>
      <ToggleGroupItem value="closed">Closed</ToggleGroupItem>
    </ToggleGroup>
  )
}

Installation

pnpm dlx shadcn@latest add https://rdf.dev.360online.com/r/toggle-group.json

Installs to @/components/ui/toggle-group.

Manual installation

Install the dependencies:

pnpm add @base-ui/react@^1.8.0 class-variance-authority@^0.7.1

Add the components it builds on: toggle.

Copy the source into your project:

components/ui/toggle-group.tsx

'use client'

import { Toggle as TogglePrimitive } from '@base-ui/react/toggle'
import { ToggleGroup as ToggleGroupPrimitive } from '@base-ui/react/toggle-group'
import type { VariantProps } from 'class-variance-authority'
import * as React from 'react'
import { toggleVariants } from '@/components/ui/toggle'
import { cn } from '@/lib/utils'

const ToggleGroupContext = React.createContext<
	VariantProps<typeof toggleVariants> & {
		spacing?: number
		orientation?: 'horizontal' | 'vertical'
	}
>({
	size: 'default',
	variant: 'default',
	spacing: 2,
	orientation: 'horizontal',
})

function ToggleGroup({
	className,
	variant,
	size,
	spacing = 2,
	orientation = 'horizontal',
	children,
	...props
}: ToggleGroupPrimitive.Props &
	VariantProps<typeof toggleVariants> & {
		spacing?: number
		orientation?: 'horizontal' | 'vertical'
	}) {
	const contextValue = React.useMemo(
		() => ({ variant, size, spacing, orientation }),
		[variant, size, spacing, orientation],
	)

	return (
		<ToggleGroupPrimitive
			data-slot="toggle-group"
			data-variant={variant}
			data-size={size}
			data-spacing={spacing}
			data-orientation={orientation}
			orientation={orientation}
			style={{ '--gap': spacing } as React.CSSProperties}
			className={cn(
				'group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] rounded-lg data-[size=sm]:rounded-[min(var(--radius-md),10px)] data-vertical:flex-col data-vertical:items-stretch',
				className,
			)}
			{...props}
		>
			<ToggleGroupContext.Provider value={contextValue}>{children}</ToggleGroupContext.Provider>
		</ToggleGroupPrimitive>
	)
}

function ToggleGroupItem({
	className,
	children,
	variant = 'default',
	size = 'default',
	...props
}: TogglePrimitive.Props & VariantProps<typeof toggleVariants>) {
	const context = React.useContext(ToggleGroupContext)

	return (
		<TogglePrimitive
			data-slot="toggle-group-item"
			data-variant={context.variant || variant}
			data-size={context.size || size}
			data-spacing={context.spacing}
			className={cn(
				'shrink-0 group-data-[spacing=0]/toggle-group:rounded-none group-data-[spacing=0]/toggle-group:px-2 focus:z-10 focus-visible:z-10 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-end]:pr-1.5 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-start]:pl-1.5 group-data-horizontal/toggle-group:data-[spacing=0]:first:rounded-l-lg group-data-vertical/toggle-group:data-[spacing=0]:first:rounded-t-lg group-data-horizontal/toggle-group:data-[spacing=0]:last:rounded-r-lg group-data-vertical/toggle-group:data-[spacing=0]:last:rounded-b-lg group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:border-l-0 group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:border-t-0 group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-l group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-t',
				toggleVariants({
					variant: context.variant || variant,
					size: context.size || size,
				}),
				className,
			)}
			{...props}
		>
			{children}
		</TogglePrimitive>
	)
}

export { ToggleGroup, ToggleGroupItem }

A set of two-state buttons that can be toggled on or off. Built on the Base UI ToggleGroup primitive with single or multiple selection modes.

Features

Single (default) or multiple selection
Built on the Base UI ToggleGroup primitive for accessibility
Shares styling with the Toggle component (toggleVariants)
variant and size set on the group are inherited by every item
spacing prop controls the gap between items; spacing={0} joins items into a segmented control
Horizontal and vertical orientation
Icon spacing via data-icon="inline-start" / data-icon="inline-end"
Controlled and uncontrolled modes
Individual item or group-wide disabled states

Usage

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

// Single selection
<ToggleGroup defaultValue={["left"]}>
  <ToggleGroupItem value="left" aria-label="Align left">
    <AlignLeft />
  </ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center">
    <AlignCenter />
  </ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Align right">
    <AlignRight />
  </ToggleGroupItem>
</ToggleGroup>

// Multiple selection, segmented outline
<ToggleGroup multiple variant="outline" spacing={0}>
  <ToggleGroupItem value="bold">
    <Bold data-icon="inline-start" />
    Bold
  </ToggleGroupItem>
  <ToggleGroupItem value="italic">
    <Italic data-icon="inline-start" />
    Italic
  </ToggleGroupItem>
</ToggleGroup>

// Vertical
<ToggleGroup orientation="vertical">
  ...
</ToggleGroup>

Examples

Default

A joined (spacing={0}) outline group filtering cases by status. Give the group an aria-label so the set has a name.

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

export function ToggleGroupDemo() {
  return (
    <ToggleGroup defaultValue={['open']} variant="outline" spacing={0} aria-label="Case status">
      <ToggleGroupItem value="all">All</ToggleGroupItem>
      <ToggleGroupItem value="open">Open</ToggleGroupItem>
      <ToggleGroupItem value="waiting">Waiting for resident</ToggleGroupItem>
      <ToggleGroupItem value="closed">Closed</ToggleGroupItem>
    </ToggleGroup>
  )
}

Single Selection

By default one item can be pressed. The value is always an array, so a single selection is value={[language]}. Here it picks the language of a decision letter; ignoring the empty array in onValueChange keeps one option always selected.

<ToggleGroup value={[language]} onValueChange={(value) => value[0] && setLanguage(value[0])}>
  …
</ToggleGroup>

import { useState } from 'react'
import { Label } from '@/components/ui/label'
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'

export function ToggleGroupSingleSelection() {
  const [language, setLanguage] = useState('sv')
  const greetings: Record<string, string> = {
    en: 'Decision on your application for a parking permit',
    sv: 'Beslut om din ansökan om parkeringstillstånd',
    fi: 'Päätös pysäköintilupahakemuksestasi',
    no: 'Vedtak om din søknad om parkeringstillatelse',
  }
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Label id="toggle-group-language">Language of the decision letter</Label>
      <ToggleGroup
        variant="outline"
        size="sm"
        value={[language]}
        onValueChange={(value) => value[0] && setLanguage(value[0])}
        aria-labelledby="toggle-group-language"
      >
        <ToggleGroupItem value="en">English</ToggleGroupItem>
        <ToggleGroupItem value="sv">Svenska</ToggleGroupItem>
        <ToggleGroupItem value="fi">Suomi</ToggleGroupItem>
        <ToggleGroupItem value="no">Norsk</ToggleGroupItem>
      </ToggleGroup>
      <p lang={language} className="rounded-lg bg-muted p-3 text-sm font-medium">
        {greetings[language]}
      </p>
    </div>
  )
}

Multiple Selection

multiple lets any number of items be pressed – the weekdays for home help visits. Each short label has a full aria-label.

import { useState } from 'react'
import { Label } from '@/components/ui/label'
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'

export function ToggleGroupMultipleSelection() {
  const days = [
    { value: 'mon', short: 'M', label: 'Monday' },
    { value: 'tue', short: 'T', label: 'Tuesday' },
    { value: 'wed', short: 'W', label: 'Wednesday' },
    { value: 'thu', short: 'T', label: 'Thursday' },
    { value: 'fri', short: 'F', label: 'Friday' },
    { value: 'sat', short: 'S', label: 'Saturday' },
    { value: 'sun', short: 'S', label: 'Sunday' },
  ]
  const [selected, setSelected] = useState(['mon', 'wed', 'fri'])
  return (
    <div className="flex flex-col gap-3">
      <Label id="toggle-group-days">Home help visit days</Label>
      <ToggleGroup
        multiple
        variant="outline"
        spacing={1}
        value={selected}
        onValueChange={setSelected}
        aria-labelledby="toggle-group-days"
      >
        {days.map((day) => (
          <ToggleGroupItem key={day.value} value={day.value} aria-label={day.label} className="w-9">
            {day.short}
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
      <p className="text-sm text-muted-foreground">{selected.length} visits per week · Ingrid Hansen, Storgatan 14</p>
    </div>
  )
}

Variants

default and outline, set once on the group and inherited by every item.

import { BoldIcon, ItalicIcon, UnderlineIcon } from 'lucide-react'
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'

export function ToggleGroupVariants() {
  return (
    <div className="grid grid-cols-[auto_auto] items-center gap-x-6 gap-y-4">
      <span className="text-sm font-medium">Default</span>
      <ToggleGroup multiple defaultValue={['bold']} aria-label="Formatting (default variant)">
        <ToggleGroupItem value="bold" aria-label="Bold">
          <BoldIcon />
        </ToggleGroupItem>
        <ToggleGroupItem value="italic" aria-label="Italic">
          <ItalicIcon />
        </ToggleGroupItem>
        <ToggleGroupItem value="underline" aria-label="Underline">
          <UnderlineIcon />
        </ToggleGroupItem>
      </ToggleGroup>
      <span className="text-sm font-medium">Outline</span>
      <ToggleGroup multiple variant="outline" defaultValue={['bold']} aria-label="Formatting (outline variant)">
        <ToggleGroupItem value="bold" aria-label="Bold">
          <BoldIcon />
        </ToggleGroupItem>
        <ToggleGroupItem value="italic" aria-label="Italic">
          <ItalicIcon />
        </ToggleGroupItem>
        <ToggleGroupItem value="underline" aria-label="Underline">
          <UnderlineIcon />
        </ToggleGroupItem>
      </ToggleGroup>
    </div>
  )
}

Sizes

sm, default and lg.

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

export function ToggleGroupSizes() {
  return (
    <div className="flex flex-col items-center gap-4">
      {(['sm', 'default', 'lg'] as const).map((size) => (
        <ToggleGroup
          key={size}
          variant="outline"
          size={size}
          spacing={0}
          defaultValue={['week']}
          aria-label={`Calendar view (${size})`}
        >
          <ToggleGroupItem value="day">Day</ToggleGroupItem>
          <ToggleGroupItem value="week">Week</ToggleGroupItem>
          <ToggleGroupItem value="month">Month</ToggleGroupItem>
        </ToggleGroup>
      ))}
    </div>
  )
}

Spacing

spacing={0} joins the items into a segmented control; any other value is the gap in spacing units.

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

export function ToggleGroupSpacing() {
  return (
    <div className="grid grid-cols-[auto_auto] items-center gap-x-6 gap-y-4">
      <span className="text-sm text-muted-foreground">
        <code>spacing={'{0}'}</code>
      </span>
      <ToggleGroup variant="outline" spacing={0} defaultValue={['q2']} aria-label="Quarter (joined)">
        <ToggleGroupItem value="q1">Q1</ToggleGroupItem>
        <ToggleGroupItem value="q2">Q2</ToggleGroupItem>
        <ToggleGroupItem value="q3">Q3</ToggleGroupItem>
        <ToggleGroupItem value="q4">Q4</ToggleGroupItem>
      </ToggleGroup>
      <span className="text-sm text-muted-foreground">
        <code>spacing={'{2}'}</code>
      </span>
      <ToggleGroup variant="outline" spacing={2} defaultValue={['q2']} aria-label="Quarter (spaced)">
        <ToggleGroupItem value="q1">Q1</ToggleGroupItem>
        <ToggleGroupItem value="q2">Q2</ToggleGroupItem>
        <ToggleGroupItem value="q3">Q3</ToggleGroupItem>
        <ToggleGroupItem value="q4">Q4</ToggleGroupItem>
      </ToggleGroup>
    </div>
  )
}

Vertical

orientation="vertical" stacks the items – here as a filter for e-service areas, with counts.

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

export function ToggleGroupVertical() {
  return (
    <div className="flex flex-col gap-2">
      <Label id="toggle-group-category">Service area</Label>
      <ToggleGroup
        orientation="vertical"
        spacing={1}
        defaultValue={['care']}
        aria-labelledby="toggle-group-category"
        className="w-52"
      >
        {[
          { value: 'all', label: 'All e-services', count: 86 },
          { value: 'school', label: 'School and preschool', count: 14 },
          { value: 'care', label: 'Care and support', count: 21 },
          { value: 'housing', label: 'Building and housing', count: 18 },
          { value: 'environment', label: 'Environment', count: 9 },
        ].map((item) => (
          <ToggleGroupItem key={item.value} value={item.value} className="justify-between">
            {item.label}
            <span className="text-xs text-muted-foreground tabular-nums">{item.count}</span>
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
    </div>
  )
}

With Icon and Text

Icons with data-icon="inline-start" next to text labels, for choosing how a decision is delivered.

import { InboxIcon, MailIcon, SendIcon } from 'lucide-react'
import { Label } from '@/components/ui/label'
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'

export function ToggleGroupWithIconAndText() {
  return (
    <div className="flex flex-col gap-3">
      <Label id="toggle-group-delivery">How do you want to receive the decision?</Label>
      <ToggleGroup
        variant="outline"
        defaultValue={['mailbox']}
        aria-labelledby="toggle-group-delivery"
        className="flex-wrap"
      >
        <ToggleGroupItem value="mailbox">
          <InboxIcon data-icon="inline-start" />
          Digital mailbox
        </ToggleGroupItem>
        <ToggleGroupItem value="email">
          <MailIcon data-icon="inline-start" />
          Email
        </ToggleGroupItem>
        <ToggleGroupItem value="post">
          <SendIcon data-icon="inline-start" />
          Letter by post
        </ToggleGroupItem>
      </ToggleGroup>
    </div>
  )
}

View Modes

Icon-only items switching between list, grid and map views of municipal facilities.

import { LayoutGridIcon, ListIcon, MapIcon } from 'lucide-react'
import { useState } from 'react'
import { Badge } from '@/components/ui/badge'
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'

const facilities = [
  { name: 'Central library', address: 'Kungsgatan 3', status: 'Open until 20:00' },
  { name: 'Ekdalen sports hall', address: 'Idrottsvägen 8', status: 'Open until 22:00' },
  { name: 'Norrby recycling centre', address: 'Industrivägen 21', status: 'Closed today' },
  { name: 'Citizen Service Centre', address: 'Storgatan 14', status: 'Open until 16:30' },
]

export function ToggleGroupViewModes() {
  const [view, setView] = useState('list')
  return (
    <div className="flex w-full max-w-lg flex-col gap-3">
      <div className="flex items-center justify-between gap-4">
        <h3 className="text-sm font-medium">Municipal facilities near you</h3>
        <ToggleGroup
          size="sm"
          variant="outline"
          spacing={0}
          value={[view]}
          onValueChange={(value) => value[0] && setView(value[0])}
          aria-label="View"
        >
          <ToggleGroupItem value="list" aria-label="List">
            <ListIcon />
          </ToggleGroupItem>
          <ToggleGroupItem value="grid" aria-label="Grid">
            <LayoutGridIcon />
          </ToggleGroupItem>
          <ToggleGroupItem value="map" aria-label="Map">
            <MapIcon />
          </ToggleGroupItem>
        </ToggleGroup>
      </div>
      {view === 'map' ? (
        <div className="flex h-44 flex-col items-center justify-center gap-2 rounded-lg bg-linear-to-br from-primary/10 to-chart-2/20 text-sm text-muted-foreground">
          <MapIcon className="size-6" aria-hidden />
          Map of 4 facilities
        </div>
      ) : (
        <ul className={view === 'grid' ? 'grid grid-cols-2 gap-2' : 'flex flex-col divide-y rounded-lg border'}>
          {facilities.map((facility) => (
            <li
              key={facility.name}
              className={
                view === 'grid'
                  ? 'flex flex-col gap-1 rounded-lg border p-3 text-sm'
                  : 'flex items-center justify-between gap-4 px-3 py-2 text-sm'
              }
            >
              <div>
                <p className="font-medium">{facility.name}</p>
                <p className="text-muted-foreground">{facility.address}</p>
              </div>
              <Badge variant="secondary" className={view === 'grid' ? 'mt-1' : undefined}>
                {facility.status}
              </Badge>
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

Rating

A five-point satisfaction scale with icon-only items and a live text label for the current choice.

import { AngryIcon, FrownIcon, LaughIcon, MehIcon, SmileIcon } from 'lucide-react'
import { useState } from 'react'
import { Label } from '@/components/ui/label'
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'

export function ToggleGroupRating() {
  const [rating, setRating] = useState('')
  const options = [
    { value: '1', label: 'Very dissatisfied', icon: AngryIcon },
    { value: '2', label: 'Dissatisfied', icon: FrownIcon },
    { value: '3', label: 'Neutral', icon: MehIcon },
    { value: '4', label: 'Satisfied', icon: SmileIcon },
    { value: '5', label: 'Very satisfied', icon: LaughIcon },
  ]
  const current = options.find((option) => option.value === rating)
  return (
    <div className="flex flex-col items-center gap-3 text-center">
      <Label id="toggle-group-rating">How satisfied are you with the library's e-service?</Label>
      <ToggleGroup
        size="lg"
        value={rating ? [rating] : []}
        onValueChange={(value) => setRating(value[0] ?? '')}
        aria-labelledby="toggle-group-rating"
      >
        {options.map(({ value, label, icon: Icon }) => (
          <ToggleGroupItem key={value} value={value} aria-label={label}>
            <Icon className="size-5" />
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
      <p className="h-5 text-sm text-muted-foreground" aria-live="polite">
        {current ? current.label : 'Choose an option'}
      </p>
    </div>
  )
}

Disabled

Disable the whole group with disabled on ToggleGroup, or single items with disabled on ToggleGroupItem.

import { InboxIcon, SendIcon } from 'lucide-react'
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'

export function ToggleGroupDisabled() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex flex-col gap-2">
        <span className="text-sm text-muted-foreground">Whole group disabled</span>
        <ToggleGroup variant="outline" spacing={0} defaultValue={['week']} disabled aria-label="Calendar view">
          <ToggleGroupItem value="day">Day</ToggleGroupItem>
          <ToggleGroupItem value="week">Week</ToggleGroupItem>
          <ToggleGroupItem value="month">Month</ToggleGroupItem>
        </ToggleGroup>
      </div>
      <div className="flex flex-col gap-2">
        <span className="text-sm text-muted-foreground">One item disabled</span>
        <ToggleGroup variant="outline" defaultValue={['mailbox']} aria-label="Delivery method">
          <ToggleGroupItem value="mailbox">
            <InboxIcon data-icon="inline-start" />
            Digital mailbox
          </ToggleGroupItem>
          <ToggleGroupItem value="post" disabled>
            <SendIcon data-icon="inline-start" />
            Letter by post
          </ToggleGroupItem>
        </ToggleGroup>
      </div>
    </div>
  )
}

Props

ToggleGroup

multiple?: boolean - Whether several items can be pressed at once (default false)
value?: string[] - Controlled values of the pressed items (always an array, also for single selection)
defaultValue?: string[] - Default values for uncontrolled mode
onValueChange?: (value: string[], eventDetails) => void - Callback when selection changes
loopFocus?: boolean - Whether arrow keys wrap from the last item to the first (default true)
variant?: "default" | "outline" - Visual style applied to all items
size?: "sm" | "default" | "lg" - Size applied to all items
spacing?: number - Gap between items in spacing units (default 2; 0 joins items)
orientation?: "horizontal" | "vertical" - Layout direction (default "horizontal")
disabled?: boolean - Whether the entire group is disabled
Extends all Base UI ToggleGroup props

ToggleGroupItem

value: string - Unique identifier for the item (required)
variant?: "default" | "outline" - Used when the group does not set a variant
size?: "sm" | "default" | "lg" - Used when the group does not set a size
disabled?: boolean - Whether this specific item is disabled
Extends all Base UI Toggle props

Styling

Items use toggleVariants from @/components/ui/toggle. The group exposes data-variant, data-size, data-spacing and data-orientation attributes, and items expose data-slot="toggle-group-item", so you can target them with Tailwind data selectors:

<ToggleGroup className="rounded-lg bg-muted p-1">
  <ToggleGroupItem value="a" className="data-pressed:bg-background">A</ToggleGroupItem>
  <ToggleGroupItem value="b" className="data-pressed:bg-background">B</ToggleGroupItem>
</ToggleGroup>

Accessibility

Built on the Base UI ToggleGroup primitive with full keyboard support
Roving focus: Tab moves into and out of the group, arrow keys move between items
Space / Enter toggle the focused item
Home / End move to the first / last item
Provide an aria-label on icon-only items, and on the group when its purpose is not obvious

Best Practices

Selection Modes
- Use the default single selection for mutually exclusive options (radio-like behavior)
- Use multiple for independent toggles that can be combined
Labeling
- Always provide meaningful aria-label attributes for icon-only items
- Consider adding tooltips for icon-only items
Visual Design
- Use spacing={0} with variant="outline" for segmented controls
- Keep the number of items manageable (typically 2-7 items)
State Management
- Use controlled mode when the value lives elsewhere
- Provide sensible default values

Common Use Cases

Text Formatting: Bold, italic, underline in rich text editors
Layout Controls: Text alignment, view modes, display options
Filter Controls: Show/hide content categories or types
Media Controls: Playback options, audio settings
Segmented Controls: Day/week/month and similar period pickers

Integration Examples

With Form Libraries

import { useForm, Controller } from 'react-hook-form'

function PreferencesForm() {
  const { control, handleSubmit } = useForm()

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Controller
        name="notifications"
        control={control}
        render={({ field }) => (
          <ToggleGroup
            multiple
            value={field.value || []}
            onValueChange={field.onChange}
          >
            <ToggleGroupItem value="email">Email</ToggleGroupItem>
            <ToggleGroupItem value="push">Push</ToggleGroupItem>
            <ToggleGroupItem value="sms">SMS</ToggleGroupItem>
          </ToggleGroup>
        )}
      />
    </form>
  )
}

Toggle
Button Group
Radio Group
Tabs