Skip to content

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
toggle-group.svelte
<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
outline-variant.svelte
<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
ghost-variant.svelte
<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
sizes.svelte
<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
icons-and-labels.svelte
<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
disabled-loading-stable-keys.svelte
<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

NameTypeDefaultDescription
itemsrequiredButtonGroupItem[]—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.
variantButtonGroupVariant'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.
classClassValue—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 active value to reflect selection. Each button exposes this state through aria-pressed; selecting an item is controlled by the Consumer’s onclick handler.
  • secondary and outline use surface-overlay-active for the selected segment. ghost uses surface-overlay-hover, matching Button variant="ghost". Inactive hover colors also follow the corresponding Button variant.
  • Items support icon, optional label, tooltip-based title, native button attributes, and additive classes and styles. Omit label (or use an empty string) for a square icon-only item; layout is derived from an icon or loading spinner without label text. Supply aria-label or title for its accessible name. The iconOnly item 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, and lg have 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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.