Export to Excel

Export your grid data to an Excel (.xlsx) file, preserving cell types, styling, formulas, merged cells, and more.

Overview

The ExportFile plugin supports XLSX export via ExcelJS, which you must install as a peer dependency. XLSX export goes beyond CSV in several ways:

Cell types (numeric, date, time, checkbox, dropdown) are written as native Excel types with matching number formats.
Cell styling is read from the rendered DOM - font properties, background colors, alignment, and borders are all transferred to the workbook.
Column headers and nested headers, merged cells, frozen panes, hidden rows, and hidden columns are preserved.
HyperFormula and ColumnSummary destination cells can be exported as live Excel formulas.
Multiple Handsontable instances can be exported into separate sheets of one workbook.

Prerequisites

Install ExcelJS. The supported version range is ^4.4.0 (ExcelJS 4.x, version 4.4.0 or later).

1
npm install exceljs

Pass the ExcelJS constructor as engines: { xlsx: ExcelJS } in the exportFile plugin configuration:

1
import ExcelJS from 'exceljs';
2

3
const hot = new Handsontable(container, {
4
  exportFile: { engines: { xlsx: ExcelJS } },
5
});

Example

The table below is a Q1 sales report that demonstrates the main XLSX export features: nested column headers, numeric and checkbox cell types, a column summary total, merged cells, a custom border, a frozen first column, and a cell comment on Alice’s row.

Click Export XLSX to download the file and open it in Microsoft Excel or any compatible spreadsheet application.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import ExcelJS from 'exceljs';
4

5
registerAllModules();
6

7
const container = document.querySelector('#example1');
8
const hot = new Handsontable(container, {
9
  data: [
10
    ['Alice Martin', 'North', 142000, true, 'Exceeded Q1 target by 18%.'],
11
    ['Bob Chen', 'East', 98500, true, 'Strong pipeline for Q2.'],
12
    ['Carol Davies', 'South', 76200, false, 'Needs coaching on closing.'],
13
    ['David Kim', 'West', 115300, true, 'Cross-sell opportunity.'],
14
    ['Eva Rossi', 'North', 54800, false, 'Sick leave impacted March.'],
15
    ['TOTALS', '', null, '', ''],
16
  ],
17
  nestedHeaders: [
18
    [
19
      { label: 'Sales Representative', colspan: 2, headerClassName: 'htCenter' },
20
      { label: 'Results', colspan: 2, headerClassName: 'htCenter' },
21
      { label: 'Notes', colspan: 1, headerClassName: 'htLeft' },
22
    ],
23
    ['Name', 'Region', 'Revenue ($)', 'Hit Target?', 'Notes'],
24
  ],
25
  columns: [
26
    { type: 'text' },
27
    { type: 'dropdown', source: ['North', 'South', 'East', 'West'] },
28
    {
29
      type: 'numeric',
30
      locale: 'en-US',
31
      numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
32
    },
33
    { type: 'checkbox' },
34
    { type: 'text' },
35
  ],
36
  columnSummary: [
37
    {
38
      sourceColumn: 2,
39
      destinationRow: 5,
40
      destinationColumn: 2,
41
      type: 'sum',
42
      forceNumeric: true,
43
    },
44
  ],
45
  mergeCells: [{ row: 5, col: 0, rowspan: 1, colspan: 2 }],
46
  customBorders: [
47
    {
48
      row: 5,
49
      col: 2,
50
      top: { width: 2, color: '#333333' },
51
    },
52
  ],
53
  cell: [
54
    { row: 5, col: 0, readOnly: true },
55
    { row: 5, col: 2, readOnly: true },
56
  ],
57
  fixedColumnsStart: 1,
58
  rowHeaders: true,
59
  colHeaders: false,
60
  height: 'auto',
61
  autoWrapRow: true,
62
  autoWrapCol: true,
63
  exportFile: { engines: { xlsx: ExcelJS } },
64
  licenseKey: 'non-commercial-and-evaluation',
65
});
66

67
// Add a comment to Alice's notes cell.
68
hot.setCellMeta(0, 4, 'comment', { value: 'Top sales rep — review for promotion.' });
69
hot.render();
70

