Skip Navigation
React Magma

Toggle Button Group

The Toggle Button Group is a container for multiple Toggle Buttons and enables controlled behaviors throughout the grouping.

Basic Usage

The Toggle Button Group enables styling and selection states across a group of ToggleButtons.

import React from 'react';


import { ToggleButton, ToggleButtonGroup } from 'react-magma-dom';
import {
  FormatAlignCenterIcon,
  FormatAlignJustifyIcon,
  FormatAlignLeftIcon,
  FormatAlignRightIcon,
} from 'react-magma-icons';


export function Example() {
  return (
    <ToggleButtonGroup>
      <ToggleButton
        aria-label="Left align"
        icon={<FormatAlignLeftIcon />}
        value="left"
      />
      <ToggleButton
        aria-label="Center align"
        icon={<FormatAlignCenterIcon />}
        value="center"
      />
      <ToggleButton
        aria-label="Right align"
        icon={<FormatAlignRightIcon />}
        value="right"
      />
      <ToggleButton
        aria-label="Justify align"
        icon={<FormatAlignJustifyIcon />}
        value="justify"
      />
    </ToggleButtonGroup>
  );
}

Defined Selection

Using the same value between ToggleButtonGroup and ToggleButton allows a user to define preselected buttons.

import React from 'react';


import { ToggleButton, ToggleButtonGroup } from 'react-magma-dom';
import {
  FormatAlignCenterIcon,
  FormatAlignJustifyIcon,
  FormatAlignLeftIcon,
  FormatAlignRightIcon,
} from 'react-magma-icons';


export function Example() {
  return (
    <ToggleButtonGroup value="center">
      <ToggleButton
        aria-label="Left align"
        icon={<FormatAlignLeftIcon />}
        value="left"
      />
      <ToggleButton
        aria-label="Center align"
        icon={<FormatAlignCenterIcon />}
        value="center"
      />
      <ToggleButton
        aria-label="Right align"
        icon={<FormatAlignRightIcon />}
        value="right"
      />
      <ToggleButton
        aria-label="Justify align"
        icon={<FormatAlignJustifyIcon />}
        value="justify"
      />
    </ToggleButtonGroup>
  );
}

Exclusive Selection

When exclusive is enabled, it ensures a radio style ToggleButtonGroup has at least one selected state.

import React from 'react';


import { ToggleButton, ToggleButtonGroup } from 'react-magma-dom';
import {
  FormatAlignLeftIcon,
  FormatAlignCenterIcon,
  FormatAlignRightIcon,
  FormatAlignJustifyIcon,
} from 'react-magma-icons';


export function Example() {
  return (
    <ToggleButtonGroup noSpace exclusive>
      <ToggleButton
        aria-label="Left align"
        icon={<FormatAlignLeftIcon />}
        value="left"
      />
      <ToggleButton
        aria-label="Center align"
        icon={<FormatAlignCenterIcon />}
        value="center"
      />
      <ToggleButton
        aria-label="Right align"
        icon={<FormatAlignRightIcon />}
        value="right"
      />
      <ToggleButton
        aria-label="Justify align"
        icon={<FormatAlignJustifyIcon />}
        value="justify"
      />
    </ToggleButtonGroup>
  );
}

Enforced Selection

The enforced prop requires that at least one button be selected (after first selection).

The enforced prop in conjunction with exclusive allows just one toggled button across the group like a radio.

import React from 'react';


import { ToggleButton, ToggleButtonGroup, Spacer } from 'react-magma-dom';
import {
  FormatAlignLeftIcon,
  FormatAlignCenterIcon,
  FormatAlignRightIcon,
  FormatAlignJustifyIcon,
} from 'react-magma-icons';


export function Example() {
  return (
    <>
      <ToggleButtonGroup noSpace enforced>
        <ToggleButton
          aria-label="Left align"
          icon={<FormatAlignLeftIcon />}
          value="left"
        />
        <ToggleButton
          aria-label="Center align"
          icon={<FormatAlignCenterIcon />}
          value="center"
        />
        <ToggleButton
          aria-label="Right align"
          icon={<FormatAlignRightIcon />}
          value="right"
        />
        <ToggleButton
          aria-label="Justify align"
          icon={<FormatAlignJustifyIcon />}
          value="justify"
        />
      </ToggleButtonGroup>
      <Spacer size="12" />
      <ToggleButtonGroup noSpace enforced exclusive>
        <ToggleButton
          aria-label="Left align"
          icon={<FormatAlignLeftIcon />}
          value="left"
        />
        <ToggleButton
          aria-label="Center align"
          icon={<FormatAlignCenterIcon />}
          value="center"
        />
        <ToggleButton
          aria-label="Right align"
          icon={<FormatAlignRightIcon />}
          value="right"
        />
        <ToggleButton
          aria-label="Justify align"
          icon={<FormatAlignJustifyIcon />}
          value="justify"
        />
      </ToggleButtonGroup>
    </>
  );
}

Role and Accessibility

By default, a Toggle Button Group renders with role="group", and its buttons use role="radio" (when exclusive) or role="switch" (otherwise). Use the role prop to expose the correct semantics to assistive technology when the group does something other than toggle independent options.

