Expand All

  Getting Started

  Interfacing

  Features

  Row Models

  Themes

  Components

  Examples

  Third Party

Misc

Github stars make projects look great. Please help, donate a star, it's free.
Read about ag-Grid's Partnership with webpack.
Get informed on releases and other ag-Grid news only - never spam.
Follow on Twitter

Header Components

You can specify what header renderer to use at the column definition level. If not specified, the grid's default header rendering components will be used.

There are two types of header components:

  • Header Component: For rendering the normal column headers. Configured for columns.
  • Header Group Component: For rendering column groups. Configured for column groups.

You specify the header component to use in the column definition (or you can set in the default column definition to impact all columns).

// a list of column definitions
var myColumns = {

    // these columns use the default header
    {headerName: "Athlete", field: "athlete"},
    {headerName: "Sport", field: "sport"},

    // this column uses a custom header
    {headerName: "Age", field: "age", headerComponent: MyHeaderComponent},

    // you can also specify header components for groups
    {
        headerName: "Medals",
        // custom header component
        headerGroupComponent: MyHeaderGroupComponent,
        children: [
            {headerName: "Gold", field: "gold"},
            {headerName: "Silver", field: "silver"},
            {headerName: "Gold", field: "bronze"}
        ]
    }
}
Header Components were introduced in v8 of ag-Grid. Before this customising the header was done a different way. The old way is described below and marked 'deprecated'. A future version of ag-Grid will remove the old way. HOWEVER - we will not remove it until we have come up with a way to allow changing the default template of the new header components.

Header Component

This section details how to put a header component into ag-Grid. How to create header group components is explained in the next section.

Grid vs Your Responsibilities

A Header Component allows customising the inside part of the header. The component is wrapped inside a header cell so that the grid can take care of some complex logic that you should not be worried about, eg the resizing and moving of columns. The HTML of the header cell is similar to the following:

// the ag-header-cell is always provided by ag-Grid
// column moving and resize logic is put on this element by the grid
<div class="ag-header-cell">

    // ag-Grid will also always provide a resize bar (if column resizing
    // is enabled) and take care of all the resize logic. the grid usually
    // floats this element to the right.
    <div class="ag-header-cell-resize"/>

    // checkbox for selection, if turned on.
    // the grid usually floats this element to the left.
    <div class="ag-header-select-all"/>

    // the header component - this is the piece that you can customise
    <div class="ag-header-component"/>
</div>

The grid is always responsible for the following:

  • Resizing: When enabled, the grid will put an invisible widget to be grabbed by the mouse for resizing.
  • Checkbox Selection: When enabled, the grid puts a checkbox for 'select all' in the header.

The header component (your bit) will be responsible for the following:

  • Sorting: You will need to process user interaction for sorting. The default grid component sorts when the user clicks the header with the mouse. You may also need to display icons as the sort state of the column changes.
  • Filtering: You do not filter via the column (you filter from inside the menu), however you may need to display icons as the filter state of the column changes.
  • Menu: If you want the user to be able to open the column menu, you will need to manage this user interaction. The default grid component provides a button for the user to click to show the menu.
  • Anything Else: Whatever you want, you are probably creating a custom header to add your own functionality in.

Header Component Interface

Header components work similar to other component types in ag-Grid in which they should implement the following interface:

interface IHeaderComp {

    // optional method, gets called once with params
    init?(params: IHeaderCompParams): void;

    // gets called once, you should return the HTML element
    getGui(): HTMLElement;

    // optional method, gets called once, when component is destroyed
    destroy?(): void;

}

The params passed to init() are as follows:

export interface IHeaderCompParams {

    // the column the header is for
    column: Column;

    // the name to display for the column. if the column is using a headerValueGetter,
    // the displayName will take this into account.
    displayName: string;

    // whether sorting is enabled for the column. only put sort logic into
    // your header if this is true.
    enableSorting: boolean;

    // whether menu is enabled for the column. only display a menu button
    // in your header if this is true.
    enableMenu: boolean;

    // callback to progress the sort for this column.
    // the grid will decide the next sort direction eg ascending, descending or 'no sort'.
    // pass multiSort=true if you want to do a multi sort (eg user has shift held down when they click)
    progressSort(multiSort: boolean): void;

