Button Group Component

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

Live Demo

Anatomy

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

The Angular 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 Angular Button Group, follow the Ignite UI for Angular 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 Angular package for your target framework. Keep the framework package, the Button Group package, and the theme package on the same release version.

For Angular using the igniteui-angular package, install the package:

ng add igniteui-angular

Then import IgxButtonGroupModule in an NgModule application, or import IGX_BUTTON_GROUP_DIRECTIVES and the required standalone components in the component imports collection.

import { IGX_BUTTON_GROUP_DIRECTIVES } from 'igniteui-angular/button-group';
import { IgxIconComponent } from 'igniteui-angular/icon';

For a complete introduction to Ignite UI for Angular, read the Getting Started topic.

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

<igx-buttongroup></igx-buttongroup>

Usage

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

<igx-buttongroup>
    <button igxButton>
        <igx-icon>format_align_left</igx-icon>
    </button>
    <button igxButton>
        <igx-icon>format_align_center</igx-icon>
    </button>
    <button igxButton selected>
        <igx-icon>format_align_justify</igx-icon>
    </button>
</igx-buttongroup>

Alignment

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

For Angular, set the alignment input with the ButtonGroupAlignment enum:

import { ButtonGroupAlignment } from 'igniteui-angular/button-group';

public alignment = ButtonGroupAlignment.vertical;

<igx-buttongroup [alignment]="alignment">
    <button igxButton>Sofia</button>
    <button igxButton>London</button>
    <button igxButton selected>New York</button>
    <button igxButton>Tokyo</button>
</igx-buttongroup>

Selection

In order to configure the Ignite UI for Angular ButtonGroup 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 ButtonGroup selection modes:

The Angular selection modes are single, singleRequired, and multi.

Set the Angular selectionMode input to configure the selection behavior:

<igx-buttongroup [selectionMode]="'multi'">
    <button igxButton selected>Bold</button>
    <button igxButton>Italic</button>
    <button igxButton>Underline</button>
</igx-buttongroup>

A IgxToggleButton could be marked as selected via its Selected attribute or through the ButtonGroup SelectedItems attribute:

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 IgxToggleButton components.

Interaction States

The enabled buttons in the group support idle, hover, and focused interaction states. Use the state behavior provided by the contained IgxToggleButton 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 Angular, use the values input to provide an array of customized buttons. Each item can define properties such as label, icon, selected, disabled, and togglable.

Define the button values in the component class:

interface IButton {
    label?: string;
    icon?: string;
    disabled?: boolean;
    togglable?: boolean;
    selected?: boolean;
    color?: string;
}

public bordersButtons: IButton[] = [
    { icon: 'border_top', selected: true },
    { icon: 'border_right' },
    { icon: 'border_bottom' },
    { icon: 'border_left' }
];

<igx-buttongroup [selectionMode]="'multi'" [values]="bordersButtons"></igx-buttongroup>

See the Angular Button Group sample for the complete values model and configuration.

Size

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

igx-buttongroup {
    --ig-size: var(--ig-size-small);
}

<igx-buttongroup></igx-buttongroup>

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 IgxToggleButton 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 Angular Button Group theme exposes Sass parameters for the group items and their interaction states. Changing a primary theme property updates its related state properties to keep the component visually consistent.

Sass Theming

Use the Angular theme system to customize the Button Group consistently with the rest of your application.

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

@use "igniteui-angular/theming" as *;

Create a theme with button-group-theme and include it in the component scope:

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

:host {
    @include tokens($custom-button-group);
}

CSS Variables

Use the Angular theme tokens to customize the Button Group item colors and interaction states. The primary Sass parameters listed below update their related state tokens.

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:

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

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

Styling with Tailwind

You can style the Angular Button Group with the Ignite UI Tailwind utility classes. First, set up Tailwind, then import the utility file in the global stylesheet:

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

Use light-button-group or dark-button-group for the corresponding theme and override generated CSS variables with arbitrary properties:

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

The exclamation mark (!) makes the utility class important so it takes precedence over the component theme.

Accessibility

The Button Group groups related Toggle Buttons while preserving the interaction and accessible state of each button. Provide meaningful content for every button and choose a selection mode that matches the intended interaction.

Keyboard Interaction

The Angular Button Group follows the keyboard behavior of its Toggle Buttons. Use the keyboard interaction provided by the contained buttons and verify the focus order and selection behavior for the configured selection mode.

Screen Readers / ARIA

Use clear labels for every Angular Toggle Button so assistive technology users can identify each option and its selected state. When an icon does not provide an accessible name, provide an appropriate text label or accessible name for the button.

Accessibility Compliance

Verify the rendered Angular Button Group against the accessibility requirements of the application. Check the button names, focus order, selected state announcements, and behavior for the configured selection mode in the target framework.

Troubleshooting

The Angular 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 Angular 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 Angular 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 Angular resources for API details and project support:

• Ignite UI for Angular Forums
• Ignite UI for Angular GitHub

Related Components

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

• IgxToggleButton

FAQ

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