71
const exportPlugin = hot.getPlugin('exportFile');
72
const button = document.querySelector('#export-file');
73

74
button.addEventListener('click', async () => {
75
  await exportPlugin.downloadFileAsync('xlsx', {
76
    filename: 'Q1-Sales-Report',
77
    columnHeaders: true,
78
    rowHeaders: true,
79
    exportFormulas: true,
80
  });
81
});

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import ExcelJS from 'exceljs';
4

5
registerAllModules();
6

7
const container = document.querySelector('#example1')!;
8
const hot = new Handsontable(container, {
9
  data: [
10
    ['Alice Martin',  'North', 142000, true,  'Exceeded Q1 target by 18%.'],
11
    ['Bob Chen',      'East',   98500, true,  'Strong pipeline for Q2.'],
12
    ['Carol Davies',  'South',  76200, false, 'Needs coaching on closing.'],
13
    ['David Kim',     'West',  115300, true,  'Cross-sell opportunity.'],
14
    ['Eva Rossi',     'North',  54800, false, 'Sick leave impacted March.'],
15
    ['TOTALS',        '',       null,  '',    ''],
16
  ],
17
  nestedHeaders: [
18
    [
19
      { label: 'Sales Representative', colspan: 2, headerClassName: 'htCenter' },
20
      { label: 'Results',              colspan: 2, headerClassName: 'htCenter' },
21
      { label: 'Notes',                colspan: 1, headerClassName: 'htLeft'  },
22
    ],
23
    ['Name', 'Region', 'Revenue ($)', 'Hit Target?', 'Notes'],
24
  ],
25
  columns: [
26
    { type: 'text' },
27
    { type: 'dropdown', source: ['North', 'South', 'East', 'West'] },
28
    {
29
      type: 'numeric',
30
      locale: 'en-US',
31
      numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
32
    },
33
    { type: 'checkbox' },
34
    { type: 'text' },
35
  ],
36
  columnSummary: [
37
    {
38
      sourceColumn: 2,
39
      destinationRow: 5,
40
      destinationColumn: 2,
41
      type: 'sum',
42
      forceNumeric: true,
43
    },
44
  ],
45
  mergeCells: [
46
    { row: 5, col: 0, rowspan: 1, colspan: 2 },
47
  ],
48
  customBorders: [
49
    {
50
      row: 5, col: 2,
51
      top: { width: 2, color: '#333333' },
52
    },
53
  ],
54
  cell: [
55
    { row: 5, col: 0, readOnly: true },
56
    { row: 5, col: 2, readOnly: true },
57
  ],
58
  fixedColumnsStart: 1,
59
  rowHeaders: true,
60
  colHeaders: false,
61
  height: 'auto',
62
  autoWrapRow: true,
63
  autoWrapCol: true,
64
  exportFile: { engines: { xlsx: ExcelJS } },
65
  licenseKey: 'non-commercial-and-evaluation',
66
});
67

68
// Add a comment to Alice's notes cell.
69
hot.setCellMeta(0, 4, 'comment', { value: 'Top sales rep — review for promotion.' });
70
hot.render();
71

72
const exportPlugin = hot.getPlugin('exportFile');
73
const button = document.querySelector('#export-file')!;
74

75
button.addEventListener('click', async () => {
76
  await exportPlugin.downloadFileAsync('xlsx', {
77
    filename: 'Q1-Sales-Report',
78
    columnHeaders: true,
79
    rowHeaders: true,
80
    exportFormulas: true,
81
  });
82
});

1
<div class="example-controls-container">
2
  <div class="controls">
3
    <button id="export-file">Export XLSX</button>
4
  </div>
5
</div>
6
<div id="example1"></div>

Available methods

The plugin exposes the following methods to export data.

downloadFileAsync(format, options) - generates a downloadable .xlsx file directly in the browser. Returns a Promise that resolves when the download starts.
exportAsBlob(format, options) - exports the data as a JavaScript Blob. Returns a Promise that resolves with the Blob.

Both methods take two parameters. The first, format, must be 'xlsx'. The second, options, is an optional object that configures the exported workbook.