    // callback to set the sort for this column.
    // pass the sort direction to use ignoring the current sort eg one of 'asc', 'desc' or null (for no sort).
    // pass multiSort=true if you want to do a multi sort (eg user has shift held down when they click)
    setSort(sort: string, multiSort?: boolean): void;

    // callback to request the grid to show the column menu.
    // pass in the html element of the column menu to have the 
    // grid position the menu over the button.
    showColumnMenu(menuButton: HTMLElement): void;

     // The grid API
    api: any;
}

Sorting

How you interact with the user for sorting (eg do you listen for mouse clicks?) is up to you. The grid helps you by providing column state and events for getting and setting the sort.

After the user requests a sort, you should call ONE of the following:

  1. params.progressSort(multiSort): This is the simplest. Call it to progress the sort on the column to the next stage. Using this uses the grid logic for working out what the next sort stage is (eg 'descending' normally follows 'ascending').
  2. params.setSort(direction, multiSort): Use this to set to sort to a specific state. Use this if you don't want to use the grids logic for working out the next sort state.

// option 1) tell the grid when you want to progress the sorting
myHeaderElement.addEventListener('click', function(event) {
    // in this example, we do multi sort if shift key is pressed
    params.progressSort(event.shiftKey);
});

// or option 2) tell the grid when you want to set the sort explicitly
// button that always sorts ASCENDING
mySortAscButton.addEventListener('click', function(event) {
    params.setSort('asc', event.shiftKey);
});
// button that always sorts DESCENDING
mySortDescButton.addEventListener('click', function(event) {
    params.setSort('desc', event.shiftKey);
});

To know when a column's sort state has change (eg when to update your icons), you should listen for sortChanged event on the column.

// listen to the column for sort events
column.addEventListener('sortChanged', function() {

    // get sort state from column
    var sort = column.getSort();
    console.log('sort state of column is ' + sort); // prints one of ['asc',desc',null]

    // then do what you need, eg set relevant icons visible
    var sortingAscending = sort==='asc';
    var sortingDescending = sort==='desc';
    var notSorting = !sortingAscending && !sortingDescending;
    // how you update your GUI accordingly is up to you
});

// don't forget to remove your listener in your destroy code

Filtering

The header doesn't normally initiate filtering. If it does, use the standard grid API to set the filter. The header will typically display icons when the filter is applied. To know when to show a filter icon, listen to the column for filterChanged events.

// listen to the column for filter events
column.addEventListener('filterChanged', function() {
    // when filter changes on the col, this will print one of [true,false]
    console.log('filter of column is ' + column.isFilterActive());
});

// don't forget to remove your listener in your destroy code

How you get the user to ask for the column menu is up to you. When you want to display the menu, call the params.showColumnMenu() callback. The callback takes the HTML element for the button so that it can place the menu over the button (so the menu appears to drop down from the button).

myMenuButton.addEventListener('click', function() {
    params.showColumnMenu(myMenuButton);
});

Complementing Params

On top of the parameters provided by the grid, you can also provide your own parameters. This is useful if you want to 'configure' your header component. For example, you might have a header component for formatting currency but that needs the currency symbol.

colDef = {
    ...
    headerComponent: MyHeaderComponent;
    headerComponentParams : {
        currencySymbol: '£' // the pound symbol will be placed into params
    }
}

Example - Header Component

The example below shows a header component in action. The following can be observed in the demo:

  • Column moving and resizing is working without requiring any logic in the header component.
  • Some columns have suppressMenu=true, so the header component doesn't show the menu.
  • Some columns have suppressSorting=true, so the header component doesn't add sorting logic.
  • The header component uses additional parameters to allowing configuring the menu icon.

Header Group Component

This section details how to put a header group component into ag-Grid.

Grid vs Your Responsibilities

As with normal headers, ag-Grid will always handle resize and column moving. The grid does not handle selection checkbox as this feature is only at the non-grouped header level. The header group component (your bit) is responsible for the following:

  • Group Open / Close: If the group can expand (one or more columns visibility depends on the open / closed state of the group) then your header group component should handle the interaction with the user for opening and closing groups.
  • Anything Else: Whatever you want, it's your component!

Header Group Component Interface

The header group component interface is almost identical to the above header component. The only difference is the params object passed to the init() method.

export interface IHeaderGroupComp {

