Button Group Component

The Angular Button Group component is used to organize buttons with the IgxButton directive 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.

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

ng add igniteui-angular

Then 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';

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

<igx-buttongroup></igx-buttongroup>

Usage

Use the IgxButtonGroup to wrap buttons using the IgxButton directive. Set the selected input on a button to select it by default:

<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 Button Group selection, use its platform-specific selection property.

For Angular, use the selectionMode property. 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>

An IgxButton can be marked as selected via its selected input or through the values input of the Button Group.

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

Interaction States

The enabled buttons in the group support idle, hover, and focused interaction states. Use the state behavior provided by the contained IgxButton 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 Angular Button Group exposes the following properties.

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 Angular 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".
• Angular updates each contained button’s aria-pressed value when its selection changes and disables child buttons when the group is disabled.
• The group emits selected and deselected when a user changes selection. Each event provides the selected Toggle Button and its index.
• Provide visible text, an igxLabel, or another accessible name for every icon-only button.

Accessibility Compliance

Infragistics documents Ignite UI for Angular 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

Use this section to check boundaries and common decisions before treating Button Group as a single toggle, form field, or action group.

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 Angular package and its theme stylesheet. The examples also use the IgxButton, IgxIcon, and IgxRipple 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

• Button - Use Button when you need an individual action instead of a selectable group.

FAQ