Toggle Group

A row of toggles where one item, or several, can be pressed.

import { TextBIcon } from "@phosphor-icons/react/dist/csr/TextB"
import { TextItalicIcon } from "@phosphor-icons/react/dist/csr/TextItalic"
import { TextUnderlineIcon } from "@phosphor-icons/react/dist/csr/TextUnderline"

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

export default function ToggleGroupDemo() {
  return (
    <ToggleGroup aria-label="Formatting" variant="outline" multiple>
      <ToggleGroupItem value="bold" aria-label="Toggle bold">
        <TextBIcon aria-hidden="true" />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic">
        <TextItalicIcon aria-hidden="true" />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Toggle underline">
        <TextUnderlineIcon aria-hidden="true" />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/toggle-group

Needs the arene setup first. Also adds Button and Toggle.

Usage

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

;<ToggleGroup aria-label="Options" defaultValue={["a"]}>
  <ToggleGroupItem value="a">A</ToggleGroupItem>
  <ToggleGroupItem value="b">B</ToggleGroupItem>
  <ToggleGroupItem value="c">C</ToggleGroupItem>
</ToggleGroup>

Pass multiple to allow more than one selection. value and defaultValue are arrays in both modes; use onValueChange to control the selection.

RTL support is not included.

Composition

Use ToggleGroupItem for each option.

ToggleGroup
├── ToggleGroupItem
└── ToggleGroupItem

Outline

variant="outline" draws a border around each item.

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

export default function ToggleGroupOutline() {
  return (
    <ToggleGroup aria-label="Inbox" variant="outline" defaultValue={["all"]}>
      <ToggleGroupItem value="all" aria-label="Toggle all">
        All
      </ToggleGroupItem>
      <ToggleGroupItem value="unread" aria-label="Toggle unread">
        Unread
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Size

Use size to set the size of every item.

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

export default function ToggleGroupSizes() {
  return (
    <VStack gap={4}>
      {(["sm", "default", "lg"] as const).map((size) => (
        <ToggleGroup
          key={size}
          aria-label={`${size} position`}
          size={size}
          defaultValue={["top"]}
          variant="outline"
        >
          <ToggleGroupItem value="top">Top</ToggleGroupItem>
          <ToggleGroupItem value="bottom">Bottom</ToggleGroupItem>
          <ToggleGroupItem value="left">Left</ToggleGroupItem>
          <ToggleGroupItem value="right">Right</ToggleGroupItem>
        </ToggleGroup>
      ))}
    </VStack>
  )
}

Segmented

With spacing={0} and the default variant, the group is a segmented control. The items sit in a shallow well and the pressed one is raised out of it. Inside a Toolbar the toolbar is the well, so the group draws none of its own.

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

export default function ToggleGroupSegmented() {
  return (
    <VStack gap={4}>
      {(["sm", "default", "lg"] as const).map((size) => (
        <ToggleGroup
          key={size}
          aria-label={`${size} view`}
          size={size}
          spacing={0}
          defaultValue={["list"]}
        >
          <ToggleGroupItem value="list">List</ToggleGroupItem>
          <ToggleGroupItem value="board">Board</ToggleGroupItem>
          <ToggleGroupItem value="calendar">Calendar</ToggleGroupItem>
        </ToggleGroup>
      ))}
    </VStack>
  )
}

Spacing

With variant="outline", use spacing={0} to join the items, or a spacing step to separate them.

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

export default function ToggleGroupSpacing() {
  return (
    <VStack gap={4}>
      {([0, 2] as const).map((spacing) => (
        <ToggleGroup
          key={spacing}
          aria-label={spacing === 0 ? "Joined position" : "Spaced position"}
          size="sm"
          defaultValue={["top"]}
          variant="outline"
          spacing={spacing}
        >
          <ToggleGroupItem value="top">Top</ToggleGroupItem>
          <ToggleGroupItem value="bottom">Bottom</ToggleGroupItem>
          <ToggleGroupItem value="left">Left</ToggleGroupItem>
          <ToggleGroupItem value="right">Right</ToggleGroupItem>
        </ToggleGroup>
      ))}
    </VStack>
  )
}

Vertical

Use orientation="vertical" to stack items and navigate with the up and down arrow keys.

import { TextBIcon } from "@phosphor-icons/react/dist/csr/TextB"
import { TextItalicIcon } from "@phosphor-icons/react/dist/csr/TextItalic"
import { TextUnderlineIcon } from "@phosphor-icons/react/dist/csr/TextUnderline"

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

export default function ToggleGroupVertical() {
  return (
    <ToggleGroup
      multiple
      orientation="vertical"
      spacing={0}
      variant="outline"
      defaultValue={["bold", "italic"]}
    >
      <ToggleGroupItem value="bold" aria-label="Toggle bold">
        <TextBIcon aria-hidden="true" />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic">
        <TextItalicIcon aria-hidden="true" />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Toggle underline">
        <TextUnderlineIcon aria-hidden="true" />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Disabled

Use disabled on the group to disable every item, or on an item to disable only that option.

import { VStack } from "@/components/ui/stack"
import { TextBIcon } from "@phosphor-icons/react/dist/csr/TextB"
import { TextItalicIcon } from "@phosphor-icons/react/dist/csr/TextItalic"
import { TextUnderlineIcon } from "@phosphor-icons/react/dist/csr/TextUnderline"

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

export default function ToggleGroupDisabled() {
  return (
    <VStack gap={4}>
      <ToggleGroup aria-label="Formatting" disabled>
        <ToggleGroupItem value="bold" aria-label="Toggle bold">
          <TextBIcon aria-hidden="true" />
        </ToggleGroupItem>
        <ToggleGroupItem value="italic" aria-label="Toggle italic">
          <TextItalicIcon aria-hidden="true" />
        </ToggleGroupItem>
        <ToggleGroupItem value="underline" aria-label="Toggle underline">
          <TextUnderlineIcon aria-hidden="true" />
        </ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup aria-label="Available formatting" multiple>
        <ToggleGroupItem value="bold" aria-label="Toggle bold">
          <TextBIcon aria-hidden="true" />
        </ToggleGroupItem>
        <ToggleGroupItem value="italic" aria-label="Toggle italic" disabled>
          <TextItalicIcon aria-hidden="true" />
        </ToggleGroupItem>
        <ToggleGroupItem value="underline" aria-label="Toggle underline">
          <TextUnderlineIcon aria-hidden="true" />
        </ToggleGroupItem>
      </ToggleGroup>
    </VStack>
  )
}

Custom

Use xstyle to customize the items and value to keep one weight selected.

Font weight

Body text is set in the normal weight.

"use client"

import { useId, useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Field, FieldDescription, FieldTitle } from "@/components/ui/field"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
import { Text } from "@/components/ui/text"
import { radius, space } from "@/theme/tokens.stylex"

const styles = stylex.create({
  item: { width: space.s16, height: space.s16, flexDirection: "column", borderRadius: radius.xl },
})
const weights = stylex.create({
  light: { fontWeight: 300 },
  normal: { fontWeight: 400 },
  medium: { fontWeight: 500 },
  bold: { fontWeight: 700 },
})

export default function ToggleGroupFontWeightSelector() {
  const id = useId()
  const [fontWeight, setFontWeight] = useState<keyof typeof weights>("normal")
  return (
    <Field>
      <FieldTitle id={id}>Font weight</FieldTitle>
      <ToggleGroup
        aria-labelledby={id}
        value={[fontWeight]}
        onValueChange={(value) => {
          if (value[0]) setFontWeight(value[0])
        }}
        variant="outline"
        spacing={2}
        size="lg"
      >
        {(["light", "normal", "medium", "bold"] as const).map((weight) => (
          <ToggleGroupItem key={weight} value={weight} aria-label={weight} xstyle={styles.item}>
            <Text size="xl2" xstyle={weights[weight]}>
              Aa
            </Text>
            <Text size="xs" tone="muted">
              {weight.charAt(0).toUpperCase() + weight.slice(1)}
            </Text>
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
      <FieldDescription>Body text is set in the {fontWeight} weight.</FieldDescription>
    </Field>
  )
}

API reference

ToggleGroup accepts Base UI Toggle Group props. ToggleGroupItem accepts Toggle props. Both take render, xstyle, className and real inline style.

ToggleGroup

PropTypeDefault
variant"default" | "outline""default"
size"sm" | "default" | "lg""default"
spacing0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 122

Group-level variant and size override item values. When omitted, each item uses its own value or its default.

toggleGroupStyles

KeyWhat it is
rootFitted row with stretching items
verticalColumn layout
spacingGaps on the token scale
segmentedThe well a segmented group draws

Data attributes

AttributeOnEffect
data-slot="toggle-group"rootTargets the group
data-slot="toggle-group-item"itemTargets an option
data-variant, data-sizeroot and itemsMirror the variant and size
data-spacingrootMirrors spacing
data-orientationrootMirrors orientation
data-disabledroot and itemsBase UI writes the disabled state
data-multiplerootBase UI writes it when multiple selection is enabled
data-presseditemsBase UI writes the selection state