Button Group Component

The React Button Group component is used to organize IgrToggleButton’s into styled button groups with horizontal/vertical alignment, single/multiple selection and toggling.

Live Demo

Anatomy

The React Button Group organizes related Toggle Buttons into a single group with a shared container and individual button items.

The React Button Group contains Toggle Buttons, and each button can contain an icon and a label.

Button Group
└── Toggle Button
    ├── Icon
    └── Label

Getting Started

To use the React Button Group, follow the Ignite UI for React Getting Started topic for the basic project setup, then register the component for your target platform.

Prerequisites and Version Compatibility

Use a supported version of the Ignite UI for React package for your target framework. Keep the framework package, the Button Group package, and the theme package on the same release version.

For React using the igniteui-react package, install the package:

npm install igniteui-react

Then import the Button Group wrapper and its theme CSS:

import { IgrButtonGroup } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

The simplest way to start using the IgrButtonGroup is as follows:

<IgrButtonGroup />

Usage

Use the IgrButtonGroup to wrap your IgrToggleButton components. To select a button by default, use the Selected attribute:

<IgrButtonGroup>
    <IgrToggleButton value="left">
        <IgrIcon name="format_align_left" collection="material"/>
        <IgrRipple/>
    </IgrToggleButton>
    <IgrToggleButton value="center">
        <IgrIcon name="format_align_center" collection="material"/>
        <IgrRipple/>
    </IgrToggleButton>
    <IgrToggleButton value="right">
        <IgrIcon name="format_align_right" collection="material"/>
        <IgrRipple/>
    </IgrToggleButton>
    <IgrToggleButton value="justify" selected={true}>
        <IgrIcon name="format_align_justify" collection="material"/>
        <IgrRipple/>
    </IgrToggleButton>
</IgrButtonGroup>

Alignment

The Button Group supports horizontal and vertical layouts. Use the Alignment property to set the orientation of the buttons in the group.

Selection

In order to configure the Ignite UI for React IgrButtonGroup selection, use its platform-specific selection property. For Angular, use selectionMode. For React, Web Components, and Blazor, use selection. The available modes are:

• single - default selection mode of the button group. A single button can be selected/deselected by the user.
• single-required - mimics a radio group behavior. Only one button can be selected and once initial selection is made, deselection is not possible through user interaction.
• multiple - multiple buttons in the group can be selected and deselected.

The sample below demonstrates the exposed IgrButtonGroup selection modes:

A IgrToggleButton could be marked as selected via its Selected attribute or through the IgrButtonGroup SelectedItems attribute:

<IgrButtonGroup selectedItems={['bold']}>
    <IgrToggleButton value="bold">
        <IgrIcon name="bold" collection="material" />
        <IgrRipple />
    </IgrToggleButton>
    <IgrToggleButton value="italic">
        <IgrIcon name="italic" collection="material" />
        <IgrRipple />
    </IgrToggleButton>
    <IgrToggleButton value="underlined">
        <IgrIcon name="underlined" collection="material" />
        <IgrRipple />
    </IgrToggleButton>
</IgrButtonGroup>

States

Each button in the group supports enabled and disabled variants, which can also be selected or not selected. Use the state behavior provided by the contained IgrToggleButton components.

Interaction States

The enabled buttons in the group support idle, hover, and focused interaction states. Use the state behavior provided by the contained IgrToggleButton components.

Layout Template

Each button can use text, an icon, or both. Keep the content style consistent across the group, and use the button content APIs to control the icon and label shown in each button.

Custom Toggle Buttons

For React, use individual Toggle Buttons to create a custom Button Group. Each button can define its own value, icon, label, selected state, and disabled state.

Import the Button Group, Toggle Button, and Icon components:

import { IgrButtonGroup, IgrToggleButton, IgrIcon } from 'igniteui-react';

Then define the custom buttons in JSX:

<IgrButtonGroup>
    <IgrToggleButton value="align-left">
        <IgrIcon name="format_align_left" collection="material" />
    </IgrToggleButton>
    <IgrToggleButton value="align-center" selected={true}>
        <IgrIcon name="format_align_center" collection="material" />
    </IgrToggleButton>
    <IgrToggleButton value="align-right" disabled={true}>
        <IgrIcon name="format_align_right" collection="material" />
    </IgrToggleButton>
</IgrButtonGroup>

Size

The --ig-size CSS custom property can be used to control the size of the button group.

<IgrButtonGroup style={{ '--ig-size': 'var(--ig-size-small)' } as React.CSSProperties}>
</IgrButtonGroup>

Do/Don’t

