For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Toggle Group

A set of grouped toggle buttons.

toggle-group.tsx
"use client";

import type { VariantProps } from "class-variance-authority";
import * as React from "react";

import { toggleVariants } from "@/components/ui/toggle";
import { cn } from "@/lib/utils";

interface ToggleGroupContextValue {
  disabled?: boolean;
  orientation: "horizontal" | "vertical";
  registerItem: (value: string) => () => void;
  setValue: (next: string) => void;
  size?: VariantProps<typeof toggleVariants>["size"];
  spacing: number;
  type: "single" | "multiple";
  value: string[];
  variant?: VariantProps<typeof toggleVariants>["variant"];
}

const ToggleGroupContext = React.createContext<ToggleGroupContextValue | null>(
  null
);

function useToggleGroupContext(): ToggleGroupContextValue {
  const ctx = React.useContext(ToggleGroupContext);
  if (!ctx) {
    throw new Error("ToggleGroupItem must be used within <ToggleGroup>.");
  }
  return ctx;
}

type ToggleGroupBaseProps = VariantProps<typeof toggleVariants> & {
  className?: string;
  orientation?: "horizontal" | "vertical";
  spacing?: number;
  disabled?: boolean;
  children?: React.ReactNode;
};

type SingleProps = ToggleGroupBaseProps & {
  type?: "single";
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
};

type MultipleProps = ToggleGroupBaseProps & {
  type: "multiple";
  value?: string[];
  defaultValue?: string[];
  onValueChange?: (value: string[]) => void;
};

type ToggleGroupProps = SingleProps | MultipleProps;

function ToggleGroup(props: ToggleGroupProps) {
  const {
    children,
    className,
    disabled,
    orientation = "horizontal",
    size,
    spacing = 2,
    variant,
  } = props;
  const isMultiple = props.type === "multiple";
  const isControlled = props.value !== undefined;
  const defaultValue = props.defaultValue;
  const [uncontrolledSingle, setUncontrolledSingle] = React.useState<string>(
    isMultiple ? "" : ((defaultValue as string | undefined) ?? "")
  );
  const [uncontrolledMultiple, setUncontrolledMultiple] = React.useState<
    string[]
  >(isMultiple ? ((defaultValue as string[] | undefined) ?? []) : []);
  const value: string[] = isMultiple
    ? isControlled
      ? ((props.value as string[] | undefined) ?? [])
      : uncontrolledMultiple
    : isControlled
      ? props.value
        ? [props.value as string]
        : []
      : uncontrolledSingle
        ? [uncontrolledSingle]
        : [];

  const itemsRef = React.useRef<string[]>([]);
  const registerItem = React.useCallback((next: string) => {
    if (!itemsRef.current.includes(next)) {
      itemsRef.current = [...itemsRef.current, next];
    }
    return () => {
      itemsRef.current = itemsRef.current.filter((x) => x !== next);
    };
  }, []);

  const setValue = React.useCallback(
    (next: string) => {
      if (isMultiple) {
        const current = isControlled
          ? ((props.value as string[] | undefined) ?? [])
          : uncontrolledMultiple;
        const newValue = current.includes(next)
          ? current.filter((v) => v !== next)
          : [...current, next];
        if (!isControlled) {
          setUncontrolledMultiple(newValue);
        }
        (props.onValueChange as ((v: string[]) => void) | undefined)?.(
          newValue
        );
      } else {
        const current = isControlled ? props.value : uncontrolledSingle;
        const newValue = current === next ? "" : next;
        if (!isControlled) {
          setUncontrolledSingle(newValue);
        }
        (props.onValueChange as ((v: string) => void) | undefined)?.(newValue);
      }
    },
    [
      isControlled,
      isMultiple,
      props.onValueChange,
      props.value,
      uncontrolledMultiple,
      uncontrolledSingle,
    ]
  );

  const ctx = React.useMemo<ToggleGroupContextValue>(
    () => ({
      disabled,
      orientation,
      registerItem,
      setValue,
      size,
      spacing,
      type: isMultiple ? "multiple" : "single",
      value,
      variant,
    }),
    [
      disabled,
      isMultiple,
      orientation,
      registerItem,
      setValue,
      size,
      spacing,
      value,
      variant,
    ]
  );

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

type ToggleGroupItemProps = Omit<
  React.ComponentPropsWithoutRef<"button">,
  "value" | "ref" | "aria-pressed" | "type"
> &
  VariantProps<typeof toggleVariants> & {
    value: string;
    ref?: React.Ref<HTMLButtonElement>;
  };

function ToggleGroupItem({
  className,
  disabled: disabledProp,
  onClick,
  ref,
  size,
  value,
  variant,
  ...props
}: ToggleGroupItemProps) {
  const ctx = useToggleGroupContext();
  const isPressed = ctx.value.includes(value);
  const isDisabled = ctx.disabled || disabledProp === true;
  const registerItem = ctx.registerItem;

  React.useEffect(() => registerItem(value), [registerItem, value]);

  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
    onClick?.(event);
    if (event.defaultPrevented || isDisabled) {
      return;
    }
    ctx.setValue(value);
  };

  return (
    <button
      {...props}
      aria-pressed={isPressed}
      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({
          size: ctx.size || size,
          variant: ctx.variant || variant,
        }),
        className
      )}
      data-size={ctx.size || size}
      data-slot="toggle-group-item"
      data-spacing={ctx.spacing}
      data-state={isPressed ? "on" : "off"}
      data-value={value}
      data-variant={ctx.variant || variant}
      disabled={isDisabled}
      onClick={handleClick}
      ref={ref}
      type="button"
    />
  );
}