Both methods are asynchronous. Use await or .then() to handle the result:

1
const exportPlugin = hot.getPlugin('exportFile');
2

3
// Download a file.
4
await exportPlugin.downloadFileAsync('xlsx', { filename: 'my-report' });
5

6
// Get a Blob (e.g. to upload to a server).
7
const blob = await exportPlugin.exportAsBlob('xlsx', { filename: 'my-report' });

Plugin configuration

Configure the plugin in Handsontable’s settings under the exportFile key.

Option	Type	Default	Description
`engines`	`Object`	-	A map of format keys to their engine constructors. Pass `{ xlsx: ExcelJS }` to enable XLSX export via ExcelJS.

Export options

Pass these options as the second argument to downloadFileAsync('xlsx', options) or exportAsBlob('xlsx', options).

Option	Type / Default	Description
`filename`	`String`, default `'Handsontable [YYYY]-[MM]-[DD]'`	File name without extension. Placeholders `[YYYY]`, `[MM]`, and `[DD]` are replaced with the current date.
`columnHeaders`	`Boolean`, default `false`	Include column headers in the exported file. Supports the NestedHeaders plugin.
`rowHeaders`	`Boolean`, default `false`	Include row headers as a frozen first column in the exported file.
`exportHiddenColumns`	`Boolean` \| `'hide'`, default `false`	Controls how hidden columns are handled. `true` exports them as normal visible columns. `false` omits them entirely. `'hide'` exports them and marks them as hidden in Excel, so their data is preserved but not shown.
`exportHiddenRows`	`Boolean` \| `'hide'`, default `false`	Controls how hidden rows are handled. `true` exports them as normal visible rows. `false` omits them entirely. `'hide'` exports them and marks them as hidden in Excel, so their data is preserved but not shown.
`exportFormulas`	`Boolean`, default `false`	Export HyperFormula cells and ColumnSummary destination cells as live Excel formulas instead of their pre-calculated values.
`sheets`	`Array`, default `[]`	Multi-sheet configuration. Each entry is an object with an `instance` (a Handsontable object), a `name` (the sheet tab label), and any per-sheet options such as `columnHeaders` or `rowHeaders`. When provided, the top-level `instance` is ignored and each sheet is exported separately.
`compression`	`Boolean` \| `Number` (1–9), default `false`	Enable DEFLATE compression. `true` uses level 6. A number 1–9 sets a specific level (1 = fastest, 9 = smallest).
`conditionalFormatting`	`Array`, default `[]`	Array of conditional formatting descriptors. Each descriptor accepts optional `rows` and `cols` ranges (zero-based Handsontable indexes) and a `rules` array of ExcelJS conditional formatting rule objects.
`range`	`Array`, default `[]`	Cell range to export: `[startRow, startColumn, endRow, endColumn]` (visual indexes). When omitted, the entire grid is exported.

Multi-sheet export

Use the sheets option to export multiple Handsontable instances into a single workbook. Each entry specifies the instance to read from and a name for the sheet tab.

Q1 Sales

Q2 Sales

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import ExcelJS from 'exceljs';
4

5
registerAllModules();
6

7
const q1Data = [
8
  ['Alice Martin', 'North', 142000, true],
9
  ['Bob Chen', 'East', 98500, true],
10
  ['Carol Davies', 'South', 76200, false],
11
  ['David Kim', 'West', 115300, true],
12
  ['Eva Rossi', 'North', 54800, false],
13
];
14

15
const q2Data = [
16
  ['Alice Martin', 'North', 158000, true],
17
  ['Bob Chen', 'East', 112400, true],
18
  ['Carol Davies', 'South', 89100, true],
19
  ['David Kim', 'West', 97600, false],
20
  ['Eva Rossi', 'North', 63200, true],
21
];
22

