Introduction

The ToggleGroup component is a set of toggle buttons designed for single or multiple selection. It is widely used to let users choose mutually exclusive layout styles (e.g. view-switchers for Grid vs. List) or group inclusive modifiers (e.g. text formatting buttons for Bold, Italic, and Underline).

The ToggleGroup is fully integrated as a toggleGroup block in the Page Builder, allowing content authors and developers to easily configure visual options, multi-select behaviors, and active color palettes directly within the CMS.

Usage

These examples illustrate how content editors bind and structure interactive toggle buttons.

1. Multiple-Selection Text Formatting Toolbar

Allows multiple items to be pressed and active at the same time. Excellent for multi-select feature switches or text editor panels.

{
  "type": "toggleGroup",
  "multiple": true,
  "defaultValue": ["bold"],
  "items": [
    { "label": "B", "value": "bold" },
    { "label": "I", "value": "italic" },
    { "label": "U", "value": "underline" }
  ],
  "interactive": true
}

2. Single-Selection Layout Switcher (Purple Theme)

Demonstrates single-selection mode where only one item can be active at a time. Active choices are styled with custom accented purple theme tokens.

{
  "type": "toggleGroup",
  "multiple": false,
  "defaultValue": ["list"],
  "items": [
    { "label": "Grid View", "value": "grid" },
    { "label": "List View", "value": "list" }
  ],
  "colorPalette": "purple",
  "interactive": true
}

3. Compact Vertical Navigation Group

Arranges the toggle choices vertically instead of horizontally, styled in a compact size scale.

{
  "type": "toggleGroup",
  "orientation": "vertical",
  "defaultValue": ["dashboard"],
  "items": [
    { "label": "Dashboard", "value": "dashboard" },
    { "label": "Settings", "value": "settings" }
  ],
  "size": "sm",
  "interactive": true
}

Props

Toggle Group Items Schema

Every entry inside the items array accepts the following parameters:

Developer Notes & Accessibility

• WAI-ARIA Accessibility Patterns: Renders a robust keyboard-navigable toolbar:
  • The root container receives role="group".
  • Individual items render as role="checkbox" with aria-checked states when multiple is true, or role="radio" with aria-checked states otherwise.
• Roving Focus Keyboard Navigation: Supports native focus movement:
  • Arrow keys (Right/Down to move forward, Left/Up to move backward) automatically roam focus between active buttons, matching the chosen orientation axis.
  • Home and End keyboard keys jump focus instantly to the first and last enabled buttons in the group.
• Form Association: Toggle choices seamlessly update associated state context, allowing parent containers or form hooks to capture changes dynamically.