---
title: "Column Headers"
framework: react
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. |

```jsx
const [columnDefs, setColumnDefs] = useState([
    // header name will be 'Athlete'
    { field: 'athlete' },
    // header name will be 'First Name'
    { field: 'firstName' },
    // header name will be 'foo'
    { headerName: 'foo', field: 'bar' }
]);

<AgGridReact columnDefs={columnDefs} />
```

## 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/react-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/react-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/react-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/react-data-grid/modules/). |

Editable columns can be renamed via:

- The **Edit Column Name** item in the [Column Menu](https://www.ag-grid.com/react-data-grid/column-menu/).
- Right-clicking the column in the [Columns Tool Panel](https://www.ag-grid.com/react-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/react-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/react-data-grid/column-state/) and [Grid State](https://www.ag-grid.com/react-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/react-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

```tsx
("use client");

import React, {
  useCallback,
  useMemo,
  useRef,
  useState,
  StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgGridReact, AgGridProvider } from "ag-grid-react";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  ColumnApiModule,
  ColumnHeaderEditOptions,
  GridApi,
  GridOptions,
  GridState,
  GridStateModule,
  ModuleRegistry,
  SideBarDef,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnHeaderEditModule,
  ColumnMenuModule,
  ColumnsToolPanelModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";
import { useFetchJson } from "./useFetchJson";

if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

const modules = [
  ClientSideRowModelModule,
  ColumnApiModule,
  GridStateModule,
  ColumnHeaderEditModule,
  ColumnMenuModule,
  ColumnsToolPanelModule,
];

declare let window: any;

const GridExample = () => {
  const gridRef = useRef<AgGridReact<IOlympicData>>(null);
  const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
  const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);

  const [columnDefs, setColumnDefs] = useState<(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" }],
    },
  ]);
  const defaultColDef = useMemo<ColDef>(() => {
    return {
      width: 170,
    };
  }, []);
  const columnHeaderEdit = useMemo<ColumnHeaderEditOptions>(() => {
    return {
      applyMode: "live",
    };
  }, []);

  const { data, loading } = useFetchJson<IOlympicData>(
    "https://www.ag-grid.com/example-assets/olympic-winners.json",
  );

  const onModeChange = useCallback(() => {
    const deferred =
      document.querySelector<HTMLInputElement>("#deferredMode")?.checked;
    gridRef.current!.api.setGridOption("columnHeaderEdit", {
      applyMode: deferred ? "deferred" : "live",
    });
  }, []);

  const saveState = useCallback(() => {
    window.gridState = gridRef.current!.api.getState();
    console.log("grid state saved");
  }, []);

  const restoreState = useCallback(() => {
    if (!window.gridState) {
      console.log("no grid state to restore, you must save state first");
      return;
    }
    gridRef.current!.api.setState(window.gridState as GridState);
    console.log("grid state restored");
  }, [window]);

  const resetState = useCallback(() => {
    gridRef.current!.api.resetColumnState();
    console.log("column state reset");
  }, []);

  return (
    <AgGridProvider modules={modules}>
      <div style={containerStyle}>
        <div
          style={{ display: "flex", flexDirection: "column", height: "100%" }}
        >
          <div style={{ marginBottom: "1rem" }}>
            <label style={{ marginRight: "1rem" }}>
              <input
                type="checkbox"
                id="deferredMode"
                onChange={onModeChange}
              />
              Deferred edit mode (Apply / Cancel)
            </label>
            <button onClick={saveState}>Save State</button>
            <button onClick={restoreState}>Restore State</button>
            <button onClick={resetState}>Reset State</button>
          </div>

          <div style={gridStyle}>
            <AgGridReact<IOlympicData>
              ref={gridRef}
              rowData={data}
              loading={loading}
              columnDefs={columnDefs}
              defaultColDef={defaultColDef}
              sideBar={"columns"}
              columnHeaderEdit={columnHeaderEdit}
            />
          </div>
        </div>
      </div>
    </AgGridProvider>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(
  <StrictMode>
    <GridExample />
  </StrictMode>,
);
```

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

## 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/react-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/react-data-grid/modules/). |

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

#### Header Tooltip

```tsx
"use client";

import React, {
  useCallback,
  useMemo,
  useRef,
  useState,
  StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgGridReact, AgGridProvider } from "ag-grid-react";
import {
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  TooltipModule,
  enableDevValidations,
} from "ag-grid-community";
import { IOlympicData } from "./interfaces";
import { useFetchJson } from "./useFetchJson";

if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

const modules = [TooltipModule, ClientSideRowModelModule];

const GridExample = () => {
  const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
  const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);

  const [columnDefs, setColumnDefs] = useState<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" },
  ]);
  const defaultColDef = useMemo<ColDef>(() => {
    return {
      width: 150,
    };
  }, []);

  const { data, loading } = useFetchJson<IOlympicData>(
    "https://www.ag-grid.com/example-assets/olympic-winners.json",
  );

  return (
    <AgGridProvider modules={modules}>
      <div style={containerStyle}>
        <div style={gridStyle}>
          <AgGridReact<IOlympicData>
            rowData={data}
            loading={loading}
            columnDefs={columnDefs}
            defaultColDef={defaultColDef}
            tooltipShowDelay={500}
          />
        </div>
      </div>
    </AgGridProvider>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(
  <StrictMode>
    <GridExample />
  </StrictMode>,
);
```

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

## 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/react-data-grid/column-headers-styling/) for full documentation on:

- [Header Style](https://www.ag-grid.com/react-data-grid/column-headers-styling/#header-style) and [Header Class](https://www.ag-grid.com/react-data-grid/column-headers-styling/#header-class)
- [Header Height](https://www.ag-grid.com/react-data-grid/column-headers-styling/#header-height)
- [Auto Header Height](https://www.ag-grid.com/react-data-grid/column-headers-styling/#auto-header-height)
- [Text Orientation](https://www.ag-grid.com/react-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/react-data-grid/column-headers-components/) for full documentation on:

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