Grid Toolbar container for UI operations

The 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 Grid and it matches its horizontal size. The toolbar container hosts different UI controls which are related to some of the Grid's features - column hiding, column pinning, excel exporting, etc and supports Angular events.

Demo


The toolbar is shown using the Grid's showToolbar property - just set it to true. The toolbar supports a textual title which is left aligned and its content is set using the Grid's toolbarTitle property. The following code snippet demonstrates how to enable a toolbar and set its title:

<igx-grid [data]="data" [autoGenerate]="true" height="400px" width="600px"
    [showToolbar]="true"
    toolbarTitle="Grid Title">
</igx-grid>

Features

The toolbar can be configured to allow column hiding, column pinning and exporting data to MS Excel and CSV. You can enable each feature independently by setting its dedicated boolean property to true:

There are also properties for configuring each button's text and they are listed in the API section below.


The following code snippet demonstrates how to enable all features of the toolbar:

<igx-grid [data]="data" [autoGenerate]="true" height="400px" width="600px"
    [showToolbar]="true"
    toolbarTitle="Grid Title"
    [columnHiding]="true"
    [columnPinning]="true"
    [exportExcel]="true"
    [exportCsv]="true"
    exportText="Export"
    exportExcelText="Export to Excel"
    exportCsvText="Export to CSV">
</igx-grid>

The export to MS Excel and the export to CSV features are using respectively the IgxExcelExporterService and IgxCsvExporterService as providers. If you need to use any of them you should specify them in the providers array of your app.module.ts file. For example the following code snippet demonstrates how to include all exporter services:

// app.module.ts

...
import { IgxExcelExporterService, IgxCsvExporterService } from "igniteui-angular";

@NgModule({
  providers: [ IgxExcelExporterService, IgxCsvExporterService ]
})

export class AppModule {}

Customizing the Export

In addition to simply switching on and off the toolbar features, the export process can be further configured in the onToolbarExporting event which is emitted when the user initiates the export process. This event exposes both the exporter and the exporter's options.

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 how to subscribe to the onToolbarExporting event and cancel the default exporting process.

<igx-grid ... (onToolbarExporting)="toolbarExportingHandler($event)"></igx-grid>
import { IgxExcelExporterService, IgxCsvExporterService } from "igniteui-angular";

...

public toolbarExportingHandler(args) {
    // You can customize the exporting from this event
    const options: IgxExporterOptionsBase = args.options ;
    options.fileName = "Custom Title";

    if (options instanceof IgxExcelExporterOptions) {
        const excelOptions = options as IgxExcelExporterOptions;
        excelOptions.columnWidth = 10;
    } else {
        const csvOptions = options as IgxCsvExporterOptions;
        csvOptions.fileType = CsvFileTypes.TSV;
        csvOptions.valueDelimiter = "\t";
    }

    args.exporter.onColumnExport.subscribe((columnArgs: IColumnExportingEventArgs) => {

        // Don't export image fields
        columnArgs.cancel = columnArgs.header === "Athlete" ||
                            columnArgs.header === "Country";


    });
}

The following sample demonstrates how to customize the exported files:


Custom Content Template

If you need to add some application specific UI to the toolbar (like custom buttons for example) you may create an ng-template and mark it with the igxToolbarCustomContent directive. The following code snippet demonstrates how to define such custom template:

<igx-grid [showToolbar]="true" ...>

    ...

    <ng-template igxToolbarCustomContent let-grid="grid">
        <button igxButton="flat" igxRipple igxRippleCentered="true" (click)="grid.clearSort()">
            <igx-icon fontSet="material">clear</igx-icon>
            Clear Sort
        </button>
    </ng-template>
</igx-grid>
Note

The igxToolbarCustomContent directive's context contains two properties: grid - a reference to the IgxGridComponent containing the toolbar and toolbar - a reference to the IgxGridToolbarComponent

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:

// custom-grid-paging-style.component.scss
@import '~igniteui-angular/lib/core/styles/themes/index';

Following the simplest approach, we create a new theme that extends the igx-grid-toolbar-theme and accepts the $background-color, $title-text-color, $button-background, $button-text-color, $button-hover-background and the $button-hover-text-color parameters.

$dark-grid-toolbar-theme: igx-grid-toolbar-theme(
    $background-color: #292826,
    $title-text-color: #FFCD0F,
    $button-background: #FFCD0F,
    $button-text-color: #292826,
    $button-hover-background: #404040,
    $button-hover-text-color: #FFCD0F
);

As seen, the igx-grid-toolbar-theme only controls colors for the toolbar container and the buttons inside of it by taking advantage of the respective parameters for the button (e.g. $button-background). (Buttons outside the toolbar will not be affected.)

The last step is to include the newly created theme.

@include igx-grid-toolbar($dark-grid-toolbar-theme);
Note

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

:host {
    ::ng-deep {
        @include igx-grid-toolbar($dark-grid-toolbar-theme);
    }
}

Defining a color palette

Instead of hardcoding the color values like we just did, we can achieve greater flexibility in terms of colors by using the igx-palette and igx-color functions.

igx-palette generates a color palette based on the primary and secondary colors that are passed:

$yellow-color: #FFCD0F;
$black-color: #292826;

$dark-palette: igx-palette($primary: $black-color, $secondary: $yellow-color);

And then with igx-color we can easily retrieve color from the palette.

$dark-grid-toolbar-theme: igx-grid-toolbar-theme(
    $background-color: igx-color($dark-palette, "primary", 200),
    $title-text-color: igx-color($dark-palette, "secondary", 400),
    $button-background: igx-color($dark-palette, "secondary", 400),
    $button-text-color: igx-color($dark-palette, "primary", 400),
    $button-hover-background: igx-color($dark-palette, "primary", 400),
    $button-hover-text-color: igx-color($dark-palette, "secondary", 400)
);
Note

The igx-color and igx-palette are powerful functions for generating and retrieving colors. Please refer to Palettes topic for detailed guidance on how to use them.

Using Schemas

Going further with the theming engine, you can build a robust and flexible structure that benefits from schemas. A schema is a recipe of a theme.

Extend one of the two predefined schemas, that are provided for every component, in this case - dark-grid-toolbar schema:

 Extending the dark toolbar schema
$dark-grid-toolbar-schema: extend($_dark-grid-toolbar,
    (
        background-color:(
            igx-color: ("primary", 200)
        ),
        title-text-color:(
            igx-color: ("secondary", 400)
        ),
        button-background:(
            igx-color: ("secondary", 400)
        ),
        button-text-color:(
            igx-color: ("primary", 400)
        ),
        button-hover-background:(
            igx-color: ("primary", 400)
        ),
        button-hover-text-color:(
            igx-color: ("secondary", 400)
        )
    )
);

In order to apply our custom schemas we have to extend one of the globals (light or dark), which is basically pointing out the components with a custom schema, and after that add it to the respective component themes:

// Extending the global dark-schema
$custom-dark-schema: extend($dark-schema,(
    igx-grid-toolbar: $dark-grid-toolbar-schema
));

// Defining grid-toolbar-theme with the global dark schema
$dark-grid-toolbar-theme: igx-grid-toolbar-theme(
  $palette: $dark-palette,
  $schema: $custom-dark-schema
);

Don't forget to include the themes in the same way as it was demonstrated above.

Demo


API References

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

IgxGridToolbarComponent

IgxGridComponent properties:

IgxGridComponent events:

Styles:

Additional Resources

Our community is active and always welcoming to new ideas.