Toggle Group React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Toggle Group is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import ToggleGroup from @/components/ui/toggle-group.

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

export function EditorToolbar({ align, onAlignChange }: { align: string; onAlignChange: (value: string) => void }) {
  return (
    <div role="toolbar" aria-label="Editor" className="flex items-center gap-1">
      <ToggleGroup
        type="multiple"
        iconOnly
        defaultValue={["bold"]}
        aria-label="Formatting"
        options={[
          { value: "bold", label: "Bold", icon: <Bold />, shortcut: "mod+b" },
          { value: "italic", label: "Italic", icon: <Italic />, shortcut: "mod+i" },
          { value: "underline", label: "Underline", icon: <Underline />, shortcut: "mod+u" },
        ]}
      />
      <ToggleGroupSeparator />
      <ToggleGroup
        iconOnly
        value={align}
        onValueChange={onAlignChange}
        aria-label="Alignment"
        options={[
          { value: "left", label: "Left", icon: <AlignLeft /> },
          { value: "center", label: "Center", icon: <AlignCenter /> },
          { value: "right", label: "Right", icon: <AlignRight /> },
        ]}
      />
    </div>
  )
}

Props

• typedefault "single"
  "single" | "multiple"

  single: one item stays pressed and the value is a string (an alignment, a view). multiple: any number stay pressed and the value is a string[] (bold, italic, filters).

• options
  ToggleGroupOption[]

  { value: string; label: ReactNode; icon?: ReactNode; disabled?: boolean; tooltip?: ReactNode; shortcut?: string }. The shortcut is a hint shown in the tooltip and set as aria-keyshortcuts; bind it yourself with useShortcut. Values that disappear from the list are dropped from the value.

• value
  string | string[]

  Controlled value, typed by type: a string for single (empty for none), a string[] for multiple.

• defaultValue
  string | string[]

  Starting value while uncontrolled: "" or [] when omitted.

• onValueChange
  (value: string | string[]) => void

  Fires with the new value, typed by type: a string for single ("" when cleared), a string[] for multiple.

• deselectabledefault false
  boolean

  single only: clicking the pressed item clears the value. Off by default, since an alignment or a view always has one.

• variantdefault "ghost"
  "ghost" | "outline" | "soft"

  ghost: transparent items for toolbars, pressed ones get the selected tint. outline: items joined into one bordered control with hairlines between them. soft: a tinted track where the pressed item becomes a solid fill.

• sizedefault "md"
  "sm" | "md" | "lg"

  Height 32 / 40 / 48px with matching padding, type and icon size; icon-only items are square. On touch screens md grows to 44px and sm keeps a 44px hit area.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape, scaled with the size like the button's. full turns the group into a pill.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Color of the pressed items. neutral is the gray selected tint (a black or white fill on soft); the other tones tint the highlight and color the text.

• colordefault ""
  string

  Any CSS color for the pressed items; replaces the tone. Leave empty to use the tone.

• orientationdefault "horizontal"
  "horizontal" | "vertical"

  The direction of the row and of the arrow keys. Vertical items align their labels to the start.

• iconOnlydefault false
  boolean

  Shows only the icons in square items. Each label becomes the item's aria-label and its tooltip (with the shortcut hint).

• fullWidthdefault false
  boolean

  Items share the width of the container, the usual layout for a view switch on a phone.

• attacheddefault true
  boolean

  outline only: items share their borders as one control. Off: they stand apart as separate chips with a gap; add flex-wrap through className to let them wrap.

• loopdefault true
  boolean

  Arrow keys wrap from the last item to the first and back. Off: they stop at the ends.

• disableddefault false
  boolean

  Dims the whole group and blocks it. A single option can be disabled through its disabled field.

• aria-labeldefault ""
  string

  The group's name for screen readers, like Alignment. Needed when no visible label sits next to it.

• classNames
  Partial<Record<"item" | "highlight" | "icon" | "label", string>>

  Extra classes for every item, the pressed highlight, the icon wrapper and the label wrapper.

• className
  string

  Extra classes for the group itself, merged last.

Parts

FAQ

Used in

More React button components