JavaScript Data GridColumn Headers - Custom Components

The grid provides a default Header Component with sorting, filtering and menu functionality. There are three approaches to customising Column Headers:

• Custom Template - Provide an HTML template to the default Header Component for simple layout changes while retaining built-in functionality.
• Inner Header Component - Replace just the header name display with a custom component while keeping sorting, filtering and menu functionality.
• Custom Component - Create a fully custom Header Component with complete control over rendering and behaviour.

Custom Template Copy Link

Provide an HTML template to the Provided Header Component for simple layout changes while retaining built-in sorting, filtering and menu functionality.

Set the template using colDef.headerComponentParams. Set on the defaultColDef grid option to set for all Columns.

const gridOptions = {
    defaultColDef: {
        width: 100,
        headerComponentParams: {
            template:
                `<div class="ag-cell-label-container" role="presentation">
                  <span data-ref="eMenu" class="ag-header-icon ag-header-cell-menu-button"></span>
                  <span data-ref="eFilterButton" class="ag-header-icon ag-header-cell-filter-button"></span>
                  <div data-ref="eLabel" class="ag-header-cell-label" role="presentation">
                    <span data-ref="eSortOrder" class="ag-header-icon ag-sort-order"></span>
                    <span data-ref="eSortAsc" class="ag-header-icon ag-sort-ascending-icon"></span>
                    <span data-ref="eSortDesc" class="ag-header-icon ag-sort-descending-icon"></span>
                    <span data-ref="eSortNone" class="ag-header-icon ag-sort-none-icon"></span>
                    ** <span data-ref="eText" class="ag-header-cell-text" role="columnheader"></span>
                    <span data-ref="eFilter" class="ag-header-icon ag-filter-icon"></span>
                  </div>
                </div>`
        }
    },

    // other grid options ...
}

The example below demonstrates a custom template. Note that specifying your own templates is compatible with other configurations:

• suppressHeaderFilterButton is specified in: Athlete, Country, Date and Bronze columns
• sortable=false is specified in: Age, Year, Sport, Silver and Total columns
• Gold is the only column that doesn't have sortable=false or suppressHeaderFilterButton

Default Template Copy Link

This is the default template used in AG Grid:

<div class="ag-cell-label-container" role="presentation">
    <span data-ref="eMenu" class="ag-header-icon ag-header-cell-menu-button" aria-hidden="true"></span>
    <span data-ref="eFilterButton" class="ag-header-icon ag-header-cell-filter-button" aria-hidden="true"></span>
    <div data-ref="eLabel" class="ag-header-cell-label" role="presentation">
        <span data-ref="eText" class="ag-header-cell-text"></span>
        <span data-ref="eFilter" class="ag-header-icon ag-header-label-icon ag-filter-icon" aria-hidden="true"></span>
        <span data-ref="eSortOrder" class="ag-header-icon ag-header-label-icon ag-sort-order" aria-hidden="true"></span>
        <span data-ref="eSortAsc" class="ag-header-icon ag-header-label-icon ag-sort-ascending-icon" aria-hidden="true"></span>
        <span data-ref="eSortDesc" class="ag-header-icon ag-header-label-icon ag-sort-descending-icon" aria-hidden="true"></span>
        <span data-ref="eSortAbsoluteAsc" class="ag-header-icon ag-header-label-icon ag-sort-absolute-ascending-icon ag-hidden"></span>
        <span data-ref="eSortAbsoluteDesc" class="ag-header-icon ag-header-label-icon ag-sort-absolute-descending-icon ag-hidden"></span>
        <span data-ref="eSortNone" class="ag-header-icon ag-header-label-icon ag-sort-none-icon" aria-hidden="true"></span>
    </div>
</div>

When you provide your own template, everything should work as expected as long as you re-use the same data-ref attribute names.

The data-ref parameters are used by the grid to identify elements to add functionality to. If you leave an element out of your template, the functionality will not be added. For example if you do not specify eLabel then the column will not react to click events for sorting.

Inner Header Component Copy Link

When using the Header Component, the agColumnHeader component will display the header name, adjacent to any configured menu, filter, and checkbox.

This text value can be overridden with a Custom Component by setting the innerHeaderComponent and innerHeaderComponentParams properties on the headerComponentParams property. This is useful when you only need to implement a Component to customise the Column Name without having to reimplement the whole header functionality (sorting, filter, menu, etc...).

