ExportFile
See the Export to CSV guide for examples and configuration details. See the Export to Excel guide for examples and configuration details.
Options
exportFile
Can be set at: grid
exportFile.exportFile : boolean | object
The exportFile option configures the ExportFile plugin.
You can set the exportFile option to one of the following:
| Setting | Description |
|---|---|
undefined | Use the ExportFile plugin with the default configuration, with the context-menu entry hidden |
true | Use the plugin with the default configuration (built-in xlsx engine), with the context-menu entry shown |
false | The same as true: the plugin stays enabled, its API keeps working, and the context-menu entry is shown. To hide the entry, leave the option undefined |
| An object | Enable the ExportFile plugin and modify the plugin options |
If you set the exportFile option to an object, you can configure the following options:
| Option | Type | Default | Description |
|---|---|---|---|
engines | Object | – | Optional. A map of format keys to engine modules. Pass { xlsx: ExcelJS } to export through ExcelJS instead of the built-in engine. |
Read more:
Default: undefined
Since: 17.1.0
Example
// XLSX and CSV export with the built-in engineexportFile: true,
// or export XLSX through ExcelJSimport ExcelJS from 'exceljs';
exportFile: { engines: { xlsx: ExcelJS },},Members
LICENSE
ExportFile.LICENSE
Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.
PLUGIN_KEY
ExportFile.PLUGIN_KEY
Returns the plugin key used to identify this plugin in Handsontable settings.
PLUGIN_PRIORITY
ExportFile.PLUGIN_PRIORITY
Returns the priority order used to determine the order in which plugins are initialized.
SETTING_KEYS
ExportFile.SETTING_KEYS
Returns the setting keys that trigger a plugin update when changed via updateSettings.
Methods
destroy
exportFile.destroy()
Revokes the object URL of every download whose revoke timeout has not run yet, then runs the
base plugin teardown. Core#destroy clears every _registerTimeout before the plugins are
destroyed, so a grid torn down within the timeout would otherwise keep each blob alive until the
page unloads.
disablePlugin
exportFile.disablePlugin()
Disables the plugin functionality for this Handsontable instance.
downloadFile
exportFile.downloadFile(format, options) ⇒ void
Triggers a synchronous file download for text-based export formats (e.g. 'csv').
Calling this method with a binary format (e.g. 'xlsx') throws an error — use
ExportFile#downloadFileAsync instead.
Throws:
ErrorWhen the license key names tiers and none of them includes Export to file.
| Param | Type | Default | Description |
|---|---|---|---|
| format | string | Export format type e.g. 'csv'. | |
| options | object | Export options. | |
| [options.mimeType] | string | optional MIME type. Default depends on format. | |
| [options.fileExtension] | string | optional File extension. Default depends on format. | |
| [options.filename] | string | ”Handsontable [YYYY]-[MM]-[DD]“ | optional File name. |
| [options.encoding] | string | ”utf-8” | optional Charset label of the Blob; the content is always UTF-8. |
| [options.bom] | boolean | optional Include BOM signature. Default depends on format. | |
| [options.columnDelimiter] | string | ”,“ | optional Column delimiter (CSV only). |
| [options.rowDelimiter] | string | ”\r\n” | optional Row delimiter (CSV only). |
| [options.colHeaders] | boolean | false | optional Include column headers. |
| [options.rowHeaders] | boolean | false | optional Include row headers. |
| [options.exportHiddenColumns] | boolean | false | optional Include hidden columns. |
| [options.exportHiddenRows] | boolean | false | optional Include hidden rows. |
| [options.range] | Array<number> | [] | optional Cell range: [startRow, startColumn, endRow, endColumn]. |
| [options.sanitizeValues] | boolean RegExp function | false | optional Sanitization (CSV only). |
downloadFileAsync
exportFile.downloadFileAsync(format, options) ⇒ Promise<void>
Triggers an asynchronous file download. Supports all export formats.
For text-based formats (e.g. 'csv'), the download is triggered immediately
and the returned Promise resolves right away.
For binary formats (e.g. 'xlsx'), the export runs asynchronously. When the
dialog plugin is enabled, a progress overlay is shown for the duration of the export. The
export reads the data after the overlay is painted, so a Core#loadData call made before
that, for example a sheets bar switch, rejects the returned Promise and downloads nothing.
Throws:
ErrorThe returned promise rejects when the license key names tiers and none of them includes Export to file.
Since: 17.1.0
| Param | Type | Default | Description |
|---|---|---|---|
| format | string | Export format type e.g. 'csv' or 'xlsx'. | |
| options | object | Export options. | |
| [options.mimeType] | string | optional MIME type. Default depends on format. | |
| [options.fileExtension] | string | optional File extension. Default depends on format. | |
| [options.filename] | string | ”Handsontable [YYYY]-[MM]-[DD]“ | optional File name. |
| [options.encoding] | string | ”utf-8” | optional Charset label of the Blob and the download; the content is always UTF-8 (text formats only). |
| [options.bom] | boolean | optional Include BOM signature (text formats only). | |
| [options.columnDelimiter] | string | ”,“ | optional Column delimiter (CSV only). |
| [options.rowDelimiter] | string | ”\r\n” | optional Row delimiter (CSV only). |
| [options.colHeaders] | boolean | false | optional Include column headers. |
| [options.rowHeaders] | boolean | false | optional Include row headers. |
| [options.exportHiddenColumns] | boolean string | false | optional Hidden columns: true exports them visible, false leaves them out, 'hide' writes them hidden in the sheet (XLSX only). |
| [options.exportHiddenRows] | boolean string | false | optional Hidden rows: true exports them visible, false leaves them out, 'hide' writes them hidden in the sheet (XLSX only). |
| [options.range] | Array<number> | [] | optional Cell range: [startRow, startColumn, endRow, endColumn]. |
| [options.sanitizeValues] | boolean RegExp function | false | optional Sanitization (CSV only). |
| [options.exportFormulas] | boolean | false | optional Export cell formulas instead of their computed values (XLSX only). |
| [options.compression] | boolean number | optional DEFLATE compression (XLSX only). Omitted, null, true or any value other than false and a number 1–9 compresses at level 6. A number 1–9 sets the level on the ExcelJS engine; the built-in engine always uses the platform’s default level. false stores the entries uncompressed. | |
| [options.conditionalFormatting] | Array<ConditionalFormattingDescriptor> | [] | optional Conditional formatting rules to apply to the exported file (XLSX only). |
| [options.sheets] | Array<SheetOptions> | [] | optional Configuration for multi-sheet export. Each entry defines one worksheet (XLSX only). |
| [options.headerStyle] | HeaderStyle null | optional Fill and border of the header cells (XLSX only). Defaults to a light-gray fill with a thin border; an object replaces the whole default, null writes unstyled headers. | |
| [options.engine] | object null | optional Engine for this call only (XLSX only). null or an absent key keeps the engine from the engines setting, or the built-in one. | |
| [options.protection] | object null | optional Sheet protection of read-only cells (XLSX only). Unset protects a sheet that has a read-only cell with no password, and null protects no sheet. With the built-in engine, an export that protects a sheet with a password needs a secure context (https or localhost), or it rejects. | |
| [options.protection.password] | string | optional The sheet password, at most 255 characters. An empty one sets no password. |
enablePlugin
exportFile.enablePlugin()
Enables the plugin functionality for this Handsontable instance.
exportAsBlob
exportFile.exportAsBlob(format, options) ⇒ Blob
Exports table data as a blob object.
This method is only supported for text-based formats such as CSV.
Calling it with a binary format (e.g. 'xlsx') throws an error — use
ExportFile#exportAsBlobAsync instead.
Throws:
ErrorWhen the license key names tiers and none of them includes Export to file.
| Param | Type | Default | Description |
|---|---|---|---|
| format | string | Export format type e.g. 'csv'. | |
| options | object | Export options. | |
| [options.mimeType] | string | optional MIME type. Default depends on format. | |
| [options.fileExtension] | string | optional File extension. Default depends on format. | |
| [options.filename] | string | ”Handsontable [YYYY]-[MM]-[DD]“ | optional File name. |
| [options.encoding] | string | ”utf-8” | optional Charset label of the Blob; the content is always UTF-8. |
| [options.bom] | boolean | optional Include BOM signature. Default depends on format (e.g. true for CSV). | |
| [options.columnDelimiter] | string | ”,“ | optional Column delimiter (CSV only). |
| [options.rowDelimiter] | string | ”\r\n” | optional Row delimiter (CSV only). |
| [options.colHeaders] | boolean | false | optional Include column headers. |
| [options.rowHeaders] | boolean | false | optional Include row headers. |
| [options.exportHiddenColumns] | boolean | false | optional Include hidden columns. |
| [options.exportHiddenRows] | boolean | false | optional Include hidden rows. |
| [options.range] | Array<number> | [] | optional Cell range: [startRow, startColumn, endRow, endColumn]. |
| [options.sanitizeValues] | boolean RegExp function | false | optional Sanitization (CSV only). |
exportAsBlobAsync
exportFile.exportAsBlobAsync(format, options) ⇒ Promise<Blob>
Exports table data as a blob object, asynchronously.
Supports all export formats. For text-based formats (e.g. 'csv'),
the Promise resolves immediately. For binary formats (e.g. 'xlsx'),
the export runs asynchronously.
Throws:
ErrorThe returned promise rejects when the license key names tiers and none of them includes Export to file.
Since: 17.1.0
| Param | Type | Default | Description |
|---|---|---|---|
| format | string | Export format type e.g. 'csv' or 'xlsx'. | |
| options | object | Export options. | |
| [options.mimeType] | string | optional MIME type. Default depends on format. | |
| [options.fileExtension] | string | optional File extension. Default depends on format. | |
| [options.filename] | string | ”Handsontable [YYYY]-[MM]-[DD]“ | optional File name. |
| [options.encoding] | string | ”utf-8” | optional Charset label of the Blob and the download; the content is always UTF-8 (text formats only). |
| [options.bom] | boolean | optional Include BOM signature (text formats only). | |
| [options.columnDelimiter] | string | ”,“ | optional Column delimiter (CSV only). |
| [options.rowDelimiter] | string | ”\r\n” | optional Row delimiter (CSV only). |
| [options.colHeaders] | boolean | false | optional Include column headers. |
| [options.rowHeaders] | boolean | false | optional Include row headers. |
| [options.exportHiddenColumns] | boolean string | false | optional Hidden columns: true exports them visible, false leaves them out, 'hide' writes them hidden in the sheet (XLSX only). |
| [options.exportHiddenRows] | boolean string | false | optional Hidden rows: true exports them visible, false leaves them out, 'hide' writes them hidden in the sheet (XLSX only). |
| [options.range] | Array<number> | [] | optional Cell range: [startRow, startColumn, endRow, endColumn]. |
| [options.sanitizeValues] | boolean RegExp function | false | optional Sanitization (CSV only). |
| [options.exportFormulas] | boolean | false | optional Export cell formulas instead of their computed values (XLSX only). |
| [options.compression] | boolean number | optional DEFLATE compression (XLSX only). Omitted, null, true or any value other than false and a number 1–9 compresses at level 6. A number 1–9 sets the level on the ExcelJS engine; the built-in engine always uses the platform’s default level. false stores the entries uncompressed. | |
| [options.conditionalFormatting] | Array<ConditionalFormattingDescriptor> | [] | optional Conditional formatting rules to apply to the exported file (XLSX only). |
| [options.sheets] | Array<SheetOptions> | [] | optional Configuration for multi-sheet export. Each entry defines one worksheet (XLSX only). |
| [options.headerStyle] | HeaderStyle null | optional Fill and border of the header cells (XLSX only). Defaults to a light-gray fill with a thin border; an object replaces the whole default, null writes unstyled headers. | |
| [options.engine] | object null | optional Engine for this call only (XLSX only). null or an absent key keeps the engine from the engines setting, or the built-in one. | |
| [options.protection] | object null | optional Sheet protection of read-only cells (XLSX only). Unset protects a sheet that has a read-only cell with no password, and null protects no sheet. With the built-in engine, an export that protects a sheet with a password needs a secure context (https or localhost), or it rejects. | |
| [options.protection.password] | string | optional The sheet password, at most 255 characters. An empty one sets no password. |
exportAsString
exportFile.exportAsString(format, options) ⇒ string
Exports table data as a string.
This method is only supported for text-based formats such as CSV.
Calling it with a binary format (e.g. 'xlsx') throws an error.
Throws:
ErrorWhen the license key names tiers and none of them includes Export to file.
| Param | Type | Default | Description |
|---|---|---|---|
| format | string | Export format type eq. 'csv'. | |
| options | object | Export options. | |
| [options.mimeType] | string | optional MIME type (e.g. 'text/csv' for CSV). Default depends on format. | |
| [options.fileExtension] | string | optional File extension (e.g. 'csv'). Default depends on format. | |
| [options.filename] | string | ”Handsontable [YYYY]-[MM]-[DD]“ | optional File name. Placeholders [YYYY], [MM], [DD] are replaced with the current date. |
| [options.encoding] | string | ”utf-8” | optional Charset label of the Blob; the content is always UTF-8. |
| [options.bom] | boolean | optional Include BOM signature. Default depends on format (e.g. true for CSV). | |
| [options.columnDelimiter] | string | ”,“ | optional Column delimiter (CSV only). |
| [options.rowDelimiter] | string | ”\r\n” | optional Row delimiter (CSV only). |
| [options.colHeaders] | boolean | false | optional Include column headers in the exported file. |
| [options.rowHeaders] | boolean | false | optional Include row headers in the exported file. |
| [options.exportHiddenColumns] | boolean string | false | optional Controls how hidden columns are handled. true or 'hide' exports them as normal columns, false omits them. |
| [options.exportHiddenRows] | boolean string | false | optional Controls how hidden rows are handled. true or 'hide' exports them as normal rows, false omits them. |
| [options.range] | Array<number> | [] | optional Cell range to export: [startRow, startColumn, endRow, endColumn] (visual indexes). |
| [options.sanitizeValues] | boolean RegExp function | false | optional Controls the sanitization of cell values (CSV only). |
isEnabled
exportFile.isEnabled() ⇒ boolean
Checks if the plugin is enabled in the handsontable settings. This method is executed in Hooks#beforeInit
hook and if it returns true then the ExportFile#enablePlugin method is called.
supportsExportFormat
exportFile.supportsExportFormat(format) ⇒ boolean
Returns true when the plugin can produce an export in the given format. 'csv' always can,
because it needs no engine. 'xlsx' can through the built-in xlsx engine or through the one
configured in engines; an engine of unknown shape writes nothing and answers false, which
is the same answer ImportFile#supportsImportFormat gives for that configuration. 'xlsx' also
answers false whenever an xlsx export would throw for the license: when the license key names
tiers and none of them includes feat:export_file, the plugin’s own feature, or none includes
xlsx:export. A key that names no tier is not restricted. 'csv' does not read the license here, although the
export methods still need feat:export_file for it.
| Param | Type | Description |
|---|---|---|
| format | string | Export format — 'csv' or 'xlsx'. |