---
title: "Column Headers"
framework: javascript
version: "36.1.0"
---

# Column Headers

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 camelCase and will convert it to Title Case (e.g. `firstName` becomes `First Name`). Alternatively, you can provide your own header name using the `headerName` property of the `ColDef`.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `headerName` | `string` |  |  | The name to render in the column header. If not specified and field is specified, the field name will be used as the header name. |

```js
const gridOptions = {
    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' }
    ],

    // other grid options ...
}
```

## Header Value Getters

Use `headerValueGetter` instead of `colDef.headerName` to provide column header names dynamically.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `headerValueGetter` | `string \| HeaderValueGetterFunc` |  |  | Function or [expression](https://www.ag-grid.com/javascript-data-grid/cell-expressions/#column-definition-expressions). Gets the value for display in the header. |

The parameters for `headerValueGetter` differ from a [Cell Value Getter](https://www.ag-grid.com/javascript-data-grid/value-getters/) as follows:

- Only one of column or columnGroup will be present, depending on whether it's a column or a column group.
- Parameter `location` allows you to have different column names depending on where the column is appearing, eg you might want to have a different name when the column is in the column drop zone or the columns tool panel.

See the [Column Tool Panel Example](https://www.ag-grid.com/javascript-data-grid/tool-panel-columns/#columns-tool-panel-example) for an example of `headerValueGetter` used in different locations, where you can change the header name depending on where the name appears.

## Editable Header Name  (Enterprise)

Set `headerNameEditable: true` on a `ColDef` (or a `ColGroupDef`) to let users rename that column or column group header from the UI. This is an AG Grid Enterprise feature.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `headerNameEditable` | `boolean` |  | `false` | Set to `true` to allow the user to edit this column's (or column group's) header name from the UI. The edited value is persisted as part of grid state. Module: [`ColumnHeaderEditModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |

Editable columns can be renamed via:

- The **Edit Column Name** item in the [Column Menu](https://www.ag-grid.com/javascript-data-grid/column-menu/).
- Right-clicking the column in the [Columns Tool Panel](https://www.ag-grid.com/javascript-data-grid/tool-panel-columns/) and choosing **Edit Column Name**.

Editable column groups can be renamed via the **Edit Column Name** item in the group header right-click menu or the Columns Tool Panel context menu.

The **Edit Column Name** item is never offered for [calculated columns](https://www.ag-grid.com/javascript-data-grid/calculated-columns/), even when `headerNameEditable` is set; rename a calculated column from its **Edit Calculated Column** dialog instead.

Committing an empty value sets an empty header name; the header reverts to its Column Definition default only when the edit is cleared programmatically, such as `resetColumnState()`. Edited column names are persisted as part of [Column State](https://www.ag-grid.com/javascript-data-grid/column-state/) and [Grid State](https://www.ag-grid.com/javascript-data-grid/grid-state/); edited group names are persisted as part of Grid State. Both survive save and restore.

> **Note**
>
> An edited name takes priority over any `headerValueGetter` on the column. Once the user has provided a custom header name, the `headerValueGetter` is no longer called for that column.

### Edit Modes

Configure the editor with the `columnHeaderEdit` grid option.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `columnHeaderEdit` | `ColumnHeaderEditOptions` |  |  | Configures editing of column and column group header names via the UI. Requires `headerNameEditable` on the relevant Column or Column Group Definitions. Module: [`ColumnHeaderEditModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |

Its `applyMode` controls when edits are applied:

- `'live'` (default): each change is applied to the header immediately as the user types. Pressing `Escape` or closing the editor keeps the change.
- `'deferred'`: the editor shows **Apply** and **Cancel** buttons and the header is only updated when the edit is committed with **Apply** or `Enter`. **Cancel**, `Escape`, or closing the editor discards the edit.

While a header is being edited it is highlighted. Set `columnHeaderEdit: { suppressColumnHighlighting: true }` to turn the highlight off.

The example below has editable columns and column groups. Toggle **Deferred edit mode** to switch between live and deferred editing. Rename a header, then use **Save State** and **Restore State** to confirm edited names are persisted as part of Grid State, or **Reset State** to revert to the Column Definition defaults.

#### Editable Header Name

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  ColumnApiModule,
  GridApi,
  GridOptions,
  GridState,
  GridStateModule,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnHeaderEditModule,
  ColumnMenuModule,
  ColumnsToolPanelModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

declare let window: any;

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  ClientSideRowModelModule,
  ColumnApiModule,
  GridStateModule,
  ColumnHeaderEditModule,
  ColumnMenuModule,
  ColumnsToolPanelModule,
]);

const columnDefs: (ColDef | ColGroupDef)[] = [
  {
    groupId: "athleteDetails",
    headerName: "Athlete Details",
    headerNameEditable: true,
    children: [
      { field: "athlete", headerNameEditable: true },
      { field: "age", headerNameEditable: true },
      { field: "country", headerNameEditable: true },
    ],
  },
  { field: "sport" },
  {
    groupId: "medals",
    headerName: "Medals",
    headerNameEditable: true,
    children: [{ field: "gold" }, { field: "silver" }, { field: "bronze" }],
  },
];

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: columnDefs,
  defaultColDef: {
    width: 170,
  },
  sideBar: "columns",
  columnHeaderEdit: {
    applyMode: "live",
  },
};

