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
readonly hotSettings: GridSettings = {
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
/* file: app.component.ts */
2
import { Component, ViewChild } from '@angular/core';
3
import { GridSettings, HotTableComponent } from '@handsontable/angular-wrapper';
4
import ExcelJS from 'exceljs';
5

6
@Component({
7
  selector: 'app-example1',
8
  template: `
9
    <div class="example-controls-container">
10
      <div class="controls">
11
        <button (click)="exportFile()">Export XLSX</button>
12
      </div>
13
    </div>
14

15
    <hot-table [settings]="hotSettings!" [data]="hotData" (afterInit)="onAfterInit()">
16
    </hot-table>
17
  `,
18
  standalone: false,
19
})
20
export class AppComponent {
21
  @ViewChild(HotTableComponent, { static: false }) hotTable!: HotTableComponent;
22

23
  readonly hotData = [
24
    ['Alice Martin',  'North', 142000, true,  'Exceeded Q1 target by 18%.'],
25
    ['Bob Chen',      'East',   98500, true,  'Strong pipeline for Q2.'],
26
    ['Carol Davies',  'South',  76200, false, 'Needs coaching on closing.'],
27
    ['David Kim',     'West',  115300, true,  'Cross-sell opportunity.'],
28
    ['Eva Rossi',     'North',  54800, false, 'Sick leave impacted March.'],
29
    ['TOTALS',        '',       null,  '',    ''],
30
  ];
31

32
  readonly hotSettings: GridSettings = {
33
    nestedHeaders: [
34
      [
35
        { label: 'Sales Representative', colspan: 2, headerClassName: 'htCenter' },
36
        { label: 'Results',              colspan: 2, headerClassName: 'htCenter' },
37
        { label: 'Notes',                colspan: 1, headerClassName: 'htLeft'  },
38
      ],
39
      ['Name', 'Region', 'Revenue ($)', 'Hit Target?', 'Notes'],
40
    ],
41
    columns: [
42
      { type: 'text' },
43
      { type: 'dropdown', source: ['North', 'South', 'East', 'West'] },
44
      {
45
        type: 'numeric',
46
        locale: 'en-US',
47
        numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
48
      },
49
      { type: 'checkbox' },
50
      { type: 'text' },
51
    ],
52
    columnSummary: [
53
      {
54
        sourceColumn: 2,
55
        destinationRow: 5,
56
        destinationColumn: 2,
57
        type: 'sum',
58
        forceNumeric: true,
59
      },
60
    ],
61
    mergeCells: [{ row: 5, col: 0, rowspan: 1, colspan: 2 }],
62
    customBorders: [{ row: 5, col: 2, top: { width: 2, color: '#333333' } }],
63
    cell: [
64
      { row: 5, col: 0, readOnly: true },
65
      { row: 5, col: 2, readOnly: true },
66
    ],
67
    fixedColumnsStart: 1,
68
    rowHeaders: true,
69
    colHeaders: false,
70
    height: 'auto',
71
    autoWrapRow: true,
72
    autoWrapCol: true,
73
    exportFile: { engines: { xlsx: ExcelJS } },
74
  };
75

76
  onAfterInit(): void {
77
    const hot = this.hotTable.hotInstance!;
78

79
    hot.setCellMeta(0, 4, 'comment', { value: 'Top sales rep — review for promotion.' });
80
    hot.render();
81
  }
82

83
  async exportFile(): Promise<void> {
84
    const exportPlugin = this.hotTable.hotInstance!.getPlugin('exportFile');
85

86
    await exportPlugin.downloadFileAsync('xlsx', {
87
      filename: 'Q1-Sales-Report',
88
      columnHeaders: true,
89
      rowHeaders: true,
90
      exportFormulas: true,
91
    });
92
  }
93
}
94
/* end-file */
95

96

97
/* file: app.module.ts */
98
import { NgModule, ApplicationConfig } from '@angular/core';
99
import { BrowserModule } from '@angular/platform-browser';
100
import { registerAllModules } from 'handsontable/registry';
101
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
102
import { CommonModule } from '@angular/common';
103
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
104

105
/* start:skip-in-compilation */
106
import { AppComponent } from './app.component';
107
/* end:skip-in-compilation */
108

109
registerAllModules();
110

111
export const appConfig: ApplicationConfig = {
112
  providers: [
113
    {
114
      provide: HOT_GLOBAL_CONFIG,
115
      useValue: {
116
        license: NON_COMMERCIAL_LICENSE,
117
      } as HotGlobalConfig,
118
    },
119
  ],
120
};
121

122
@NgModule({
123
  imports: [BrowserModule, HotTableModule, CommonModule],
124
  declarations: [AppComponent],
125
  providers: [...appConfig.providers],
126
  bootstrap: [AppComponent],
127
})
128
export class AppModule {}
129
/* end-file */

1
<div>
2
    <app-example1></app-example1>
3
</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
async exportFile(): Promise<void> {
2
  const exportPlugin = this.hotTable.hotInstance!.getPlugin('exportFile');
3

4
  await exportPlugin.downloadFileAsync('xlsx', { filename: 'my-report' });
5
}

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.

1
/* file: app.component.ts */
2
import { Component, ViewChild } from '@angular/core';
3
import { GridSettings, HotTableComponent } from '@handsontable/angular-wrapper';
4
import ExcelJS from 'exceljs';
5

6
@Component({
7
  selector: 'app-example2',
8
  template: `
9
    <div class="example-controls-container">
10
      <div class="controls">
11
        <button (click)="exportSheets()">Export XLSX</button>
12
      </div>
13
    </div>
14

15
    <p><strong>Q1 Sales</strong></p>
16
    <hot-table [settings]="sharedSettings" [data]="q1Data"></hot-table>
17

18
    <p><strong>Q2 Sales</strong></p>
19
    <hot-table #hotQ2 [settings]="sharedSettings" [data]="q2Data"></hot-table>
20
  `,
21
  standalone: false,
22
})
23
export class AppComponent {
24
  @ViewChild('hotQ2', { static: false }) hotQ2!: HotTableComponent;
25
  @ViewChild(HotTableComponent, { static: false }) hotQ1!: HotTableComponent;
26

27
  readonly q1Data = [
28
    ['Alice Martin',  'North', 142000, true ],
29
    ['Bob Chen',      'East',   98500, true ],
30
    ['Carol Davies',  'South',  76200, false],
31
    ['David Kim',     'West',  115300, true ],
32
    ['Eva Rossi',     'North',  54800, false],
33
  ];
34

35
  readonly q2Data = [
36
    ['Alice Martin',  'North', 158000, true ],
37
    ['Bob Chen',      'East',  112400, true ],
38
    ['Carol Davies',  'South',  89100, true ],
39
    ['David Kim',     'West',   97600, false],
40
    ['Eva Rossi',     'North',  63200, true ],
41
  ];
42

43
  readonly sharedSettings: GridSettings = {
44
    columns: [
45
      { type: 'text' },
46
      { type: 'dropdown', source: ['North', 'South', 'East', 'West'] },
47
      {
48
        type: 'numeric',
49
        locale: 'en-US',
50
        numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
51
      },
52
      { type: 'checkbox' },
53
    ],
54
    colHeaders: ['Name', 'Region', 'Revenue ($)', 'Hit Target?'],
55
    rowHeaders: true,
56
    height: 'auto',
57
    autoWrapRow: true,
58
    autoWrapCol: true,
59
    exportFile: { engines: { xlsx: ExcelJS } },
60
  };
61

62
  async exportSheets(): Promise<void> {
63
    const hotQ1 = this.hotQ1.hotInstance!;
64
    const exportPlugin = hotQ1.getPlugin('exportFile');
65

66
    await exportPlugin.downloadFileAsync('xlsx', {
67
      filename: 'Annual-Sales-Report',
68
      sheets: [
69
        { instance: hotQ1, name: 'Q1 Sales', columnHeaders: true, rowHeaders: true },
70
        { instance: this.hotQ2.hotInstance!, name: 'Q2 Sales', columnHeaders: true, rowHeaders: true },
71
      ],
72
    });
73
  }
74
}
75
/* end-file */
76

77

78
/* file: app.module.ts */
79
import { NgModule, ApplicationConfig } from '@angular/core';
80
import { BrowserModule } from '@angular/platform-browser';
81
import { registerAllModules } from 'handsontable/registry';
82
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
83
import { CommonModule } from '@angular/common';
84
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
85

86
/* start:skip-in-compilation */
87
import { AppComponent } from './app.component';
88
/* end:skip-in-compilation */
89

90
registerAllModules();
91

92
export const appConfig: ApplicationConfig = {
93
  providers: [
94
    {
95
      provide: HOT_GLOBAL_CONFIG,
96
      useValue: {
97
        license: NON_COMMERCIAL_LICENSE,
98
      } as HotGlobalConfig,
99
    },
100
  ],
101
};
102

103
@NgModule({
104
  imports: [BrowserModule, HotTableModule, CommonModule],
105
  declarations: [AppComponent],
106
  providers: [...appConfig.providers],
107
  bootstrap: [AppComponent],
108
})
109
export class AppModule {}
110
/* end-file */

1
<div>
2
    <app-example2></app-example2>
3
</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.

1
/* file: app.component.ts */
2
import { Component } from '@angular/core';
3
import { GridSettings } from '@handsontable/angular-wrapper';
4
import ExcelJS from 'exceljs';
5

6
@Component({
7
  selector: 'app-example3',
8
  template: `
9
    <div class="example-controls-container">
10
      <p>Right-click any cell to open the context menu.</p>
11
    </div>
12
    <hot-table [settings]="hotSettings" [data]="hotData"></hot-table>
13
  `,
14
  standalone: false,
15
})
16
export class AppComponent {
17
  readonly hotData = [
18
    ['Alice Martin',  'North', 142000, true ],
19
    ['Bob Chen',      'East',   98500, true ],
20
    ['Carol Davies',  'South',  76200, false],
21
    ['David Kim',     'West',  115300, true ],
22
    ['Eva Rossi',     'North',  54800, false],
23
  ];
24

25
  readonly hotSettings: GridSettings = {
26
    columns: [
27
      { type: 'text' },
28
      { type: 'dropdown', source: ['North', 'South', 'East', 'West'] },
29
      {
30
        type: 'numeric',
31
        locale: 'en-US',
32
        numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
33
      },
34
      { type: 'checkbox' },
35
    ],
36
    colHeaders: ['Name', 'Region', 'Revenue ($)', 'Hit Target?'],
37
    rowHeaders: true,
38
    height: 'auto',
39
    autoWrapRow: true,
40
    autoWrapCol: true,
41
    contextMenu: true,
42
    exportFile: { engines: { xlsx: ExcelJS } },
43
  };
44
}
45
/* end-file */
46

47

48
/* file: app.module.ts */
49
import { NgModule, ApplicationConfig } from '@angular/core';
50
import { BrowserModule } from '@angular/platform-browser';
51
import { registerAllModules } from 'handsontable/registry';
52
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
53
import { CommonModule } from '@angular/common';
54
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
55

56
/* start:skip-in-compilation */
57
import { AppComponent } from './app.component';
58
/* end:skip-in-compilation */
59

60
registerAllModules();
61

62
export const appConfig: ApplicationConfig = {
63
  providers: [
64
    {
65
      provide: HOT_GLOBAL_CONFIG,
66
      useValue: {
67
        license: NON_COMMERCIAL_LICENSE,
68
      } as HotGlobalConfig,
69
    },
70
  ],
71
};
72

73
@NgModule({
74
  imports: [BrowserModule, HotTableModule, CommonModule],
75
  declarations: [AppComponent],
76
  providers: [...appConfig.providers],
77
  bootstrap: [AppComponent],
78
})
79
export class AppModule {}
80
/* end-file */

1
<div>
2
    <app-example3></app-example3>
3
</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