ToggleButtonGroup

Group multiple toggle buttons, with single or multiple selection.

Documentation
React Aria
Pattern
W3C ARIA
Source
GitHub
Issues
Report
Composes
Field, ToggleButton
ToggleButtonGroup example
import {
  TextAlignCenter,
  TextAlignLeft,
  TextAlignRight,
} from "@phosphor-icons/react/dist/ssr";
import { ToggleButton } from "@/shim-ui/toggle-button";
import { ToggleButtonGroup } from "@/shim-ui/toggle-button-group";

export default () => (
  <ToggleButtonGroup aria-label="Align" className="self-start">
    <ToggleButton aria-label="Left" id="left">
      <TextAlignLeft size={16} />
    </ToggleButton>
    <ToggleButton aria-label="Center" id="center">
      <TextAlignCenter size={16} />
    </ToggleButton>
    <ToggleButton aria-label="Right" id="right">
      <TextAlignRight size={16} />
    </ToggleButton>
  </ToggleButtonGroup>
);

Install

Use the CLI or copy the source code manually.

pnpm dlx @kkga/shim add toggle-button-group

Selection mode

Configure how many buttons may be active by setting the selectionMode prop.

Selection mode example
import {
  TextB,
  TextItalic,
  TextUnderline,
} from "@phosphor-icons/react/dist/ssr";
import { ToggleButton } from "@/shim-ui/toggle-button";
import { ToggleButtonGroup } from "@/shim-ui/toggle-button-group";

export default () => (
  <ToggleButtonGroup
    aria-label="Style"
    defaultSelectedKeys={["bold", "italic"]}
    selectionMode="multiple"
  >
    <ToggleButton aria-label="Bold" id="bold">
      <TextB size={16} />
    </ToggleButton>
    <ToggleButton aria-label="Italic" id="italic">
      <TextItalic size={16} />
    </ToggleButton>
    <ToggleButton aria-label="Underline" id="underline">
      <TextUnderline size={16} />
    </ToggleButton>
  </ToggleButtonGroup>
);

States

Use isDisabled on the group or individual buttons to control interactivity.

States example
import { ToggleButton } from "@/shim-ui/toggle-button";
import { ToggleButtonGroup } from "@/shim-ui/toggle-button-group";

export default () => (
  <>
    <ToggleButtonGroup aria-label="View" isDisabled>
      <ToggleButton id="grid">Grid</ToggleButton>
      <ToggleButton id="list">List</ToggleButton>
      <ToggleButton id="gallery">Gallery</ToggleButton>
    </ToggleButtonGroup>

    <ToggleButtonGroup aria-label="View">
      <ToggleButton id="grid">Grid</ToggleButton>
      <ToggleButton id="list">List</ToggleButton>
      <ToggleButton id="gallery" isDisabled>
        Gallery
      </ToggleButton>
    </ToggleButtonGroup>
  </>
);

Size

Set the size prop to scale each button in the group.

Size example
import { GridFour, List } from "@phosphor-icons/react/dist/ssr";
import { ToggleButton } from "@/shim-ui/toggle-button";
import { ToggleButtonGroup } from "@/shim-ui/toggle-button-group";

export default () => (
  <>
    <ToggleButtonGroup aria-label="View" size={1}>
      <ToggleButton aria-label="Grid" id="Grid">
        <GridFour size={16} />
        Grid
      </ToggleButton>
      <ToggleButton aria-label="List" id="List">
        <List size={16} />
        List
      </ToggleButton>
    </ToggleButtonGroup>
    <ToggleButtonGroup aria-label="View" size={2}>
      <ToggleButton aria-label="Grid" id="Grid">
        <GridFour size={16} />
        Grid
      </ToggleButton>
      <ToggleButton aria-label="List" id="List">
        <List size={16} />
        List
      </ToggleButton>
    </ToggleButtonGroup>
    <ToggleButtonGroup aria-label="View" size={3}>
      <ToggleButton aria-label="Grid" id="Grid">
        <GridFour size={16} />
        Grid
      </ToggleButton>
      <ToggleButton aria-label="List" id="List">
        <List size={16} />
        List
      </ToggleButton>
    </ToggleButtonGroup>
    <ToggleButtonGroup aria-label="View" size={4}>
      <ToggleButton aria-label="Grid" id="Grid">
        <GridFour size={20} />
        Grid
      </ToggleButton>
      <ToggleButton aria-label="List" id="List">
        <List size={20} />
        List
      </ToggleButton>
    </ToggleButtonGroup>
  </>
);

Variant

Use the variant prop to align the group with its surface.

Variant example
import { ToggleButton } from "@/shim-ui/toggle-button";
import { ToggleButtonGroup } from "@/shim-ui/toggle-button-group";

export default () => (
  <>
    <ToggleButtonGroup aria-label="View" variant="soft">
      <ToggleButton id="grid">Grid</ToggleButton>
      <ToggleButton id="list">List</ToggleButton>
      <ToggleButton id="gallery">Gallery</ToggleButton>
    </ToggleButtonGroup>

    <ToggleButtonGroup aria-label="View" variant="ghost">
      <ToggleButton id="grid">Grid</ToggleButton>
      <ToggleButton id="list">List</ToggleButton>
      <ToggleButton id="gallery">Gallery</ToggleButton>
    </ToggleButtonGroup>
  </>
);