Skip to content

button-group.mdx

Latest commit

 

History

History
369 lines (285 loc) · 13.8 KB

button-group.mdx

File metadata and controls

369 lines (285 loc) · 13.8 KB
Raw
title Angular Button Group Component – Ignite UI for Angular | Infragistics | MIT license
description Provides button group functionality to developers and also allows horizontal/vertical alignment, single/multiple selection with toggling.
keywords Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Native Angular Controls, Native Angular Components Library, Angular Button Group components, Angular Button Group controls, Angular Buttons components, Angular Buttons controls
license MIT
llms
description
Angular Button Group component is used to organize buttons into styled button groups with horizontal/vertical alignment, single/multiple selection and toggling.

import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro';

Angular Button Group Component Overview

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

Angular Button Group Example

Getting Started with Ignite UI for Angular Button Group

To get started with the Ignite UI for Angular Button Group component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command:

ng add igniteui-angular

For a complete introduction to the Ignite UI for Angular, read the getting started topic.

The next step is to import the IgxButtonGroupModule in your app.module.ts file.

// app.module.ts

...
import { IgxButtonGroupModule } from 'igniteui-angular/button-group';
// import { IgxButtonGroupModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [..., IgxButtonGroupModule],
    ...
})
export class AppModule {}

Alternatively, as of 16.0.0 you can import the IgxButtonGroupComponent as a standalone dependency, or use the IGX_BUTTON_GROUP_DIRECTIVES token to import the component and all of its supporting components and directives.

// home.component.ts