colDef = {
    ...
    headerComponentParams : {
        innerHeaderComponent: MyInnerHeaderComponent,
        innerHeaderComponentParams: {
            currencySymbol: '£' // the pound symbol will be placed into params
        }
    }
}

Implement this interface to provide a custom inner header component.

IInnerHeaderComponent Copy Link

interface IInnerHeaderComponent<TData = any, TContext = any, TParams extends Readonly<IHeaderParams<TData, TContext>> = IHeaderParams<TData, TContext>> {
  // Return the DOM element of your component, this is what the grid puts into the DOM 
  getGui(): HTMLElement;

  // Get the header to refresh. Gets called whenever Column Defs are updated. 
  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;

  // The init(params) method is called on the component once. 
  init?(params: TParams): AgPromise<void>  |  void;

}

IHeaderParams Copy Link

Custom Component Copy Link

To use a fully customised Header Component, set headerComponent on the Column Definition to the custom component. See Registering Components for an overview.

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

    // no Header Comp specified, uses the Provided Header Comp
    {headerName: "Athlete", field: "athlete"},
    {headerName: "Sport", field: "sport"},

    // uses Custom Header Comp
    {headerName: "Age", field: "age", headerComponent: MyHeaderComponent}
}]

• Column moving and resizing works without custom logic.
• suppressHeaderFilterButton=true is used to suppress the filter menu.
• sortable=false is used to suppress sorting.
• The menu icon is configurable.

The interface for a custom header component is:

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

The init(params) method takes a params object with the items listed below.

Responsibilities Copy Link

The grid provides the following features that should not be implemented by Custom Header Components:

• Resizing: When enabled, the grid will put an invisible widget to be grabbed by the mouse for resizing.
• Header Checkbox Selection: When enabled, the grid displays a checkbox for 'select all' in the header.
• Column Moving The grid will react to Column Dragging to reorder columns.

The Custom Header Component is 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 Copy Link

How you interact with the user for sorting (e.g. listening 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): Call this method to progress the sort on the column to the next stage. This uses the grid logic to determine the next sort stage (eg 'descending' normally follows 'ascending').
2. params.setSort(direction, multiSort): If you don't want to use the grid's logic for working out the next sort state, use this to set the sort to a specific 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 changed (e.g. when to update your icons), you should listen for the sortChanged event on the column.

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

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

    // then do what you need, e.g. 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 Copy Link

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 Copy Link

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

Refreshing Headers Copy Link

If you are creating your own Header Components then you will need to be aware of how Header Components are refreshed.

All Header Components that still exist after the new Column Definitions are applied (in other words, the Column still exists after the update, it was not removed) will have its refresh method called.

It is the responsibility of the Header Component to inspect the Column Definition for relevant changes and update itself 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.

The example below demonstrates refreshing of the headers. Note the following:

• Each column is configured to use a custom Header Component.
• The Header Component logs to the console when its lifecycle methods/functions are called.
• Toggling between 'Upper Header Names' and 'Lower Header Names' causes the Header Component to refresh.
• Toggling between 'Filter On' and 'Filter Off' causes the Header Component to refresh. The Header Component returns false which results in the component getting destroyed and recreated.
• Toggling between 'Resize On' and 'Resize Off' causes the Header Component to refresh. However there is no change to the Header Component as it doesn't depend on resize - the resize UI is provided by the grid.

Custom Props Copy Link

On top of the props provided by the grid, you can also provide your own parameters. This is useful if you want to allow configuring the header component. For example, you might have a header component for formatting currency which also requires the currency symbol to be provided.

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

Keyboard Navigation Copy Link

When using Custom Header Components, the Custom Header Component 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 Component will focus the entire cell instead of any of the elements inside.

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.

Dynamic Tooltips Copy Link

When using Custom Header Components it might be necessary to have a better control of how Tooltips are added instead of simply using the headerTooltip config. For this purpose, we provide the setTooltip method.

The example below demonstrates using the Dynamic Tooltips with a Custom Header Component.

• Note that only Column Headers where the text is not fully displayed will show tooltips.

Touch Support Copy Link

See the Touch documentation for how the grid will handle touch support, particularly for Touch Events.

Next Up Copy Link

Continue to the next section: Column Groups.