    // optional method, gets called once with params
    init?(params: IHeaderGroupCompParams): void;

    // gets called once, you should return the HTML element
    getGui(): HTMLElement;

    // optional method, gets called once, when component is destroyed
    destroy?(): void;

}

The params passed to init() are as follows:

export interface IHeaderGroupParams {

    // the column group the header is for
    columnGroup: ColumnGroup;

    // the text label to render. if the column is using a headerValueGetter,
    // the displayName will take this into account.
    displayName: string;

    // opens / closes the column group
    setExpanded(expanded: boolean): void;
}

Opening / Closing Groups

Not all column groups can open and close, so you should display open / close features accordingly. To check if a column group should have open / close functionality, check the isExpandable() method on the column group.

var showExpandableIcons = params.columnGroup.isExpandable()

To check if a column group is open or closed, check the isExpanded() method on the column group.

var groupIsOpen = params.columnGroup.isExpanded();

To open / close a column group, use the params.setExpanded(boolean) method.

// this code toggles the expanded state
var oldValue = params.columnGroup.isExpanded();
var newValue = !oldValue;
params.setExpanded(newValue);

To know if a group is expanded or collapsed, listen for the expandedChanged event on the column group.

// get a reference to the original column group
var columnGroup = params.columnGroup.getOriginalColumnGroup();
// create listener
var listener = function() { console.log('group was opened or closed'); };
// add listener
columnGroup.addEventListener('expandedChanged', listener);

// don't forget to remove the listener in your destroy method
columnGroup.removeEventListener('expandedChanged', listener);

Example - Header Group Cells

Angular Header Component

Header Component

Implementing a header component in Angular differs from the standard header component in the following ways:

  • Implement IHeaderAngularComp instead of IHeaderComp.
  • Use colDef.headerComponentFramework instead of colDef.headerComponent.

The interface IHeaderAngularComp is as follows:

interface IHeaderAngularComp {

    // equivalent of init in IHeaderComp
    // IHeaderCompParams is same as non Angular version
    agInit?(params: IHeaderCompParams): void;

    // no getGui() or destroy(), all handled by Angular
}

Header Group Component

Implementing a header group component in Angular differs from the standard header group component in the following ways:

  • Implement IHeaderGroupAngularComp instead of IHeaderGroupComp.
  • Use colDef.headerGroupComponentFramework instead of colDef.headerGroupComponent.

The interface IHeaderGroupAngularComp is as follows:

interface IHeaderGroupAngularComp {

    // equivalent of init in IHeaderGroupComp,
    // IHeaderGroupCompParams is same as non Angular version
    agInit?(params: IHeaderGroupCompParams): void;

    // no getGui() or destroy(), all handled by Angular
}

For a full working example of Header Components in Angular see Angular Example.

Aurelia Header Rendering

Aurelia Header Components use the standard Header Component - everything in the Header Components mechanism described above applies to usage in Aurelia.

React Header Rendering

Header Component

Implementing a header component in React differs from the standard header component in the following ways:

  • Implement IHeaderReactComp instead of IHeaderComp.
  • Use colDef.headerComponentFramework instead of colDef.headerComponent.

The interface IHeaderReactComp is empty. The params object (IHeaderCompParams) is passed as a constructor to your React component.

Header Group Component

Implementing a header group component in React differs from the standard header group component in the following ways:

  • Implement IHeaderGroupReactComp instead of IHeaderGroupComp.
  • Use colDef.headerGroupComponentFramework instead of colDef.headerGroupComponent.

The interface IHeaderReactComp is empty. The params object (IHeaderGroupCompParams) is passed as a constructor to your React component.

For a full working example of Header Components in React see React Example.

VueJS Header Rendering

Header Component

Implementing a header component in VueJS differs from the standard header component in it's much easier!

All you need to do is implement your VueJS component as normal, and provide it to the grid as documented above. Easy!

For a full working example of Header Components in VueJS see VueJS Example.


 

 

DEPRECATED - Header Templates

Header components (explained above) replace the need for header templates. If using header templates, you should refactor your code to use header components instead. Support for header templates will be dropped in ag-Grid v9.