...
import { IGX_BUTTON_GROUP_DIRECTIVES } from 'igniteui-angular/button-group';
import { IgxIconComponent } from 'igniteui-angular/icon';
// import { IGX_BUTTON_GROUP_DIRECTIVES, IgxIconComponent } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: `
    <igx-buttongroup>
        <button igxButton>
            <igx-icon>format_align_left</igx-icon>
        </button>
        <button igxButton>
            <igx-icon>format_align_center</igx-icon>
        </button>
        <button igxButton>
            <igx-icon>format_align_right</igx-icon>
        </button>
        <button igxButton selected>
            <igx-icon>format_align_justify</igx-icon>
        </button>
    </igx-buttongroup>
    `,
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [IGX_BUTTON_GROUP_DIRECTIVES, IgxIconComponent]
    /* or imports: [IgxButtonGroupComponent, IgxButtonDirective, IgxIconComponent] */
})
export class HomeComponent {}
This component uses Material Icons. Add the following link to your `index.html`: ``

Now that you have the Ignite UI for Angular Button Group module or directives imported, you can start with a basic configuration of the igx-buttongroup and its buttons.

Using for Angular Button Group Component

Add Button Group

Use the selector to wrap your buttons and display them into a button group. If you want a button to be selected by default, use the selected property:

{/* sample.component.html */}
<igx-buttongroup>
  <button igxButton>
    <igx-icon>format_align_left</igx-icon>
  </button>
  <button igxButton>
    <igx-icon>format_align_center</igx-icon>
  </button>
  <button igxButton>
    <igx-icon>format_align_right</igx-icon>
  </button>
  <button igxButton selected>
    <igx-icon>format_align_justify</igx-icon>
  </button>
</igx-buttongroup>

Examples

Alignment

Use the input property to set the orientation of the buttons in the button group.

//sample.component.ts
import { ButtonGroupAlignment } from 'igniteui-angular/button-group';
// import { ButtonGroupAlignment } from '@infragistics/igniteui-angular'; for licensed package

...
public alignment = ButtonGroupAlignment.vertical;
...
{/* sample.component.html */}
<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 igx-buttongroup selection, you could use its property. This property accepts the following three modes:

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

The sample below demonstrates the exposed igx-buttongroup selection modes:

Size

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

/* sample.component.scss */
igx-buttongroup {
  --ig-size: var(--ig-size-small);
}
{/* sample.component.html */}
<igx-buttongroup></igx-buttongroup>

Custom toggle buttons

Use the input property to set an array of customized buttons in the button group.

// sample.component.ts

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

class ToggleButton {
    private ripple: string;
    private label: string;
    private disabled: boolean;
    private togglable: boolean;
    private selected: boolean;
    private color: string;
    private icon: string;

    constructor(obj?: IButton) {
        this.ripple = obj.ripple || 'gray';
        this.label = obj.label;
        this.selected = obj.selected || false;
        this.togglable = obj.togglable || true;
        this.disabled = obj.disabled || false;
        this.color = obj.color;
        this.icon = obj.icon;
    }
}
...
public bordersButtons: ToggleButton[];

public ngOnInit() {
    this.bordersButtons = [
        new ToggleButton({
            icon: 'border_top',
            selected: true
        }),
        new ToggleButton({
            icon: 'border_right',
            selected: false
        }),
        new ToggleButton({
            icon: 'border_bottom',
            selected: false
        }),
        new ToggleButton({
            icon: 'border_left',
            selected: false
        })
    ];
}
...
{/* sample.component.html */}
<igx-buttongroup [selectionMode]="'multi'" [values]="bordersButtons"></igx-buttongroup>

Styling

Button Group Theme Property Map

When you set a value for the $item-background property, all related dependent properties listed in the table below are automatically updated to maintain visual consistency. The table shows which properties are affected when you customize the primary property.

Primary Property Dependent Property Description
$item-background $item-hover-background The hover background color for items.
$item-selected-background The selected item background color.
$item-focused-background The focused item background color.
$disabled-background-color The disabled item background color.
$item-border-color The border color for items.
$item-text-color The text color for items.
$idle-shadow-color The idle shadow color for items.
$item-hover-background $item-selected-hover-background The selected item hover background color.
$item-focused-hover-background The focused hover background color.
$item-hover-text-color The text color for hovered items.
$item-hover-icon-color The icon color for hovered items.
$item-selected-background $item-selected-focus-background The selected item focus background color.
$disabled-selected-background The disabled selected background color.
$item-selected-text-color The text color for selected items.
$item-selected-icon-color The icon color for selected items.
$item-selected-hover-text-color The text color for selected hover items.
$item-selected-hover-icon-color The icon color for selected hover items.
$item-border-color $item-hover-border-color The border color for hovered items.
$item-focused-border-color The border color for focused items.
$item-selected-border-color The border color for selected items.
$item-selected-hover-border-color The border color for selected hover items.
$item-disabled-border The border color for disabled items.
$disabled-selected-border-color The border color for disabled selected items.

To get started with styling the button group, we need to import the index file, where all the theme functions and component mixins live:

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

// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';

Following the simplest approach, we create a new theme that extends the and specifying just the $item-background. Based on this value, the theme will automatically compute appropriate state colors, contrast foregrounds, and borders for the button group. Of course, you're still free to override any of the theme parameters with custom values if needed.

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

As seen, the button-group-theme exposes some useful parameters for basic styling of its items. If you want to drill deeper and change some button specific parameters, you can create a new theme that extends the button-theme and scope it under the respective button group class.

The last step is to include the component's theme.

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

Demo

Styling with Tailwind

You can style the button-group using our custom Tailwind utility classes. Make sure to set up Tailwind first.

Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows:

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

The utility file includes both light and dark theme variants.

  • Use light-* classes for the light theme.
  • Use dark-* classes for the dark theme.
  • Append the component name after the prefix, e.g., light-button-group, dark-button-group.

Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using arbitrary properties. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.).

You can find the full list of properties in the . The syntax is as follows:

<igx-button-group
class="!light-button-group ![--item-background:#7B9E89]"
>
...
</igx-button-group>
The exclamation mark(`!`) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme.

At the end your button group should look like this:

API References

- - - - ## Theming Dependencies

Additional Resources

Our community is active and always welcoming to new ideas.