When to use: Use a Button Group to organize related toggle actions where users may select one or more options.

When not to use: Do not use a Button Group for unrelated actions or for a single toggle action; use a standalone IgrToggleButton instead.

Do	Don’t

Properties

The Button Group properties are generated from the component API reference.

The property rows are injected from the typed API source during the documentation build.

Styling

The React Button Group uses CSS parts to style the group container and the individual Toggle Buttons. Use the group part on the Button Group and the toggle part on each Toggle Button to customize their appearance.

Sass Theming

Use the Ignite UI for React theme system to style the Button Group consistently with the rest of your application.

Import the theming functions before creating a custom Button Group theme:

@use "igniteui-theming" as *;

Create a theme with button-group-theme and include it in the global stylesheet. The $item-background parameter is used as the base for the related interaction-state colors. Override additional parameters when you need more control over the Button Group appearance:

$custom-button-group: button-group-theme(
    $item-background: #57a5cd,
);

igc-button-group {
    @include button-group($custom-button-group);
}

The same theme applies to Web Components directly and to the underlying igc-button-group element rendered by the React and Blazor wrappers.

CSS Variables

Use the following CSS variables to customize the Button Group item colors and interaction states. Set them on the Button Group element to apply the styles to its contained Toggle Buttons:

Style Parts

Use the following CSS parts to target the Button Group and its contained Toggle Buttons:

Custom Styling

The following example changes the group background and padding, and changes the text color of the contained Toggle Buttons:

igc-button-group::part(group) {
  background-color: var(--ig-primary-500);
  padding: 8px;
}

igc-toggle-button::part(toggle) {
  color: var(--ig-secondary-300);
}

Styling with Tailwind

You can style the React Button Group with the custom Tailwind utility classes from igniteui-theming. Make sure to set up Tailwind first, then import the Ignite UI utilities in your global stylesheet:

@import "tailwindcss";
@import "igniteui-theming/tailwind/utilities/material.css";

<IgrButtonGroup className="!light-button-group ![--item-background:#7B9E89]"></IgrButtonGroup>

The exclamation mark (!) gives the Tailwind utility precedence over the Button Group’s default theme styles.

Accessibility

The React Button Group organizes related Toggle Buttons while exposing each button’s selected and disabled state.

Keyboard Interaction

The Button Group delegates keyboard interaction to its contained Toggle Buttons. Each Toggle Button renders a native button, so standard button keyboard behavior activates the focused item and updates its selection according to the configured selection mode.

When the Button Group is disabled, it disables its contained Toggle Buttons so they are not keyboard interactive.

Screen Readers / ARIA

The Button Group exposes a group relationship and each Toggle Button exposes its state through native button semantics.

• The group container uses role="group" and reflects the group disabled state through aria-disabled.
• Each Toggle Button renders a native button with aria-pressed for selection state and aria-disabled for disabled state.
• The group emits igcSelect and igcDeselect after user interaction changes a Toggle Button selection. The event detail is the Toggle Button value.
• Provide visible text or an aria-label for every Toggle Button, especially for icon-only controls.

Accessibility Compliance

Infragistics documents Ignite UI for React accessibility support for Section 508 and WCAG 2.1 guideline areas in the Accessibility Compliance topic.

Your responsibilities:

• Give each Toggle Button a clear visible label or accessible name, especially when it contains only an icon.
• Keep the group selection mode aligned with the control purpose, so users can understand whether one or multiple options may be selected.
• Preserve the logical button order and sufficient color contrast when customizing the group or its selected state.

Troubleshooting

The React Button Group troubleshooting guidance follows a problem, cause, and fix format for common selection issues.

Why does selectedItems not select a button?

Ensure every Toggle Button has a unique value attribute. The selectedItems property depends on those values.

Known Limitations

The React Button Group coordinates Toggle Buttons but does not replace their individual labels or accessible names.

• Selection behavior depends on the configured selection mode.
• The selectedItems property depends on unique value attributes on the contained Toggle Buttons.
• The Button Group does not provide labels or icons for its buttons; define the content of each Toggle Button separately.

API References

Dependencies

The React Button Group requires the platform package and its theme stylesheet. The examples also use Toggle Button, Icon, and Ripple components.

Additional Resources

Use the following React resources for API details and project support:

• Ignite UI for React Forums
• Ignite UI for React GitHub

Related Components

The React Button Group is built from selectable Toggle Buttons. Use the following related component when you need an individual toggle action instead of a group:

• IgrToggleButton

FAQ

These frequently asked questions cover common React Button Group selection, content, and setup scenarios.