Skip to content

Column headers

Use default column headers (A, B, C), or set them to custom values provided by an array or a function.

Overview

Column headers are gray-colored rows used to label each column or group of columns. By default, these headers are populated with letters in alphabetical order.

To reflect the type or category of data in a particular column, give it a custom name and then display it in a column header. For example, instead of letters as labels such as A, B, C, ... name them Name, Symbol, Atomic Number, ....

Default headers

Setting the colHeaders option to true enables the default column headers as shown in the example below:

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const hotSettings = ref<GridSettings>({
data: [
['Hydrogen', 'H', 1, 1.008, 7, -434.4, -423.2],
['Helium', 'He', 2, 4.003, 9, -458.0, -452.1],
['Lithium', 'Li', 3, 6.94, 9, 356.9, 2447.6],
['Beryllium', 'Be', 4, 9.012, 11, 2348.6, 4478.8],
['Boron', 'B', 5, 10.81, 15, 3768.8, 7100.6],
],
colHeaders: true,
columns: [
{},
{},
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 3, maximumFractionDigits: 3, useGrouping: false } },
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
],
rowHeaders: true,
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example1">
<HotTable :settings="hotSettings" />
</div>
</template>

Header labels as an array

An array of labels can be used to set the colHeaders as shown in the example below:

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const hotSettings = ref<GridSettings>({
data: [
['Hydrogen', 'H', 1, 1.008, 7, -434.4, -423.2],
['Helium', 'He', 2, 4.003, 9, -458.0, -452.1],
['Lithium', 'Li', 3, 6.94, 9, 356.9, 2447.6],
['Beryllium', 'Be', 4, 9.012, 11, 2348.6, 4478.8],
['Boron', 'B', 5, 10.81, 15, 3768.8, 7100.6],
],
colHeaders: ['Name', 'Symbol', 'Atomic Number', 'Atomic Mass (u)', 'Known Isotopes', 'Melting Point (°F)', 'Boiling Point (°F)'],
columns: [
{},
{},
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 3, maximumFractionDigits: 3, useGrouping: false } },
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
],
rowHeaders: true,
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example2">
<HotTable :settings="hotSettings" />
</div>
</template>

Header labels as a function

The colHeaders can also be populated using a function as shown in the example below:

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const columnHeaders = ['Name', 'Symbol', 'Atomic Number', 'Atomic Mass (u)', 'Known Isotopes', 'Melting Point (°F)', 'Boiling Point (°F)'];
const hotSettings = ref<GridSettings>({
data: [
['Hydrogen', 'H', 1, 1.008, 7, -434.4, -423.2],
['Helium', 'He', 2, 4.003, 9, -458.0, -452.1],
['Lithium', 'Li', 3, 6.94, 9, 356.9, 2447.6],
['Beryllium', 'Be', 4, 9.012, 11, 2348.6, 4478.8],
['Boron', 'B', 5, 10.81, 15, 3768.8, 7100.6],
],
// Number each header with its column position, something a plain array can't do.
colHeaders: (index) => {
return `${index + 1}. ${columnHeaders[index]}`;
},
columns: [
{},
{},
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 3, maximumFractionDigits: 3, useGrouping: false } },
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
],
rowHeaders: true,
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example3">
<HotTable :settings="hotSettings" />
</div>
</template>

Header labels in the columns option

