JavaScript Data GridHeader 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. If you just want to make simple layout changes to the default header take a look at Header Templates.

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.

Simple Header Component

Below is an example of header component:

class CustomHeader {
    init(agParams) {
        this.agParams = agParams;
        this.eGui = document.createElement('div');
        this.eGui.innerHTML = `
            <div class="customHeaderMenuButton">
                <i class="fa ${this.agParams.menuIcon}"></i>
            </div>
            <div class="customHeaderLabel">${this.agParams.displayName}</div>
            <div class="customSortDownLabel inactive">
                <i class="fa fa-long-arrow-alt-down"></i>
            </div>
            <div class="customSortUpLabel inactive">
                <i class="fa fa-long-arrow-alt-up"></i>
            </div>
            <div class="customSortRemoveLabel inactive">
                <i class="fa fa-times"></i>
            </div>
        `;

        this.eMenuButton = this.eGui.querySelector(".customHeaderMenuButton");
        this.eSortDownButton = this.eGui.querySelector(".customSortDownLabel");
        this.eSortUpButton = this.eGui.querySelector(".customSortUpLabel");
        this.eSortRemoveButton = this.eGui.querySelector(".customSortRemoveLabel");

        if (this.agParams.enableMenu) {
            this.onMenuClickListener = this.onMenuClick.bind(this);
            this.eMenuButton.addEventListener('click', this.onMenuClickListener);
        } else {
            this.eGui.removeChild(this.eMenuButton);
        }

        if (this.agParams.enableSorting) {
            this.onSortAscRequestedListener = this.onSortRequested.bind(this, 'asc');
            this.eSortDownButton.addEventListener('click', this.onSortAscRequestedListener);
            this.onSortDescRequestedListener = this.onSortRequested.bind(this, 'desc');
            this.eSortUpButton.addEventListener('click', this.onSortDescRequestedListener);
            this.onRemoveSortListener = this.onSortRequested.bind(this, '');
            this.eSortRemoveButton.addEventListener('click', this.onRemoveSortListener);


            this.onSortChangedListener = this.onSortChanged.bind(this);
            this.agParams.column.addEventListener('sortChanged', this.onSortChangedListener);
            this.onSortChanged();
        } else {
            this.eGui.removeChild(this.eSortDownButton);
            this.eGui.removeChild(this.eSortUpButton);
            this.eGui.removeChild(this.eSortRemoveButton);
        }
    }

    onSortChanged() {
        const deactivate = toDeactivateItems => {
            toDeactivateItems.forEach(toDeactivate => {
                toDeactivate.className = toDeactivate.className.split(' ')[0]
            });
        }

        const activate = toActivate => {
            toActivate.className = toActivate.className + " active";
        }

        if (this.agParams.column.isSortAscending()) {
            deactivate([this.eSortUpButton, this.eSortRemoveButton]);
            activate(this.eSortDownButton)
        } else if (this.agParams.column.isSortDescending()) {
            deactivate([this.eSortDownButton, this.eSortRemoveButton]);
            activate(this.eSortUpButton)
        } else {
            deactivate([this.eSortUpButton, this.eSortDownButton]);
            activate(this.eSortRemoveButton)
        }
    }

    getGui() {
        return this.eGui;
    }

    onMenuClick() {
        this.agParams.showColumnMenu(this.eMenuButton);
    }

    onSortRequested(order, event) {
        this.agParams.setSort(order, event.shiftKey);
    }

    destroy() {
        if (this.onMenuClickListener) {
            this.eMenuButton.removeEventListener('click', this.onMenuClickListener)
        }
        this.eSortDownButton.removeEventListener('click', this.onSortRequestedListener);
        this.eSortUpButton.removeEventListener('click', this.onSortRequestedListener);
        this.eSortRemoveButton.removeEventListener('click', this.onSortRequestedListener);
        this.agParams.column.removeEventListener('sortChanged', this.onSortChangedListener);
    }
}