You provide a header template to change the overall layout of a header cell. You can provide header templates in the following places:

  • colDef.headerCellTemplate: Can be a string of HTML, a DOM element, or a function that returns a string of HTML or a DOM element.
  • gridOptions.headerCellTemplate: Can be a string of HTML or a DOM element.
  • gridOptions.getHeaderCellTemplate: A function that returns a string of HTML or a DOM element.

The list above is confusing. What it's saying is you can specify the template in the colDef or the gridOptions. If colDef, one property is used for function and non-function variants. For gridOptions, the function and non-function variant is split. This was to keep the grid consistent with other properties and callbacks.

The parameters available to the function variant are as follows:

Value Description
column The column this header is for.
colDef The colDef this header is for.
context The grid context, as provided in the gridOptions.
api The grid API.

To get the template to work, you just need to ensure it has the following IDs:

  • agResizeBar - The resize bar.
  • agSortDesc - Icon for descending sort.
  • agSortAsc - Icon for ascending sort.
  • agNoSort - Icon for 'no sort'.
  • agFilter - Icon for filter.
  • agText - Container to put header title.
  • agHeaderCellLabel - Container when clicked the column will sort. Usually contains text and icons.
The grid will then attach the relevant logic to each element. If you do NOT include any of the above, the grid will still work but just not display what's missing, eg if missing agFilter, then when filtering, the grid will not try and show the filter icon.

The template you provide must contain exactly one root DOM element (eg a div) and should not contain any leading or trailing spaces before the start and end tags.

Grid API

There are two methods useful in the API for showing the column menu if you don't like the provided logic:

  • showColumnMenuAfterButtonClick(colKey, buttonElement): Shows a menu and positions relative to the provided button element - so it appears over the element giving the impression of the dropdown menu.
  • showColumnMenuAfterMouseClick(colKey, mouseEvent): Shows a menu and positions relative to the provided mouse event - use this for context menu, so the menu appears where you click the mouse.

It is unusual to use these methods, only use them if you can't get what you want from the normal behaviour.

Example Header Template

The example below shows defining header templates in different ways. The gridOptions.headerCellTemplate is provided with a string of HTML that is used for all the columns bar 'Athlete' and 'Country'. The 'Country' column definition is provided with a function that returns a DOM element (not a string) with some functionality attached to it. The functionality shows a message when you click on the additional 'Calendar' icon. The 'Athlete' column uses the two api methods above, one api method to show menu when you mouse click on the button, and the other api method to show menu when you right click on the athlete header.

For your reference, the default header template is as follows:

<div class="ag-header-cell">
        <div id="agResizeBar" class="ag-header-cell-resize"></div>
        <span id="agMenu" class="ag-header-icon ag-header-cell-menu-button"></span>
        <div id="agHeaderCellLabel" class="ag-header-cell-label">
            <span id="agSortAsc" class="ag-header-icon ag-sort-ascending-icon"></span>
            <span id="agSortDesc" class="ag-header-icon ag-sort-descending-icon"></span>
            <span id="agNoSort" class="ag-header-icon ag-sort-none-icon"></span>
            <span id="agFilter" class="ag-header-icon ag-filter-icon"></span>
            <span id="agText" class="ag-header-cell-text"></span>
        </div>
    </div>

Header Templates and Custom Icons

If you are providing your own header template, then any custom icons you specify in the gridOptions.icons will be ignored.

DEPRECATED - Header Rendering

Header components (explained above) replace the need for header rendering. If using header rendering, you should refactor your code to use header components instead. Support for header rendering will be dropped in ag-Grid v9.

Header rendering allows you to control what's inside the label in a header. The default header rendering can be replaced by providing a header renderer in the grid options (for all columns), or by specifying it for individual columns.

As with the cell renderers, the header renderer is a function that takes params specific to the column. The returned result can be a) a string of HTML or b) an HTML element object.

You have the option to use AngularJS 1.x for the custom renderer. If you require AngularJS 1.x for header rendering, then set the grid option value 'angularCompileHeaders' to true.

Header renderers receive the following parameters:

Value Description
value The value to render, ie the header name.
colDef The colDef this header is for.
context The grid context, as provided in the gridOptions.
$scope If Angular compiling the headers, contains the scope for this header column.
api The grid API.
eHeaderCell The outer header cell. Unlike cellRenderers, this is not virtual, it's the actual cell.

The example below shows using a header renderer to add angle brackets to the header name and to also add click handling to the header, so that the header changes color with a click.