Each Column has a Column Header providing a Header Name and typically functions such as Column Resize, Row Sorting and Row Filtering.
Header Name
When no header name is provided, the grid will derive the header name from the provided field
. The grid expects the field value to use Camel Case and will insert spaces between word breaks to build a readable header name.
columnDefs: [
// header name will be 'Athlete'
{ field: 'athlete' },
// header name will be 'First Name'
{ field: 'firstName' },
// header name will be 'foo'
{ headerName: 'foo', field: 'bar' }
],
Header Height
These properties can be used to change the different heights used in the headers.
The height in pixels for the row containing the column label header. If not specified, it uses the theme value of header-height . |
The height in pixels for the rows containing header column groups. If not specified, it uses headerHeight . |
The height in pixels for the row containing the floating filters. If not specified, it uses the theme value of header-height . |
The height in pixels for the row containing the columns when in pivot mode. If not specified, it uses headerHeight . |
The height in pixels for the row containing header column groups when in pivot mode. If not specified, it uses groupHeaderHeight . |
As you can see in the example below, if you change any of the header heights, this change will be reflected automatically. Note how if the value is cleared (set to undefined
), it might reuse other values. To see all the interactions check the properties descriptions at the top of the page.
Auto Header Height
The column header row can have its height set automatically based on the content of the header cells. This is most useful when used together with Custom Header Components or when using the wrapHeaderText
column property.
To enable this, set autoHeaderHeight=true
on the column definition you want to adjust the header height for. If more than one column has this property enabled, then the header row will be sized to the maximum of these columns' header cells so no content overflows.
The example below demonstrates using the autoHeaderHeight
property in conjunction with the wrapHeaderText
property, so that long column names are fully displayed.
- Note that the long column header names wrap onto another line.
- Try making a column smaller by dragging the resize handle on the column header, observe that the header will expand so the full header content is still visible.
When autoHeaderHeight=true
the Grid automatically disables Span Header Height, see: Suppress Span Header Height.
Selecting Components
By default the grid uses the provided Header Component. To use a Custom Header Component set headerComponent
on the Column Definition.
// 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}
}]
See Registering Components for an overview of registering components.
Provided Component
Most applications will use the Provided Header Component. It provides functionality such as Sorting, Filtering and Column Menu.
You can provide an HTML template to the Default Header Component for simple layout changes. 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="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.
Ref | Description |
---|---|
eMenu | The container where the column menu icon will appear to enable opening the column menu (in AG Grid Community, this is only used when columnMenu = 'legacy' ). |
eFilterButton | The container where the column filter icon will appear to enable opening the filter (not used when columnMenu = 'legacy' ). |
eLabel | The container where there is going to be an onClick mouse listener to trigger the sort. |
eText | The text displayed on the column. |
eFilter | The container with the icon that will appear if the user filters this column (only used when columnMenu = 'legacy' or suppressHeaderFilterButton = true ). |
eSortOrder | If multiple columns are sorted, this shows the index that represents the position of this column in the order. |
eSortAsc | If the column is sorted ascending, this shows the ascending icon. |
eSortDesc | If the column is sorted descending, this shows the descending icon. |
eSortNone | If no sort is applied, this shows the no sort icon. Note this icon by default is empty. |
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.
Templates are not meant to let you configure icons. If you are looking to change the icons, see Custom Icons for more information.
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 ...
}
Note that specifying your own templates is compatible with other configurations:
suppressHeaderFilterButton
is specified in: Athlete, Country, Date and Bronze columnssortable=false
is specified in: Age, Year, Sport, Silver and Total columns- Gold is the only column that doesn't have
sortable=false
orsuppressHeaderFilterButton
Inner Header Component
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
}
}
}
Custom Component
Column Headers by default use the Provided Header Component. The default can be overridden with Custom Header Component. This example shows a Custom Header Component. Note the following:
- 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.
The column the header is for. |
The name to display for the column. If the column is using a headerValueGetter, the displayName will take this into account.
|
Whether sorting is enabled for the column. Only put sort logic into your header if this is true.
|
Whether menu is enabled for the column. Only display a menu button in your header if this is true.
|
Whether filter button should be displayed in the header (for new column menu).
|
Whether filter icon should be displayed in the header (for legacy tabbed column menu).
|
Callback to request the grid to show the column menu. Pass in the html element of the column menu button to have the grid position the menu over the button.
|
Callback to request the grid to show the column menu. Similar to showColumnMenu , but will position the menu next to the provided mouseEvent .
|
Callback to request the grid to show the filter. Pass in the html element of the filter button to have the grid position the menu over the button.
|
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).
|
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)
|
The component to use for inside the header (replaces the text value and leaves the remainder of the Grid's original component). |
Additional params to customise to the innerHeaderComponent . |
The header the grid provides. The custom header component is a child of the grid provided header. The grid's header component is what contains the grid managed functionality such as resizing, keyboard navigation etc. This is provided should you want to make changes to this cell, eg add ARIA tags, or add keyboard event listener (as focus goes here when navigating to the header).
|
Sets a tooltip to the main element of this component.
value The value to be displayed by the tooltip
shouldDisplayTooltip A function returning a boolean that allows the tooltip to be displayed conditionally. This option does not work when enableBrowserTooltips={true} .
|
The grid api. |
Application context as set on gridOptions.context . |
Responsibilities
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
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:
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').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.getSort();
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
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);
});
Refreshing Headers
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
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
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 theCountry
header can be tabbed into. At the end of the cell elements, the tab focus moves to the nextAge
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
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.
Properties available on the IHeaderParams<TData = any, TContext = any>
interface.
Sets a tooltip to the main element of this component.
value The value to be displayed by the tooltip
shouldDisplayTooltip A function returning a boolean that allows the tooltip to be displayed conditionally. This option does not work when enableBrowserTooltips={true} .
|
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
See the Touch documentation for how the grid will handle touch support, particularly for Touch Events.
Tooltips
Tooltips can be added to the Column Header by using the headerTooltip
property of the ColDef
.
The example below demonstrates using the headerTooltip
property in the grid columns.
Text Orientation
By default, the text label for the header is display horizontally, i.e. as normal readable text. To display the text in another orientation you have to provide your own CSS to change the orientation and also provide the adequate header heights using the appropriate grid property.
The following example shows how you can provide a unique look and feel to the headers. Note that:
- The header heights have all been changed via grid options:
const gridOptions = {
// Group columns
groupHeaderHeight: 75,
// Label columns
headerHeight: 150,
// Floating filter
floatingFiltersHeight: 50,
// Pivoting, requires turning on pivot mode. Label columns
pivotHeaderHeight: 100,
// Pivoting, requires turning on pivot mode. Group columns
pivotGroupHeaderHeight: 50,
// other grid options ...
}
- The grouped column header
Athlete Details
has a specific style applied to it to make it bigger. Note that the style is slightly different depending if pivoting or not:
.ag-pivot-off .ag-header-group-cell {
font-size: 50px;
color: red;
}
.ag-pivot-on .ag-header-group-cell {
font-size: 25px;
color: green;
}
- The column labels have CSS applied to them so they are displayed vertically.
.ag-header-cell-label {
/* Necessary to allow for text to grow vertically */
height: 100%;
padding: 0 !important;
}
.ag-header-cell-label .ag-header-cell-text {
/* Force the width corresponding to how much width
we need once the text is laid out vertically */
width: 30px;
transform: rotate(90deg);
margin-top: 50px;
/* Since we are rotating a span */
display: inline-block;
}
- The floating filters are using a much bigger area and the font used is bigger and bolder.
.ag-floating-filter-body input {
height: 49px;
}
.ag-floating-filter-button {
margin-top: -49px;
}
.ag-floating-filter-button button {
height: 49px
}
.ag-floating-filter-body input {
font-size: 15px;
font-weight: bold;
}
- The styling of the column labels have also been tweaked depending if pivoting or not.
.ag-pivot-off .ag-header-cell-label {
color: #8a6d3b;
}
.ag-pivot-on .ag-header-cell-label {
color: #1b6d85;
font-weight: bold;
}