export { ToggleGroup, ToggleGroupItem };

Toggle Group is a set of two-state toggle buttons rendered as native <button> elements. It supports outline and default variants, multiple selection, sm / default / lg sizes, spacing, and both horizontal and vertical orientation.

Installation

Usage

toggle-group.tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
<DocsBaseSwitcher base="web" component="toggle-group" className="mb-6" />
tsx
<ToggleGroup type="multiple" variant="outline">
  <ToggleGroupItem value="bold" aria-label="Toggle bold">
    <Bold />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Toggle italic">
    <Italic />
  </ToggleGroupItem>
</ToggleGroup>

Composition

ToggleGroup
└── ToggleGroupItem

Examples

Outline

variant="outline" for bordered items with a shared rounded container.

toggle-group-outline.tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export function ToggleGroupOutline() {
  return (
    <ToggleGroup defaultValue="all" type="single" variant="outline">
      <ToggleGroupItem aria-label="Toggle all" value="all">
        All
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle missed" value="missed">
        Missed
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
tsx
<ToggleGroup variant="outline" defaultValue={["all"]}>
  <ToggleGroupItem value="all">All</ToggleGroupItem>
  <ToggleGroupItem value="missed">Missed</ToggleGroupItem>
</ToggleGroup>

Sizes

size accepts sm, default, and lg.

toggle-group-sizes.tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export function ToggleGroupSizes() {
  return (
    <div className="flex flex-col gap-4">
      <ToggleGroup defaultValue="top" size="sm" type="single" variant="outline">
        <ToggleGroupItem aria-label="Toggle top" value="top">
          Top
        </ToggleGroupItem>
        <ToggleGroupItem aria-label="Toggle bottom" value="bottom">
          Bottom
        </ToggleGroupItem>
        <ToggleGroupItem aria-label="Toggle left" value="left">
          Left
        </ToggleGroupItem>
        <ToggleGroupItem aria-label="Toggle right" value="right">
          Right
        </ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup defaultValue="top" type="single" variant="outline">
        <ToggleGroupItem aria-label="Toggle top" value="top">
          Top
        </ToggleGroupItem>
        <ToggleGroupItem aria-label="Toggle bottom" value="bottom">
          Bottom
        </ToggleGroupItem>
        <ToggleGroupItem aria-label="Toggle left" value="left">
          Left
        </ToggleGroupItem>
        <ToggleGroupItem aria-label="Toggle right" value="right">
          Right
        </ToggleGroupItem>
      </ToggleGroup>
    </div>
  );
}
tsx
<ToggleGroup size="sm" variant="outline">...</ToggleGroup>
<ToggleGroup variant="outline">...</ToggleGroup>

Spacing

spacing accepts a Tailwind spacing scale value (e.g. 2) to separate items instead of merging them.

toggle-group-spacing.tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export function ToggleGroupSpacing() {
  return (
    <ToggleGroup
      defaultValue="top"
      size="sm"
      spacing={2}
      type="single"
      variant="outline"
    >
      <ToggleGroupItem aria-label="Toggle top" value="top">
        Top
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle bottom" value="bottom">
        Bottom
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle left" value="left">
        Left
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle right" value="right">
        Right
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
tsx
<ToggleGroup size="sm" variant="outline" spacing={2}>
  ...
</ToggleGroup>

Vertical

orientation="vertical" stacks items in a column — useful for toolbar-like selectors.

toggle-group-vertical.tsx
import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export function ToggleGroupVertical() {
  return (
    <ToggleGroup
      defaultValue={["bold", "italic"]}
      orientation="vertical"
      spacing={1}
      type="multiple"
    >
      <ToggleGroupItem aria-label="Toggle bold" value="bold">
        <BoldIcon />
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle italic" value="italic">
        <ItalicIcon />
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle underline" value="underline">
        <UnderlineIcon />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
tsx
<ToggleGroup type="multiple" orientation="vertical" spacing={1}>
  ...
</ToggleGroup>

Disabled

Pass disabled on the group to lock every item.

toggle-group-disabled.tsx
import { BoldIcon as Bold, Italic, Underline } from "lucide-react";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export function ToggleGroupDisabled() {
  return (
    <ToggleGroup disabled type="single">
      <ToggleGroupItem aria-label="Toggle bold" value="bold">
        <Bold />
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle italic" value="italic">
        <Italic />
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Toggle strikethrough" value="strikethrough">
        <Underline />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}
tsx
<ToggleGroup disabled>...</ToggleGroup>

Font weight selector

Compose ToggleGroup with Field for a labeled, controlled selector — value / onValueChange accept a string array.

Usefont-normalto set the font weight.

toggle-group-font-weight.tsx
"use client";

import * as React from "react";

import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

export function ToggleGroupFontWeightSelector() {
  const [fontWeight, setFontWeight] = React.useState("normal");
  return (
    <Field className="mx-auto w-fit *:w-fit">
      <FieldLabel>Font Weight</FieldLabel>
      <ToggleGroup
        onValueChange={(value) => {
          if (value) {
            setFontWeight(value);
          }
        }}
        size="lg"
        spacing={2}
        type="single"
        value={fontWeight}
        variant="outline"
      >
        <ToggleGroupItem
          aria-label="Light"
          className="flex size-16 flex-col items-center justify-center rounded-xl"
          value="light"
        >
          <span className="text-2xl leading-none font-light">Aa</span>
          <span className="text-muted-foreground text-xs">Light</span>
        </ToggleGroupItem>
        <ToggleGroupItem
          aria-label="Normal"
          className="flex size-16 flex-col items-center justify-center rounded-xl"
          value="normal"
        >
          <span className="text-2xl leading-none font-normal">Aa</span>
          <span className="text-muted-foreground text-xs">Normal</span>
        </ToggleGroupItem>
        <ToggleGroupItem
          aria-label="Medium"
          className="flex size-16 flex-col items-center justify-center rounded-xl"
          value="medium"
        >
          <span className="text-2xl leading-none font-medium">Aa</span>
          <span className="text-muted-foreground text-xs">Medium</span>
        </ToggleGroupItem>
        <ToggleGroupItem
          aria-label="Bold"
          className="flex size-16 flex-col items-center justify-center rounded-xl"
          value="bold"
        >
          <span className="text-2xl leading-none font-bold">Aa</span>
          <span className="text-muted-foreground text-xs">Bold</span>
        </ToggleGroupItem>
      </ToggleGroup>
      <FieldDescription>
        Use
        <code className="bg-muted rounded-md px-1 py-0.5 font-mono">
          font-{fontWeight}
        </code>
        to set the font weight.
      </FieldDescription>
    </Field>
  );
}
tsx
<Field>
  <FieldLabel>Font Weight</FieldLabel>
  <ToggleGroup value={[fontWeight]} onValueChange={(v) => setFontWeight(v[0])}>
    ...
  </ToggleGroup>
  <FieldDescription>Use font-{fontWeight} to set the weight.</FieldDescription>
</Field>

In Context

Text formatting

toggle-group-formatting.tsx
"use client";

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

export function ToggleGroupFormatting() {
  return (
    <ToggleGroup type="multiple">
      <ToggleGroupItem aria-label="Bold" value="bold">
        <BoldIcon />
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Italic" value="italic">
        <ItalicIcon />
      </ToggleGroupItem>
      <ToggleGroupItem aria-label="Underline" value="underline">
        <UnderlineIcon />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

API Reference

All parts extend React.ComponentProps<"div"> / React.ComponentProps<"button">.

ToggleGroup

PropTypeDefaultDescription
variant
"default""outline"
—Visual style.
size
"sm""default""lg"
—Item size.
spacingnumber—Gap between items (Tailwind spacing scale).
orientation
"horizontal""vertical"
—Layout direction.
type
"single""multiple"
—Single-selection or multi-selection mode.
value
stringstring[]
—Controlled selection. String in single mode, array in multiple mode.
defaultValue
stringstring[]
—Initial selection when uncontrolled.
onValueChange(value: string | string[]) => void—Called when the selection changes.

ToggleGroupItem

Requires value and an accessible aria-label.

Controlled

tsx
const [value, setValue] = React.useState(["bold"])
<ToggleGroup type="multiple" value={value} onValueChange={setValue}>{/* ... */}</ToggleGroup>

Keyboard

KeyAction
TabMove focus to the group
Space / EnterToggle focused item

Data Attributes

AttributeValues
data-slottoggle-group, toggle-group-item
data-stateon | off
data-orientationhorizontal | vertical
data-disabledtrue

Variants

VariantUse case
defaultSolid pressed state
outlineBordered

Accessibility

  • Each item renders a button with aria-pressed.
  • type="single" (default) allows one active item, type="multiple" allows many.
  • Provide aria-label when icon-only.

Best Practices

  • Group related toggles only. Bold/Italic/Underline belong together; Save does not.
  • Use single type for exclusive choices. Font family, alignment.
  • Use multiple type for independent toggles. Formatting.
  • Cap at five items. More become a toolbar with labels.