ToggleGroup

A group of toggle buttons for selecting one or multiple options. Chrome matches Tabs: default is a bordered track, outline is stroke-only, ghost is bare. Use gap for space between items — layout only, never chrome.

Default

Bordered recessed track — the usual segmented control.

import { HStack, ToggleGroup, ToggleGroupItem } from "@vesyl/ui-next";
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";

export default function ToggleGroupBasic() {
  return (
    <HStack justify="center">
      <ToggleGroup defaultValue={["center"]}>
        <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>
    </HStack>
  );
}

Multiple selection

import { HStack, ToggleGroup, ToggleGroupItem } from "@vesyl/ui-next";
import { Bold, Italic, Underline } from "lucide-react";

export default function ToggleGroupMultiple() {
  return (
    <HStack justify="center">
      <ToggleGroup multiple defaultValue={["bold"]}>
        <ToggleGroupItem value="bold" aria-label="Bold">
          <Bold />
        </ToggleGroupItem>
        <ToggleGroupItem value="italic" aria-label="Italic">
          <Italic />
        </ToggleGroupItem>
        <ToggleGroupItem value="underline" aria-label="Underline">
          <Underline />
        </ToggleGroupItem>
      </ToggleGroup>
    </HStack>
  );
}

Outline

variant="outline" keeps the outer stroke but drops the track fill.

import { HStack, ToggleGroup, ToggleGroupItem } from "@vesyl/ui-next";
import { Grid, LayoutGrid, List } from "lucide-react";

export default function ToggleGroupOutline() {
  return (
    <HStack justify="center">
      <ToggleGroup variant="outline" defaultValue={["list"]}>
        <ToggleGroupItem value="list" aria-label="List view">
          <List />
        </ToggleGroupItem>
        <ToggleGroupItem value="grid" aria-label="Grid view">
          <Grid />
        </ToggleGroupItem>
        <ToggleGroupItem value="layout" aria-label="Layout view">
          <LayoutGrid />
        </ToggleGroupItem>
      </ToggleGroup>
    </HStack>
  );
}

Ghost (with gap)

variant="ghost" has no rail. Pass gap={2} (spacing scale) or a CSS string for item spacing.

import { HStack, ToggleGroup, ToggleGroupItem } from "@vesyl/ui-next";
import { AlignCenter, AlignJustify, AlignLeft, AlignRight } from "lucide-react";

/** Ghost + gap — bare rail; gap is layout only (does not change chrome). */
export default function ToggleGroupSpacing() {
  return (
    <HStack justify="center">
      <ToggleGroup variant="ghost" gap={2} defaultValue={["center"]}>
        <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>
        <ToggleGroupItem value="justify" aria-label="Justify">
          <AlignJustify />
        </ToggleGroupItem>
      </ToggleGroup>
    </HStack>
  );
}

Sizes

sm and md — same tokens as Tabs / Button (h-8 / h-9).

import { ToggleGroup, ToggleGroupItem, VStack } from "@vesyl/ui-next";
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";

export default function ToggleGroupSizes() {
  return (
    <VStack gap={4} align="center">
      <ToggleGroup size="sm" defaultValue={["center"]}>
        <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>
      <ToggleGroup size="md" defaultValue={["center"]}>
        <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>
    </VStack>
  );
}

Vertical orientation

import { HStack, ToggleGroup, ToggleGroupItem } from "@vesyl/ui-next";
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react";

export default function ToggleGroupVertical() {
  return (
    <HStack justify="center">
      <ToggleGroup orientation="vertical" 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>
    </HStack>
  );
}

Reference

ToggleGroup

Root. Extends base-ui ToggleGroup props.

Prop	Type	Default	Description
`variant`	`"default" \| "outline" \| "ghost"`	`"default"`	Bordered track / stroke-only / bare
`size`	`"md" \| "sm"`	`"md"`	Item height (`md` = h-9, `sm` = h-8); same tokens as Tabs / Button
`gap`	`number \| string`	—	Flex gap between items (`number` = spacing scale; string = CSS). Layout only — does not change chrome
`multiple`	`boolean`	`false`	When `true`, more than one item can be pressed
`value`	`readonly any[]`	—	Controlled pressed values (array)
`defaultValue`	`readonly any[]`	—	Uncontrolled initial values (array; a bare string is coerced)
`onValueChange`	`(groupValue: any[], eventDetails) => void`	—	Fires when the pressed set changes
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout direction
`disabled`	`boolean`	`false`	Disable the whole group
`className`	`string`	—	Merged onto the root

ToggleGroupItem

One toggle in the group. Extends base-ui Toggle props. Size/chrome come from the parent group.

Prop	Type	Default	Description
`value`	`string`	—	Value included in the group’s pressed array when on