23
const sharedConfig = {
24
  columns: [
25
    { type: 'text' },
26
    { type: 'dropdown', source: ['North', 'South', 'East', 'West'] },
27
    {
28
      type: 'numeric',
29
      locale: 'en-US',
30
      numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
31
    },
32
    { type: 'checkbox' },
33
  ],
34
  colHeaders: ['Name', 'Region', 'Revenue ($)', 'Hit Target?'],
35
  rowHeaders: true,
36
  height: 'auto',
37
  autoWrapRow: true,
38
  autoWrapCol: true,
39
  exportFile: { engines: { xlsx: ExcelJS } },
40
  licenseKey: 'non-commercial-and-evaluation',
41
};
42

43
const hotQ1 = new Handsontable(document.querySelector('#example2-q1'), {
44
  ...sharedConfig,
45
  data: q1Data,
46
});
47

48
const hotQ2 = new Handsontable(document.querySelector('#example2-q2'), {
49
  ...sharedConfig,
50
  data: q2Data,
51
});
52

53
document.querySelector('#export-sheets').addEventListener('click', async () => {
54
  const exportPlugin = hotQ1.getPlugin('exportFile');
55

56
  await exportPlugin.downloadFileAsync('xlsx', {
57
    filename: 'Annual-Sales-Report',
58
    sheets: [
59
      { instance: hotQ1, name: 'Q1 Sales', columnHeaders: true, rowHeaders: true },
60
      { instance: hotQ2, name: 'Q2 Sales', columnHeaders: true, rowHeaders: true },
61
    ],
62
  });
63
});

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import ExcelJS from 'exceljs';
4

5
registerAllModules();
6

7
const q1Data = [
8
  ['Alice Martin',  'North', 142000, true ],
9
  ['Bob Chen',      'East',   98500, true ],
10
  ['Carol Davies',  'South',  76200, false],
11
  ['David Kim',     'West',  115300, true ],
12
  ['Eva Rossi',     'North',  54800, false],
13
];
14

15
const q2Data = [
16
  ['Alice Martin',  'North', 158000, true ],
17
  ['Bob Chen',      'East',  112400, true ],
18
  ['Carol Davies',  'South',  89100, true ],
19
  ['David Kim',     'West',   97600, false],
20
  ['Eva Rossi',     'North',  63200, true ],
21
];
22

23
const sharedConfig: Handsontable.GridSettings = {
24
  columns: [
25
    { type: 'text' },
26
    { type: 'dropdown', source: ['North', 'South', 'East', 'West'] },
27
    {
28
      type: 'numeric',
29
      locale: 'en-US',
30
      numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
31
    },
32
    { type: 'checkbox' },
33
  ],
34
  colHeaders: ['Name', 'Region', 'Revenue ($)', 'Hit Target?'],
35
  rowHeaders: true,
36
  height: 'auto',
37
  autoWrapRow: true,
38
  autoWrapCol: true,
39
  exportFile: { engines: { xlsx: ExcelJS } },
40
  licenseKey: 'non-commercial-and-evaluation',
41
};
42

43
const hotQ1 = new Handsontable(document.querySelector('#example2-q1')!, {
44
  ...sharedConfig,
45
  data: q1Data,
46
});
47

48
const hotQ2 = new Handsontable(document.querySelector('#example2-q2')!, {
49
  ...sharedConfig,
50
  data: q2Data,
51
});
52

53
document.querySelector('#export-sheets')!.addEventListener('click', async () => {
54
  const exportPlugin = hotQ1.getPlugin('exportFile');
55

56
  await exportPlugin.downloadFileAsync('xlsx', {
57
    filename: 'Annual-Sales-Report',
58
    sheets: [
59
      { instance: hotQ1, name: 'Q1 Sales', columnHeaders: true, rowHeaders: true },
60
      { instance: hotQ2, name: 'Q2 Sales', columnHeaders: true, rowHeaders: true },
61
    ],
62
  });
63
});

1
<div class="example-controls-container">
2
  <div class="controls">
3
    <button id="export-sheets">Export XLSX</button>
4
  </div>
5
</div>
6
<p><strong>Q1 Sales</strong></p>
7
<div id="example2-q1"></div>
8
<p><strong>Q2 Sales</strong></p>
9
<div id="example2-q2"></div>

When the context menu is enabled, Export to CSV and Export to Excel items are automatically added to the grid’s context menu. No extra configuration in exportFile is needed.

