ButtonGroup
Groups related buttons in a secondary, outline, or ghost strip with inset segments and a moving active indicator.
import { ButtonGroup, type ButtonGroupItem, type ButtonGroupVariant,} from "phoundry-ui";Toggle group
Loading interactive example…
View source
<script lang="ts"> import { ButtonGroup } from "phoundry-ui";
let view = $state("day");</script>
<ButtonGroup items={[ { label: "Day", active: view === "day", onclick: () => (view = "day") }, { label: "Week", active: view === "week", onclick: () => (view = "week") }, { label: "Month", active: view === "month", onclick: () => (view = "month"), }, ]}/>Outline variant
Loading interactive example…
View source
<script lang="ts"> import { ButtonGroup } from "phoundry-ui";
let outlineView = $state("day");</script>
<ButtonGroup variant="outline" items={[ { label: "Day", active: outlineView === "day", onclick: () => (outlineView = "day"), }, { label: "Week", active: outlineView === "week", onclick: () => (outlineView = "week"), }, { label: "Month", active: outlineView === "month", onclick: () => (outlineView = "month"), }, ]}/>Ghost variant
Loading interactive example…
View source
<script lang="ts"> import { ButtonGroup } from "phoundry-ui";
let ghostView = $state("day");</script>
<ButtonGroup variant="ghost" items={[ { label: "Day", active: ghostView === "day", onclick: () => (ghostView = "day"), }, { label: "Week", active: ghostView === "week", onclick: () => (ghostView = "week"), }, { label: "Month", active: ghostView === "month", onclick: () => (ghostView = "month"), }, ]}/>Sizes
Loading interactive example…
View source
<script lang="ts"> import { ButtonGroup } from "phoundry-ui";
let listMode = $state<"list" | "grid">("list");</script>
<p class="mb-2 text-xs text-txt-secondary"> The outer shell matches the shared control height. Segments fit inside its border and inset.</p><div class="flex flex-wrap items-center gap-3"> <ButtonGroup size="sm" items={[ { label: "List", active: listMode === "list", onclick: () => (listMode = "list"), }, { label: "Grid", active: listMode === "grid", onclick: () => (listMode = "grid"), }, ]} /> <ButtonGroup size="md" items={[ { label: "List", active: listMode === "list", onclick: () => (listMode = "list"), }, { label: "Grid", active: listMode === "grid", onclick: () => (listMode = "grid"), }, ]} /> <ButtonGroup size="lg" items={[ { label: "List", active: listMode === "list", onclick: () => (listMode = "list"), }, { label: "Grid", active: listMode === "grid", onclick: () => (listMode = "grid"), }, ]} /></div>Icons and labels
Loading interactive example…
View source
<script lang="ts"> import { ButtonGroup } from "phoundry-ui"; import { PhiIcons } from "phoundry-ui";
let iconSelection = $state("check");</script>
<p class="mb-2 text-xs text-txt-secondary"> Omit label for a square icon-only item and provide an accessible name with aria-label or title.</p><ButtonGroup items={[ { icon: PhiIcons.check, "aria-label": "Check", active: iconSelection === "check", onclick: () => (iconSelection = "check"), }, { icon: PhiIcons.add, label: "Add", active: iconSelection === "add", onclick: () => (iconSelection = "add"), }, { loading: true, "aria-label": "Processing" }, ]}/>Disabled, loading, stable keys
Loading interactive example…
View source
<script lang="ts"> import { ButtonGroup } from "phoundry-ui";
let segmentDemo = $state("left");</script>
<p class="mb-2 text-xs text-txt-secondary"> Optional <code>id</code> on each item stabilizes reconciliation when the list reorders. Loading shows the same spinner glyph as other buttons.</p><ButtonGroup aria-label="Demo alignment" items={[ { id: "seg-left", label: "Left", active: segmentDemo === "left", onclick: () => (segmentDemo = "left"), }, { id: "seg-center", label: "Center", disabled: true, }, { id: "seg-right", label: "Right", loading: true, onclick: () => (segmentDemo = "right"), }, ]}/>API
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
itemsrequired | ButtonGroupItem[] | — | Segment entries with optional label, icon, active, disabled, loading, class, onclick, and other native button attributes. An icon or spinner without a non-empty label uses icon-only layout; provide aria-label or title for its accessible name. |
variant | ButtonGroupVariant | 'secondary' | Button-aligned surfaces: secondary uses the base surface and button shadow; outline uses a transparent shell with the default border; ghost uses a transparent shell without a visible border or shadow. The moving indicator uses the corresponding Button active color. |
size | "sm" | "md" | "lg" | 'md' | Outer border-box height from --ph-comp-h-sm, --ph-comp-h-md, or --ph-comp-h-lg. The inner segments fill the remaining height after the border and inset; they do not add to the group height. Typography and icons follow the same named Button size. |
class | ClassValue | — | Additive classes on the outer role="group" container. Width is intrinsic by default. Use style="width: 100%" to stretch the shell in a layout. |
Other native attributes: Forwarded to the outer role="group" wrapper (aria-label, data-*, etc.).
Usage tips
- Set one item’s
activevalue to reflect selection. Each button exposes this state througharia-pressed; selecting an item is controlled by the Consumer’sonclickhandler. secondaryandoutlineusesurface-overlay-activefor the selected segment.ghostusessurface-overlay-hover, matchingButton variant="ghost". Inactive hover colors also follow the corresponding Button variant.- Items support
icon, optionallabel, tooltip-basedtitle, native button attributes, and additive classes and styles. Omitlabel(or use an empty string) for a square icon-only item; layout is derived from an icon or loading spinner without label text. Supplyaria-labelortitlefor its accessible name. TheiconOnlyitem prop has been removed. Links are not supported. - Loading replaces the item content with a spinner and disables its action. Disabled items cannot activate through the component’s click handler.
sm,md, andlghave outer heights of 1.5rem, 1.75rem, and 2rem with the shared defaults. Insets and borders stay inside those heights, so a group aligns with the same-sized Button or ButtonDropdown.
<ButtonGroup items={[ { icon: PhiIcons.add, "aria-label": "Add", onclick: addItem }, { icon: PhiIcons.check, label: "Apply", onclick: applyChanges }, ]}/>Styling hooks
The stable root selector is .ph-btn-group, with data-variant and data-size axes. Consumer class, style, and remaining div attributes apply to this root; item classes, styles, and native attributes apply to each button. Part selectors are internal.
The group consumes shared --ph-comp-h-sm / md / lg height tokens, --ph-comp-icon-sm / md / lg icon tokens, and --ph-btn-radius. It shares Button’s --ph-button-shadow, --ph-button-specular, --ph-button-shading, and --ph-text-shadow tokens.
Indicator movement uses --ph-motion-normal (200ms), hover uses --ph-motion-fast (100ms), and both use --ph-motion-ease-out. Loading uses --ph-motion-spin (1000ms). Reduced-motion preferences disable movement, transitions, and spinner animation.