function onModeChange() {
  const deferred =
    document.querySelector<HTMLInputElement>("#deferredMode")?.checked;
  gridApi!.setGridOption("columnHeaderEdit", {
    applyMode: deferred ? "deferred" : "live",
  });
}

function saveState() {
  window.gridState = gridApi!.getState();
  console.log("grid state saved");
}

function restoreState() {
  if (!window.gridState) {
    console.log("no grid state to restore, you must save state first");
    return;
  }
  gridApi!.setState(window.gridState as GridState);
  console.log("grid state restored");
}

function resetState() {
  gridApi!.resetColumnState();
  console.log("column state reset");
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).onModeChange = onModeChange;
  (<any>window).saveState = saveState;
  (<any>window).restoreState = restoreState;
  (<any>window).resetState = resetState;
}
```

[Live example: Editable Header Name](https://www.ag-grid.com/examples/column-headers/editable-header-name/typescript)

## Tooltips

Tooltips can be added to the Column Header by using either the `headerTooltipValueGetter`, or `headerTooltip` property of the `ColDef`.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `headerTooltipValueGetter` | `HeaderTooltipValueGetterFunc` |  |  | Callback that should return the string to use for a tooltip. Module: [`TooltipModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |
| `headerTooltip` | `string` |  |  | Tooltip for the column header, `headerTooltipValueGetter` takes precedence if set. When the column is grouped with `groupDisplayType: 'multipleColumns'`, the generated group column header inherits this value. Module: [`TooltipModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |

The example below demonstrates using both `headerTooltipValueGetter` and `headerTooltip` properties to set tooltips in the grid columns.

#### Header Tooltip

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  TooltipModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { IOlympicData } from "./interfaces";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([TooltipModule, ClientSideRowModelModule]);

const columnDefs: ColDef[] = [
  { field: "athlete", headerTooltip: "The athlete's name" },
  { field: "age", headerTooltip: "The athlete's age" },
  { field: "date", headerTooltip: "The date of the Olympics" },
  { field: "sport", headerTooltip: "The sport the medal was for" },
  {
    field: "gold",
    headerTooltipValueGetter: (p) => `How many ${p.colDef.field} medals`,
  },
  {
    field: "silver",
    headerTooltipValueGetter: (p) => `How many ${p.colDef.field} medals`,
  },
  {
    field: "bronze",
    headerTooltipValueGetter: (p) => `How many ${p.colDef.field} medals`,
  },
  { field: "total", headerTooltip: "The total number of medals" },
];

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: columnDefs,
  defaultColDef: {
    width: 150,
  },
  tooltipShowDelay: 500,
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));
```

[Live example: Header Tooltip](https://www.ag-grid.com/examples/column-headers/header-tooltip/typescript)

## Styling & Height

Column Headers can be styled using CSS classes and inline styles via `headerClass` and `headerStyle` properties. Header heights can also be configured and set to adjust automatically based on content.

See [Styling & Height](https://www.ag-grid.com/javascript-data-grid/column-headers-styling/) for full documentation on:

- [Header Style](https://www.ag-grid.com/javascript-data-grid/column-headers-styling/#header-style) and [Header Class](https://www.ag-grid.com/javascript-data-grid/column-headers-styling/#header-class)
- [Header Height](https://www.ag-grid.com/javascript-data-grid/column-headers-styling/#header-height)
- [Auto Header Height](https://www.ag-grid.com/javascript-data-grid/column-headers-styling/#auto-header-height)
- [Text Orientation](https://www.ag-grid.com/javascript-data-grid/column-headers-styling/#text-orientation)

## Custom Header Components

The grid provides a default Header Component with sorting, filtering and menu functionality. You can customise this using templates, inner header components, or create fully custom header components.

See [Custom Header Components](https://www.ag-grid.com/javascript-data-grid/column-headers-components/) for full documentation on:

- [Custom Template](https://www.ag-grid.com/javascript-data-grid/column-headers-components/#custom-template)
- [Inner Header Component](https://www.ag-grid.com/javascript-data-grid/column-headers-components/#inner-header-component)
- [Custom Component](https://www.ag-grid.com/javascript-data-grid/column-headers-components/#custom-component)