The Export to Excel item is only shown when an ExcelJS engine is configured via engines: { xlsx: ExcelJS }. The Export to CSV item is always available.

When you select a cell range before opening the context menu, the export covers only the selected range. When no selection is active, the entire grid is exported.

Right-click any cell to open the context menu.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import ExcelJS from 'exceljs';
4

5
registerAllModules();
6
new Handsontable(document.querySelector('#example3'), {
7
  data: [
8
    ['Alice Martin', 'North', 142000, true],
9
    ['Bob Chen', 'East', 98500, true],
10
    ['Carol Davies', 'South', 76200, false],
11
    ['David Kim', 'West', 115300, true],
12
    ['Eva Rossi', 'North', 54800, false],
13
  ],
14
  columns: [
15
    { type: 'text' },
16
    { type: 'dropdown', source: ['North', 'South', 'East', 'West'] },
17
    {
18
      type: 'numeric',
19
      locale: 'en-US',
20
      numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
21
    },
22
    { type: 'checkbox' },
23
  ],
24
  colHeaders: ['Name', 'Region', 'Revenue ($)', 'Hit Target?'],
25
  rowHeaders: true,
26
  height: 'auto',
27
  autoWrapRow: true,
28
  autoWrapCol: true,
29
  contextMenu: true,
30
  exportFile: { engines: { xlsx: ExcelJS } },
31
  licenseKey: 'non-commercial-and-evaluation',
32
});

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import ExcelJS from 'exceljs';
4

5
registerAllModules();
6

7
new Handsontable(document.querySelector('#example3')!, {
8
  data: [
9
    ['Alice Martin',  'North', 142000, true ],
10
    ['Bob Chen',      'East',   98500, true ],
11
    ['Carol Davies',  'South',  76200, false],
12
    ['David Kim',     'West',  115300, true ],
13
    ['Eva Rossi',     'North',  54800, false],
14
  ],
15
  columns: [
16
    { type: 'text' },
17
    { type: 'dropdown', source: ['North', 'South', 'East', 'West'] },
18
    {
19
      type: 'numeric',
20
      locale: 'en-US',
21
      numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
22
    },
23
    { type: 'checkbox' },
24
  ],
25
  colHeaders: ['Name', 'Region', 'Revenue ($)', 'Hit Target?'],
26
  rowHeaders: true,
27
  height: 'auto',
28
  autoWrapRow: true,
29
  autoWrapCol: true,
30
  contextMenu: true,
31
  exportFile: { engines: { xlsx: ExcelJS } },
32
  licenseKey: 'non-commercial-and-evaluation',
33
});

1
<div class="example-controls-container">
2
  <p>Right-click any cell to open the context menu.</p>
3
</div>
4
<div id="example3"></div>

Cell types and styling

The following Handsontable cell types are recognized and written to the .xlsx file with their native Excel equivalents.

Handsontable type	Excel behavior
`numeric`	Number cell. The `numericFormat` option is translated to an Excel `numFmt` string using `Intl.NumberFormat`.
`date`	Date cell with an Excel date serial number. Reads ISO 8601 strings (`YYYY-MM-DD`).
`time`	Time cell with an Excel time serial number. Reads `HH:mm`, `HH:mm:ss`, and 12-hour (`h:mm AM/PM`) formats.
`checkbox`	Boolean cell (`TRUE` / `FALSE`).
`dropdown` / `autocomplete`	Text cell. The validation list is not exported.
All others	Text cell.

Cell styling is read from the rendered DOM at export time. The following properties are transferred to the workbook:

Font: bold, italic, underline, strikethrough, color, size, and family.
Fill: background color.
Alignment: horizontal (htLeft, htCenter, htRight, htJustify) and vertical (htTop, htMiddle, htBottom).
Borders: configurations set via the CustomBorders plugin. Border widths map to Excel styles: 1 px → thin, 2 px → medium, 3+ px → thick.

Read-only cells (readOnly: true) receive a light-gray fill and gray font color in the exported file by default. Applying CSS classes to a read-only cell overrides these defaults.

Plugins

ExportFile