Angular Grid Toolbar - Ignite UI for Angular

The Tree Grid in Ignite UI for Angular provides an IgxGridToolbarComponent which is essentially a container for UI operations. The Angular toolbar is located at the top of the Angular component, i.e the Tree Grid and it matches its horizontal size. The toolbar container can host predefined UI controls for the following Tree Grid's features:

Column Hiding
Column Pinning
Excel Exporting
Advanced Filtering

or just any other custom content. The toolbar and the predefined UI components support Angular events and expose API for developers.

The predefined actions and title UI components are added inside the <igx-grid-toolbar> and this is all needed to have a toolbar providing default interactions with the corresponding Grid features:

<igx-tree-grid [data]="data" primaryKey="ID" foreignKey="ParentID" [autoGenerate]="true">
    <igx-grid-toolbar>
        <igx-grid-toolbar-title>Tree Grid Toolbar</igx-grid-toolbar-title>
        <igx-grid-toolbar-actions>
            <igx-grid-toolbar-advanced-filtering><igx-grid-toolbar-advanced-filtering>
            <igx-grid-toolbar-hiding></igx-grid-toolbar-hiding>
            <igx-grid-toolbar-pinning></igx-grid-toolbar-pinning>
            <igx-grid-toolbar-exporter></igx-grid-toolbar-exporter>
        </igx-grid-toolbar-actions>
    </igx-grid-toolbar>
</igx-tree-grid>

Note: As seen in the code snippet above, the predefined actions UI components are wrapped in the <igx-grid-toolbar-actions> container. This way, the toolbar title is aligned to the left of the toolbar and the actions are aligned to the right of the toolbar.

Of course, each of these UIs can be added independently of each other, or may not be added at all. This way the toolbar container will be rendered empty:

<igx-tree-grid [data]="data" primaryKey="ID" foreignKey="ParentID" [autoGenerate]="true">
    <igx-grid-toolbar>
    </igx-grid-toolbar>
</igx-tree-grid>

For a comprehensive look over each of the default UI components, continue reading the Features section below.

Features

The toolbar is great at separating logic/interactions which affects the grid as a whole. As shown above, it can be configured to provide default components for controlling, column hiding, column pinning, advanced filtering and exporting data from the grid. These features can be enabled independently from each other by following a pattern similar to the card component of the Ignite UI for Angular suite. Listed below are the main features of the toolbar with example code for each of them.

Title

Setting a title for the toolbar in your grid is achieved by using the IgxGridToolbarTitleComponent. Users can provide anything from simple text to more involved templates.

<igx-grid-toolbar>
    <igx-grid-toolbar-title>Grid toolbar title</igx-grid-toolbar-title>
</igx-grid-toolbar>

Actions

The toolbar exposes a specific container where users can place actions/interactions in relation to the parent grid. As with the title portion of the toolbar, users can provide anything inside that template part, including the default toolbar interaction components.

<igx-grid-toolbar>
    <igx-grid-toolbar-actions>
        <button igxButton>Action</button>
        <igx-select></igx-select>
        ...
    </igx-grid-toolbar-actions>
</igx-grid-toolbar>

Each action now exposes a way to change the overlay settings of the actions dialog by using the overlaySettings input, example:

<igx-grid-toolbar-actions>
    <igx-grid-toolbar-pinning [overlaySettings]="overlaySettingsScaleCenter"></igx-grid-toolbar-pinning>
    <igx-grid-toolbar-hiding [overlaySettings]="overlaySettingsAuto"></igx-grid-toolbar-hiding>
</igx-grid-toolbar-actions>

public data: any[];
public positionStrategyScaleCenter = new GlobalPositionStrategy({
    openAnimation: scaleInCenter,
    closeAnimation: scaleOutCenter
});
public overlaySettingsScaleCenter = {
    positionStrategy: this.positionStrategyScaleCenter,
    scrollStrategy: new AbsoluteScrollStrategy(),
    modal: true,
    closeOnEscape: true
};

public positionStrategyAuto = new AutoPositionStrategy();
public overlaySettingsAuto = {
    positionStrategy: this.positionStrategyAuto,
    scrollStrategy: new AbsoluteScrollStrategy(),
    modal: false,
    closeOnEscape: false
};
constructor() {
    this.data = athletesData;
}

The default overlaySettings are using ConnectedPositionStrategy with Absolute scroll strategy, modal set to false, with enabled close on escape and close on outside click interactions.

Column pinning

Toolbar Pinning component provides the default UI for interacting with column pinning in the grid. The component is setup to work out of the box with the parent grid containing the toolbar as well as several input properties for customizing the UI, such as the component title, the placeholder for the component input and the height of the dropdown itself.

