Toggle group

Pro

A row of toggle buttons where one or several can be pressed, for a small set of related options.

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0 and 2.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/toggle-group

Brings in: locked, motion, toggle, tokens, utils · npm: @base-ui/react@^1.9.0, class-variance-authority@^0.7.1

Usage

TSX · The example above

"use client"

import * as React from "react"
import { AlignCenterIcon, AlignLeftIcon, AlignRightIcon } from "lucide-react"
import { Toggle } from "@/components/candor/ui/toggle"
import { ToggleGroup, ToggleGroupItem } from "@/components/candor/ui/toggle-group"
import { TooltipProvider } from "@/components/candor/ui/tooltip"

export default function Example() {
  // Nothing is chosen until the person chooses; the app decides what an empty value means.
  const [view, setView] = React.useState("")
  return (
    <TooltipProvider>
      <div className="flex flex-col items-start gap-6">
        <ToggleGroup type="single" value={view} onValueChange={setView} aria-label="Table density">
          <ToggleGroupItem value="compact">Compact</ToggleGroupItem>
          <ToggleGroupItem value="comfortable">Comfortable</ToggleGroupItem>
          <ToggleGroupItem value="spacious" locked="Spacious needs the wide layout.">
            Spacious
          </ToggleGroupItem>
        </ToggleGroup>

        <ToggleGroup type="multiple" variant="outline" aria-label="Text style">
          <ToggleGroupItem value="left" aria-label="Align left">
            <AlignLeftIcon />
          </ToggleGroupItem>
          <ToggleGroupItem value="center" aria-label="Align centre">
            <AlignCenterIcon />
          </ToggleGroupItem>
          <ToggleGroupItem value="right" aria-label="Align right">
            <AlignRightIcon />
          </ToggleGroupItem>
        </ToggleGroup>

        <Toggle variant="outline">Wrap long lines</Toggle>
      </div>
    </TooltipProvider>
  )
}

<ToggleGroup>

Prop	Type	Default	Description
variant	`"default" \| "outline"`	"default"	Which variant: one of `toggleVariants`'s styles.
size	`"default" \| "sm" \| "lg"`	"default"	Which size: one of `toggleVariants`'s styles.
className	`string \| undefined`	—	Classes, merged with Candor's.
indicator	`boolean \| undefined`	true	Slides a highlight behind the pressed item in a single-choice group. Defaults to true; a multiple-choice group has no single item to point at, so it only changes the pressed items' colours.

<ToggleGroupItem>

One button in a ToggleGroup, pressed or not; the group says whether one or several can be on.

Prop	Type	Default	Description
variant	`"default" \| "outline"`	"default"	Which variant: one of `toggleVariants`'s styles.
size	`"default" \| "sm" \| "lg"`	"default"	Which size: one of `toggleVariants`'s styles.
className	`string \| undefined`	—	Classes, merged with Candor's.
valuerequired	`string`	—	The value the group reports while this item is pressed.
locked	`string \| null \| undefined`	—	Why this item can't be chosen right now. When set, it stays in the arrow-key order and is marked `aria-disabled`, pressing it changes nothing, and the reason is shown on hover and focus and read to screen readers (see `Locked`). `null` or left out: unlocked.

Also takes the props of Omit<TogglePrimitive.Props, "className">.

Motion

Moment	Family	What it does
indicator	move	In a single-choice group the highlight slides to the item the person chose. It is placed without sliding on first draw and when it appears after nothing was chosen, and when the pressed item changes for a reason other than a press it still slides, because that is a change the person should see.

Set with --cd-motion-toggle-group-<moment>-* in your brand file; the families are in the design reference.