Toggle Group

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add toggle-group

Usage#

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

export function Example() {
  return (
    <ToggleGroup type="single" defaultValue="yes">
      <ToggleGroupItem value="yes">Yes</ToggleGroupItem>
      <ToggleGroupItem value="no">No</ToggleGroupItem>
    </ToggleGroup>
  )
}

Anatomy#

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

<ToggleGroup type="single">
  <ToggleGroupItem value="…" />
</ToggleGroup>

Single vs. multiple#

type="single" is a mutually exclusive choice: selecting one pill clears the rest. type="multiple" lets each pill toggle on and off independently, like a formatting band.

Variants#

outline (the default) gives each pill its own border on the page ground, and the chosen one takes the ink outline. Use it when the pills are independent choices. segmented puts them in one muted track and lifts the chosen pill off it instead, the same elevation the Tabs pill indicator uses. Reach for it when the set reads as a single control, such as the format switch in the Color Picker. The lift is one sliding thumb rather than a background on each pill, so choosing another option travels instead of blinking: it snaps into place on load and slides only on later changes. ghost drops the pill altogether: bare labels in the foreground, the chosen one underlined, for a dense set where a frame per option would read as a wall of boxes.

Size grid#

The ghost variant is the size picker on a product page: lay the group out as a grid and let the cells shed their side padding. Weight stays medium when a size is chosen, so a bolder label never nudges its neighbours. A sold-out size stays in the grid, disabled, its label wrapped in <s> and its aria-label saying so.

Sizes#

sm (32px) is the compact rating pill; md (40px) is the default. Set size on the group and every item inherits it through context.

Icon-only with tooltips#

iconOnly squares an item around its glyph (32px at sm, 40px at md, where the glyph steps up to 20px), the same square the lone Toggle draws. A glyph is not a name, so an icon-only item always needs a hint, and tooltip gives it one with the same wiring as Button: a string tooltip is shown on hover and focus and also names an item that has no aria-label, and an icon-only item with an aria-label shows that label as its hint on its own. On a labelled pill a tooltip is a supplementary hint. Pass tooltip={false} to opt out when you wrap the item in your own Tooltip.

Feedback card#

The classic "Was this useful?" prompt: a title, a question, and a Yes/No band on a card. Rendered open so it reads at a glance, with the group controlled so the selection is yours to send.

Inline feedback#

The compact variant: just the question and a Yes/No band, no subtitle. Answering swaps the prompt for a thank-you, so the widget always feels resolved.

Inside a popover#

The same content floated: drop the card into a Popover when the prompt should appear on demand rather than sit in the page.

API reference#

FAQ#