Choose the role based on what selecting a button actually does:

  • group (default) — a set of related toggles that act on other content (for example, text alignment). Use exclusive for a single-choice set of radios, or leave it off for independent on/off switches.
  • radiogroup — a single-choice selection that is semantically a radio group. The buttons are always announced as radios; pair the role with exclusive so the single-select behavior matches the radio group semantics.
  • tablist — buttons that switch between different views or sections of the page. Each button is rendered as a tab with aria-selected, following the WAI-ARIA Tabs pattern. Pair with exclusive and enforced so exactly one tab is always selected, and connect each button to its panel with aria-controls and role="tabpanel".

Tablist

Use role="tablist" when selecting a button switches the visible content, such as a "Teacher view" / "Student view" toggle. This announces the control as a set of tabs rather than radio buttons, matching its behavior.

import React from 'react';


import { ToggleButton, ToggleButtonGroup } from 'react-magma-dom';


export function Example() {
  const [view, setView] = React.useState('teacher');


  return (
    <>
      <ToggleButtonGroup
        role="tablist"
        exclusive
        enforced
        value={view}
        onChange={(_event, value) => {
          if (value) {
            setView(value);
          }
        }}
      >
        <ToggleButton value="teacher" aria-controls="course-view-panel">
          Teacher view
        </ToggleButton>
        <ToggleButton value="student" aria-controls="course-view-panel">
          Student view
        </ToggleButton>
      </ToggleButtonGroup>
      <div
        id="course-view-panel"
        role="tabpanel"
        style={{ paddingTop: '12px' }}
      >
        {view === 'teacher'
          ? 'Showing the teacher view of the course.'
          : 'Showing the student view of the course.'}
      </div>
    </>
  );
}

Radio Group

Use role="radiogroup" for a single-choice selection that should be announced as a radio group. The buttons render as radios regardless, so pair the role with exclusive to keep the single-select behavior consistent with the radio group semantics.

import React from 'react';


import { ToggleButton, ToggleButtonGroup } from 'react-magma-dom';


export function Example() {
  return (
    <ToggleButtonGroup role="radiogroup" exclusive value="medium">
      <ToggleButton value="low">Low</ToggleButton>
      <ToggleButton value="medium">Medium</ToggleButton>
      <ToggleButton value="high">High</ToggleButton>
    </ToggleButtonGroup>
  );
}

No Space

Removes margins and border radius on each button then applies the border-radius around the container.

import React from 'react';


import { ToggleButton, ToggleButtonGroup } from 'react-magma-dom';
import {
  FormatAlignCenterIcon,
  FormatAlignJustifyIcon,
  FormatAlignLeftIcon,
  FormatAlignRightIcon,
} from 'react-magma-icons';


export function Example() {
  return (
    <ToggleButtonGroup noSpace>
      <ToggleButton
        aria-label="Left align"
        icon={<FormatAlignLeftIcon />}
        value="left"
      />
      <ToggleButton
        aria-label="Center align"
        icon={<FormatAlignCenterIcon />}
        value="center"
      />
      <ToggleButton
        aria-label="Right align"
        icon={<FormatAlignRightIcon />}
        value="right"
      />
      <ToggleButton
        aria-label="Justify align"
        icon={<FormatAlignJustifyIcon />}
        value="justify"
      />
    </ToggleButtonGroup>
  );
}

Size

Three sizes are configurable with the ButtonSize prop between small, medium (default), and large across the group.

import React from 'react';


import { ButtonSize, ToggleButton, ToggleButtonGroup } from 'react-magma-dom';


export function Example() {
  return (
    <ToggleButtonGroup size={ButtonSize.small}>
      <ToggleButton value="1">Toggle 1</ToggleButton>
      <ToggleButton value="2">Toggle 2</ToggleButton>
      <ToggleButton value="3" size={ButtonSize.large}>
        Toggle 3
      </ToggleButton>
    </ToggleButtonGroup>
  );
}

Inverse

import React from 'react';


import { Container, ToggleButton, ToggleButtonGroup } from 'react-magma-dom';


export function Example() {
  return (
    <Container isInverse style={{ padding: '12px' }}>
      <ToggleButtonGroup isInverse>
        <ToggleButton value="1">Toggle 1</ToggleButton>
        <ToggleButton value="2">Toggle 2</ToggleButton>
        <ToggleButton value="3">Toggle 3</ToggleButton>
      </ToggleButtonGroup>
    </Container>
  );
}

ToggleButtonGroup Props

Any other props supplied will be provided to the wrapping div element.

children

Required

Description

The content of the component

Type

React.ReactNode

Default

-

descriptionId

Description

Description for aria-describedby

Type

string

Default

-

enforced

Description

Enables a radio configuration throughout the group retaining an active selection at all times.

Type

boolean

Default

false

exclusive

Description

Sets the Toggle Button group to have only one active selection.

Type

boolean

Default

false

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

onChange

Description

The onChange handler for managing state of toggle buttons by your custom logic.

Type

function

Default

-

role

Description

ARIA role for the group container. `tablist` renders children as tabs (`aria-selected`); `radiogroup` renders them as radios (`aria-checked`); `group` renders radios or switches based on `exclusive`. `tablist` and `radiogroup` are single-select patterns, so pair them with `exclusive` (and `enforced` for tabs, to keep one selected at all times).

Type

enum, one of:
ToggleButtonGroupRole.group
ToggleButtonGroupRole.radiogroup
ToggleButtonGroupRole.tablist

Default

ToggleButtonGroupRole.group

value

Description

Value of the toggle button that is the default selected value for the group

Type

string

Default

-

On this page

Deploys by Netlify