When you configure columns individually with the columns option, set a column’s header label with that column’s title option. If both are set, a column’s title takes precedence over the matching colHeaders entry.

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const hotSettings = ref<GridSettings>({
data: [
['Hydrogen', 'H', 1, 1.008, 7, -434.4, -423.2],
['Helium', 'He', 2, 4.003, 9, -458.0, -452.1],
['Lithium', 'Li', 3, 6.94, 9, 356.9, 2447.6],
['Beryllium', 'Be', 4, 9.012, 11, 2348.6, 4478.8],
['Boron', 'B', 5, 10.81, 15, 3768.8, 7100.6],
],
// Set each column header label with the `title` option inside `columns`.
columns: [
{ title: 'Name' },
{ title: 'Symbol' },
{ title: 'Atomic Number', type: 'numeric' },
{ title: 'Atomic Mass (u)', type: 'numeric', numericFormat: { minimumFractionDigits: 3, maximumFractionDigits: 3, useGrouping: false } },
{ title: 'Known Isotopes', type: 'numeric' },
{ title: 'Melting Point (°F)', type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
{ title: 'Boiling Point (°F)', type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
],
rowHeaders: true,
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example6">
<HotTable :settings="hotSettings" />
</div>
</template>

Customize column headers

You can align the text in the header label with the headerClassName option. Setting it to htLeft, htCenter, or htRight will align the header labels to the left, center, or right, respectively.

You can also set the alignment for a specific column by using the columns option.

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const hotSettings = ref<GridSettings>({
data: [
['Hydrogen', 'H', 1],
['Helium', 'He', 2],
['Lithium', 'Li', 3],
['Beryllium', 'Be', 4],
['Boron', 'B', 5],
],
colHeaders: ['Name', 'Symbol', 'Atomic Number'],
rowHeaders: true,
autoWrapRow: true,
autoWrapCol: true,
height: 'auto',
stretchH: 'all',
headerClassName: 'htCenter',
columns: [
{ headerClassName: 'htRight' },
{ headerClassName: 'htLeft' },
{ type: 'numeric' },
],
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example4">
<HotTable :settings="hotSettings" />
</div>
</template>

If you want to style the header labels, you can pass any number of class names, separated by a space, to the headerClassName option.

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const hotSettings = ref<GridSettings>({
data: [
['Hydrogen', 'H', 1, 1.008],
['Helium', 'He', 2, 4.003],
['Lithium', 'Li', 3, 6.94],
['Beryllium', 'Be', 4, 9.012],
['Boron', 'B', 5, 10.81],
],
colHeaders: ['Name', 'Symbol', 'Atomic Number', 'Atomic Mass (u)'],
rowHeaders: true,
autoWrapRow: true,
autoWrapCol: true,
height: 'auto',
stretchH: 'all',
headerClassName: 'htLeft',
columns: [
{ headerClassName: 'italic-text' },
{ headerClassName: 'bold-text italic-text' },
{ headerClassName: 'htRight bold-text italic-text', type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 3, maximumFractionDigits: 3, useGrouping: false } },
],
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example5">
<HotTable :settings="hotSettings" />
</div>
</template>
<style>
.bold-text {
font-weight: bold;
}
.italic-text {
font-style: italic;
}
</style>

Add a tooltip to a column header

To show a description when users hover over a column header, set the HTML title attribute of the header cell. Do this in the afterGetColHeader hook, which receives the header’s <th> element. The browser displays the attribute’s value as a native tooltip. Browsers show a title tooltip only on mouse hover, so keyboard users who focus a header (with navigableHeaders) and touch users never see it. Don’t put information that users need only in the tooltip.

The HTML title attribute is not the same as the title option, which sets the header label.

Handsontable DataGrid reuses header cells as users scroll, so a cell can still hold the title of a column that was rendered in it earlier. To avoid showing the wrong tooltip, set the attribute when a column has a description and remove it when it doesn’t, on every call of the hook.

Look up each description by the header’s label, not by the column argument. That argument is a visual column index, so a description keyed by it stops matching its column after users move columns. This assumes your header labels are unique.

The example below adds a tooltip to four of the seven headers.

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
// Descriptions keyed by header label, so each one stays with its column when users move columns.
const descriptions: Record<string, string> = {
'Atomic Number': 'Number of protons in the nucleus',
'Atomic Mass (u)': 'Average mass of an atom, in unified atomic mass units (u)',
'Melting Point (°F)': 'Temperature at which the element melts, in degrees Fahrenheit',
'Boiling Point (°F)': 'Temperature at which the element boils, in degrees Fahrenheit',
};
const hotSettings = ref<GridSettings>({
data: [
['Hydrogen', 'H', 1, 1.008, 7, -434.4, -423.2],
['Helium', 'He', 2, 4.003, 9, -458.0, -452.1],
['Lithium', 'Li', 3, 6.94, 9, 356.9, 2447.6],
['Beryllium', 'Be', 4, 9.012, 11, 2348.6, 4478.8],
['Boron', 'B', 5, 10.81, 15, 3768.8, 7100.6],
],
colHeaders: ['Name', 'Symbol', 'Atomic Number', 'Atomic Mass (u)', 'Known Isotopes', 'Melting Point (°F)', 'Boiling Point (°F)'],
columns: [
{},
{},
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 3, maximumFractionDigits: 3, useGrouping: false } },
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
],
// Handsontable reuses header cells, so set or remove the `title` attribute on every call.
afterGetColHeader(column, TH) {
const label = TH.querySelector('.colHeader')?.textContent ?? '';
const description = descriptions[label];
if (description) {
TH.title = description;
} else {
TH.removeAttribute('title');
}
},
rowHeaders: true,
manualColumnMove: true,
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example8">
<HotTable :settings="hotSettings" />
</div>
</template>

Column header height

When column labels are longer, header text can wrap and require more vertical space. To control the header size, set columnHeaderHeight.

You can set this option to one of the following:

  • A number - set the same height for every column header.
  • A string - set the same height, written as a pixel size: '50' or '50px'.
  • An array - set different heights for individual column header levels.

The height is a number of pixels. A string that states a pixel size works too, so a value coming from an attribute, a JSON config, or a framework template still applies. You can mix both forms inside the array. A value that states no pixel count, such as '50%' or '20em', is ignored - the header keeps its default height, and Handsontable reports the value once in the browser console.

A negative number is kept as it is, because numbers behave exactly as they did before this option read strings. A negative string is rejected, so a typo cannot collapse the header.

The height you set is the header’s border-box height: it includes the header’s own top and bottom borders. A column header carries a 1px border on each side, so columnHeaderHeight: 40 leaves a 38px content box for the label. Before Handsontable 19.0 the bottom border was dropped while the grid sat at the top of its scroll range and added back as soon as you scrolled, so the same setting gave a 39px content box unscrolled and 38px scrolled. The header now keeps that border at every scroll position, which makes the option’s result the same wherever the grid is scrolled to. If you had tuned the number against an unscrolled grid, add a pixel to keep the label area you had.

The example below uses longer labels together with columnHeaderHeight: 50.

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const hotSettings = ref<GridSettings>({
data: [
['Hydrogen', 'H', 1, 1.008, 7, -434.4, -423.2],
['Helium', 'He', 2, 4.003, 9, -458.0, -452.1],
['Lithium', 'Li', 3, 6.94, 9, 356.9, 2447.6],
['Beryllium', 'Be', 4, 9.012, 11, 2348.6, 4478.8],
['Boron', 'B', 5, 10.81, 15, 3768.8, 7100.6],
],
colHeaders: ['Name', 'Symbol', 'Atomic Number', 'Atomic Mass (u)', 'Known Isotopes', 'Melting Point (°F)', 'Boiling Point (°F)'],
columns: [
{},
{},
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 3, maximumFractionDigits: 3, useGrouping: false } },
{ type: 'numeric' },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
{ type: 'numeric', numericFormat: { minimumFractionDigits: 1, maximumFractionDigits: 1, useGrouping: false } },
],
rowHeaders: true,
// Wide enough that no label gets cut off by the header's ellipsis truncation.
colWidths: [90, 90, 120, 130, 120, 155, 155],
columnHeaderHeight: 50,
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example7">
<HotTable :settings="hotSettings" />
</div>
</template>

Rename headers in the grid

Let users rename column headers, row headers, or both, right in the grid. Enable the EditableHeaders plugin with the editableHeaders option. It is available since version 19.0.0.

  • Set editableHeaders to true to make column headers renamable.
  • Set it to an object to choose the axes: columnHeaders defaults to true, and rowHeaders defaults to false.

Row headers need rowHeaders to be on, because the plugin renames headers that the grid shows.

How users rename a header

Users can rename a header in three ways:

  • Double-click the header.
  • Focus the header with the keyboard and press F2 or Enter. To focus a header with the keyboard, set navigableHeaders to true.
  • Select Rename header in the context menu or the column menu (dropdownMenu).

An input opens over the header. Press Enter or move the focus away to save the new name. Press Esc to cancel. An emptied input cancels too, so a header always keeps a name, and so does a scroll that moves the header out of view. The new name shows as plain text, even when it looks like HTML, also in copied data. Each rename is one step in the undo and redo history.

The grid keeps the new names in the plugin. It doesn’t write them to colHeaders or rowHeaders. A renamed header follows its column or row when users move, sort, insert, or remove columns and rows. getColHeader(), getRowHeader(), copying with headers, and exporting all return the new name.

A name belongs to the position of a column or row in your data, not to the values in it. updateData() keeps the names on the same positions in the new data. loadData() drops every name.

The example below makes both column and row headers renamable. The log under the grid shows the last rename.

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const output = ref('Rename a header to see the change here.');
const hotSettings = ref<GridSettings>({
data: [
['Wireless mouse', 'Accessories', 24.9, 120],
['Mechanical keyboard', 'Accessories', 89, 45],
['27-inch monitor', 'Displays', 319.5, 18],
['USB-C dock', 'Accessories', 149, 32],
],
colHeaders: ['Product', 'Category', 'Price', 'In stock'],
rowHeaders: true,
navigableHeaders: true,
contextMenu: true,
editableHeaders: { columnHeaders: true, rowHeaders: true },
// Save the new names in your app here.
afterHeaderChange(axis, visualIndex, newValue, oldValue) {
output.value = `Renamed the ${axis} header at index ${visualIndex} from "${oldValue}" to "${newValue}".`;
},
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example9">
<HotTable :settings="hotSettings" />
<output class="console" id="output">{{ output }}</output>
</div>
</template>

Turn off renaming for one column

To keep a column’s header fixed, set editableHeaders to false in that column’s configuration:

editableHeaders: { columnHeaders: true, rowHeaders: true },
columns: [
{ editableHeaders: false }, // users can't rename this column's header
{},
{},
{},
],

Save the new names

Handsontable doesn’t store the new names outside the grid. To save them in your app, use the afterHeaderChange hook. It receives the axis ('column' or 'row'), the visual index, the new name, and the old name.

The index is visual, so it changes when users move or sort columns and rows. Save the name by the physical index, which stays with the column or row:

afterHeaderChange(axis, visualIndex, newValue, oldValue) {
const physicalIndex = axis === 'column' ? this.toPhysicalColumn(visualIndex) : this.toPhysicalRow(visualIndex);
saveHeaderName(axis, physicalIndex, newValue);
},

afterHeaderChange also runs for every header that an undo, a redo, or clearHeaders() changes, so your saved names stay in step. beforeHeaderChange runs only for a rename: it can’t stop an undo or a reset. An undo or a redo that also adds or removes rows or columns runs no afterHeaderChange for that axis, because the positions it would report are renumbered. Read the names again in the afterUndo and afterRedo hooks in that case.

To validate or reject a rename, return false from the beforeHeaderChange hook. The header then keeps its old name, and afterHeaderChange doesn’t run.

To read or change names from your code, use the EditableHeaders plugin methods, such as setHeader(), getHeader(), and clearHeaders():

const plugin = hot.getPlugin('editableHeaders');
plugin.setHeader('column', 0, 'Item');
plugin.getHeader('column', 0); // 'Item'

Limits

  • While nestedHeaders are on, users can’t rename column headers. Row headers stay renamable.
  • When columnSorting is on, a click on a column header sorts the column. On such a header, Enter and a double-click sort the column and don’t open the input. Press F2 or use the Rename header menu item instead.

Nested headers

More complex data structures can be displayed with multiple headers, each representing a different category of data. To learn more about nested headers, see the column groups page.

Related guides

Related blog articles

Configuration options

Core methods

Hooks

Plugins