Example: Custom 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 sortable=false, so the header component doesn't add sorting logic.
• The header component uses additional parameters to allowing configuring the menu icon.

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: IHeaderParams): void;
    
    // Return the DOM element of your component, this is what the grid puts into the DOM
    // Can get called more than once
    getGui(): HTMLElement;
    
    // Gets called when a new Column Definition has been set for this header.
    // If you handle the refresh of your header return true otherwise return false and the grid will re-create your header from scratch.
    refresh(params: IHeaderParams): boolean;
    
    // Gets called once by grid when the component is being removed; if your component needs to do any cleanup, do it here
    destroy?(): void;
}

Custom Header Parameters

The init(params) method takes a params object with the items listed below. If custom params are provided via the colDef.headerComponentParams property, these will be additionally added to the params object, overriding items of the same name if a name clash exists.

Specifying Header Components

You specify the Header Component, as well Header Group Components, in the column definition (or you can set in the default column definition to impact all columns).

If you're not familiar with registering Custom Components for use within the Grid please refer the the Registering Components documentation first.

In the definitions below we're registering both a column headerComponent (for the Age column), as well as a headerGroupComponent (for the Medals grouped column).

// a list of column definitions
const colDefs = [{

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

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

    // you can also specify header components for groups
    {
        headerName: "Medals",
        // custom header component component specified in comps
        headerGroupComponent: MyHeaderGroupComponent,
        children: [
            {headerName: "Gold", field: "gold"},
            {headerName: "Silver", field: "silver"},
            {headerName: "Gold", field: "bronze"}
        ]
    }
}]

For more information on declaring columns please refer to the Column Definition Docs, and for grouped columns please refer to the Grouped Column Definition Docs.

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"></div>

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

<!-- 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.

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

Menu

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);
 });

Refresh

The refresh(params) method gets called when the application updates the Column Definitions. For example the application could set a headerName attribute and then set the Column Definitions again. In this instance, the Header Component should update the displayed header name.

It is the responsibility of the Header Component to inspect the Column Definition for relevant changes and updated if needed. If the refresh was successful then true should be returned. If the refresh was not successful then false should be returned. If false is returned, then the grid will destroy and recreate the component. This pattern is consistent with the refresh method of Cell Renderers.

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
    }
}

Header Group Components

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.

interface IHeaderGroupComp {
    // optional method, gets called once with params
    init?(params: IHeaderGroupParams): void;

    // can be called more than 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(params) are as follows:

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.

const showExpandableIcons = params.columnGroup.isExpandable()

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

const groupIsOpen = params.columnGroup.isExpanded();

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

// this code toggles the expanded state
const oldValue = params.columnGroup.isExpanded();
const 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
const columnGroup = params.columnGroup.getProvidedColumnGroup();
// create listener
const listener = () => { 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

Custom Header Keyboard Navigation

When using custom header renderers, the custom header renderer is responsible for implementing support for keyboard navigation among its focusable elements. This is why by default, focusing a grid header with a custom header renderer will focus the entire cell instead of any of the elements inside the custom header renderer.

Adding support for keyboard navigation and focus requires a custom suppressHeaderKeyboardEvent function in grid options. See Suppress Keyboard Events.

An example of this is shown below, enabling keyboard navigation through the custom header elements when pressing Tab and Shift+Tab:

• Click on the top left Athlete header, press the Tab key and notice that the button, textbox and link in the Country header can be tabbed into. At the end of the cell elements, the tab focus moves to the next Age header cell
• Use Shift+Tab to navigate in the reverse direction

The suppressHeaderKeyboardEvent callback is used to capture tab events and determine if the user is tabbing forward or backwards. It also suppresses the default behaviour of moving to the next cell if tabbing within the child elements.

If the focus is at the beginning or the end of the cell children and moving out of the cell, the keyboard event is not suppressed, so focus can move between the children elements. Also, when moving backwards, the focus needs to be manually set while preventing the default behaviour of the keyboard press event.