<igx-grid-toolbar>
    <igx-grid-toolbar-actions>
        <igx-grid-toolbar-pinning
            title="Grid pinned columns"
            prompt="Filter column collection"
            columnListHeight="400px"
        >
        </igx-grid-toolbar-pinning>
    </igx-grid-toolbar-actions>
</igx-grid-toolbar>

Column hiding

Toolbar Hiding component provides the default UI for interacting with column hiding. Exposes the same input properties for customizing the UI, such as the component title, the placeholder for the component input and the height of the dropdown itself.

<igx-grid-toolbar>
    <igx-grid-toolbar-actions>
        <igx-grid-toolbar-hiding
            title="Grid column hiding"
            prompt="Filter column collection"
            columnListHeight="400px"
        >
        </igx-grid-toolbar-hiding>
    </igx-grid-toolbar-actions>
</igx-grid-toolbar>

Advanced filtering

Toolbar Advanced Filtering component provides the default UI for the Advanced Filtering feature. The component exposes a way to change the default text of the button.

<igx-grid-toolbar>
    <igx-grid-toolbar-actions>
        <igx-grid-toolbar-advanced-filtering>Custom text for the toggle button</igx-grid-toolbar-advanced-filtering>
    </igx-grid-toolbar-actions>
</igx-grid-toolbar>

Data exporting

As with the rest of the toolbar actions, exporting is provided through a Toolbar Exporter component out of the box. The exporting component is using the respective service for the target data format (Excel CSV). That means if the respective service is not provided through the dependency injection chain, the component won't be able to export anything. If you need a refresher on the DI in Angular, check the official guide. Here is a sample snippet showing how to enable all export services for your application.

// app.module.ts

import { IgxExcelExporterService, IgxCsvExporterService } from 'igniteui-angular';
// import { IgxExcelExporterService, IgxCsvExporterService } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    providers: [IgxExcelExporterService, IgxCsvExporterService ]
})
export class AppModule { ... }

Note

In v12.2.1 and later, the exporter services are provided in root, which means you no longer need to declare them in the AppModule providers.

The toolbar exporter component exposes several input properties for customizing both the UI and the exporting experience. These range from changing the display text, to enabling/disabling options in the dropdown to customizing the name of the generated file. For full reference, consult the API documentation for the toolbar exporter component.

Here is a snippet showing some of the options which can be customized through the Angular template:

<igx-grid-toolbar>
    <igx-grid-toolbar-actions>
        <igx-grid-toolbar-exporter
            <!-- If active, enables the csv export entry in the dropdown UI -->
            [exportCSV]="csvExportEnabled"
            <!-- If active, enables the excel export entry in the dropdown UI -->
            [exportExcel]="excelExportEnabled"
            <!-- The name of the generated export file without the file extension -->
            filename="exported_data"
        >
            Custom text for the exporter button
            <span excelText>Custom text for the excel export entry</span>
            <span csvText>Custom text for the CSV export entry</span>
        </igx-grid-toolbar-exporter>
    </igx-grid-toolbar-actions>
</igx-grid-toolbar>

In addition to changing the exported filename, the user can further configure the exporter options by waiting for the toolbarExporting event and customizing the options entry in the event properties.

Note

By default when exporting to CSV the exporter exports using a comma separator and uses a '.csv' extension for the output file. You can customize these exporting parameters by subscribing to events of the exporter or changing the values of the exporter options fields. You can also cancel the export process by setting the cancel field of the event args to true.

The following code snippet demonstrates subscribing to the toolbar exporting event and configuring the exporter options:

<igx-tree-grid (toolbarExporting)="configureExport($event)" ></igx-tree-grid>

configureExport(args: IGridToolbarExportEventArgs) {
    const options: IgxExporterOptionsBase = args.options;
    
    options.fileName = `Report_${new Date().toDateString()}`;

    if (options instanceof IgxExcelExporterOptions) {
        options.columnWidth = 10;
    } else {
        options.fileType = CsvFileTypes.TSV;
        options.valueDelimiter = '\t';
    }

    args.exporter.columnExporting.subscribe((columnArgs: IColumnExportingEventArgs) => {
        
        
        // Don't export image field
        columnArgs.cancel = columnArgs.header === 'Name';
        
    });
}

The following sample demonstrates how to customize the exported files:

Exporting Indicator

When using the default toolbar exporter component, whenever an export operation takes place the toolbar will show a progress indicator while the operation is in progress. Moreover, users can set the toolbar showProgress property and use for their own long running operations or just as another way to signify an action taking place in the grid. The sample belows uses has significant amount of data, in order to increase the time needed for data export so the progressbar can be seen. Additionally it has another button that simulates a long running operation in the grid:

Custom Content

Note

This replaces the old toolbar template directive. If you are migrating from a version before v11 our migrations will handle the moving of the template content. However, we do not handle the bindings in the template, so make sure to double check the modified template files after the migration completes.

If the actions part of the toolbar component is not sufficient for a particular use case, the toolbar itself has a general content projection where users can provide additional UI. If the user needs the respective grid instance for API calls or bindings, they can create a template reference variable.

Here is a sample snippet:

<igx-tree-grid #gridRef ...>

    ...
    <igx-grid-toolbar>
        <igx-grid-toolbar-title>{{ titleBinding }}</igx-grid-toolbar-title>

        <!--
            Everything between the toolbar tags except the default toolbar components/directives
            will be projected as custom content.
         -->
        <button igxButton="flat" igxRipple (click)="#gridRef.clearSort()">
            <igx-icon fontSet="material">clear</igx-icon>
            Clear Sort
        </button>

        <igx-grid-toolbar-actions>
            ...
        </igx-grid-toolbar-actions>
    </igx-grid-toolbar>

</igx-tree-grid>

The following sample demonstrates how to add an additional button to the toolbar to clear the sorting set by clicking on the columns' headers:

Styling

To get started with styling the toolbar, 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';

First, let's create a new palette.

$my-dark-palette: palette(
    $primary: #2466ff,
    $secondary: #FFCD0F,
    $surface: #2a2b2f,
    $grays: #fff,
);

$my-dark-color: color($my-dark-palette, 'surface');

Now, create a new theme that extends the grid-toolbar-theme and modify the $background-color and the $title-text-color parameters.

$dark-grid-toolbar-theme: grid-toolbar-theme(
    $palette: $my-dark-palette,
    $background-color: $my-dark-color,
    $title-text-color: color($my-dark-palette, 'secondary'),
    $dropdown-background: $my-dark-color,
);

To theme the column actions menus of the toolbar, we have to change the theme of the column-actions-theme component.

$dark-column-actions-theme: column-actions-theme(
    $palette: $my-dark-palette,
    $title-color: color($my-dark-palette, 'secondary'),
    $background-color: color($my-dark-palette, 'surface')
);

Since the column actions are using other components - igx-button, igx-checkbox, and igx-input-group, we need to change their themes to match our new toolbar theme.

$dark-button-theme: button-theme(
    $palette: $my-dark-palette,
    $outlined-background: color($my-dark-palette, 'secondary'),
    $outlined-hover-background: color($my-dark-palette, 'grays', 100),
    $outlined-hover-text-color: color($my-dark-palette, 'secondary')
);

$dark-checkbox-theme: checkbox-theme(
    $palette: $my-dark-palette,
    $tick-color: $my-dark-color,
);

$dark-input-group-theme: input-group-theme(
    $palette: $my-dark-palette
);

The last step is to include the newly created themes.

:host {
    @include grid-toolbar($dark-grid-toolbar-theme);
    @include column-actions($dark-column-actions-theme);
    @include checkbox($dark-checkbox-theme);
    @include input-group($dark-input-group-theme);
    @include button($dark-button-theme);
}

Note

If $legacy-support is set to false(default), include the component css variables like that:

:host {
    @include css-vars($dark-grid-toolbar-theme);
    @include css-vars($dark-column-actions-theme);
    @include css-vars($dark-checkbox-theme);
    @include css-vars($dark-input-group-theme);
    @include css-vars($dark-button-theme);
}

Note

If the component is using an Emulated ViewEncapsulation, it is necessary to penetrate this encapsulation using ::ng-deep:

:host {
    ::ng-deep {
        @include grid-toolbar($dark-grid-toolbar-theme);
        @include column-actions($dark-column-actions-theme);
        @include checkbox($dark-checkbox-theme);
        @include input-group($dark-input-group-theme);
        @include button($dark-button-theme);
    }
}

Demo

API References

The Grid Toolbar service has a few more APIs to explore, which are listed below.

IgxTreeGridComponent events:

toolbarExporting

Styles:

IgxTreeGridComponent Styles

Additional Resources

Our community is active and always welcoming to new ideas.

Angular Tree Grid Toolbar

Angular Toolbar Grid Example

Features

Title

Actions

Column pinning

Column hiding

Advanced filtering

Data exporting

Note

Note

Exporting Indicator

Custom Content

Note

Styling

Note

Note

Demo

API References

Additional Resources

Theming