Skip to content

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

Source code

exportFile.exportFile : boolean | object

The exportFile option configures the ExportFile plugin.

You can set the exportFile option to one of the following:

SettingDescription
undefinedUse the ExportFile plugin with the default configuration, with the context-menu entry hidden
trueUse the plugin with the default configuration (built-in xlsx engine), with the context-menu entry shown
falseThe 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 objectEnable the ExportFile plugin and modify the plugin options

If you set the exportFile option to an object, you can configure the following options:

OptionTypeDefaultDescription
enginesObject–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 engine
exportFile: true,
// or export XLSX through ExcelJS
import ExcelJS from 'exceljs';
exportFile: {
engines: { xlsx: ExcelJS },
},

Members

LICENSE

Source code

ExportFile.LICENSE

Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.

PLUGIN_KEY

Source code

ExportFile.PLUGIN_KEY

Returns the plugin key used to identify this plugin in Handsontable settings.

PLUGIN_PRIORITY

Source code

ExportFile.PLUGIN_PRIORITY

Returns the priority order used to determine the order in which plugins are initialized.

SETTING_KEYS

Source code

ExportFile.SETTING_KEYS

Returns the setting keys that trigger a plugin update when changed via updateSettings.

Methods

destroy

Source code

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

Source code

exportFile.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

downloadFile

Source code

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:

  • Error When the license key names tiers and none of them includes Export to file.
ParamTypeDefaultDescription
formatstringExport format type e.g. 'csv'.
optionsobjectExport options.
[options.mimeType]stringoptional MIME type. Default depends on format.
[options.fileExtension]stringoptional 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]booleanoptional 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]booleanfalseoptional Include column headers.
[options.rowHeaders]booleanfalseoptional Include row headers.
[options.exportHiddenColumns]booleanfalseoptional Include hidden columns.
[options.exportHiddenRows]booleanfalseoptional Include hidden rows.
[options.range]Array<number>[]optional Cell range: [startRow, startColumn, endRow, endColumn].
[options.sanitizeValues]boolean
RegExp
function
falseoptional Sanitization (CSV only).

downloadFileAsync

Source code

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:

  • Error The returned promise rejects when the license key names tiers and none of them includes Export to file.

Since: 17.1.0

ParamTypeDefaultDescription
formatstringExport format type e.g. 'csv' or 'xlsx'.
optionsobjectExport options.
[options.mimeType]stringoptional MIME type. Default depends on format.
[options.fileExtension]stringoptional 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]booleanoptional 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]booleanfalseoptional Include column headers.
[options.rowHeaders]booleanfalseoptional Include row headers.
[options.exportHiddenColumns]boolean
string
falseoptional Hidden columns: true exports them visible, false leaves them out, 'hide' writes them hidden in the sheet (XLSX only).
[options.exportHiddenRows]boolean
string
falseoptional 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
falseoptional Sanitization (CSV only).
[options.exportFormulas]booleanfalseoptional 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]stringoptional The sheet password, at most 255 characters. An empty one sets no password.

enablePlugin

Source code

exportFile.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

exportAsBlob

Source code

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:

  • Error When the license key names tiers and none of them includes Export to file.
ParamTypeDefaultDescription
formatstringExport format type e.g. 'csv'.
optionsobjectExport options.
[options.mimeType]stringoptional MIME type. Default depends on format.
[options.fileExtension]stringoptional 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]booleanoptional 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]booleanfalseoptional Include column headers.
[options.rowHeaders]booleanfalseoptional Include row headers.
[options.exportHiddenColumns]booleanfalseoptional Include hidden columns.
[options.exportHiddenRows]booleanfalseoptional Include hidden rows.
[options.range]Array<number>[]optional Cell range: [startRow, startColumn, endRow, endColumn].
[options.sanitizeValues]boolean
RegExp
function
falseoptional Sanitization (CSV only).

exportAsBlobAsync

Source code

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:

  • Error The returned promise rejects when the license key names tiers and none of them includes Export to file.

Since: 17.1.0

ParamTypeDefaultDescription
formatstringExport format type e.g. 'csv' or 'xlsx'.
optionsobjectExport options.
[options.mimeType]stringoptional MIME type. Default depends on format.
[options.fileExtension]stringoptional 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]booleanoptional 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]booleanfalseoptional Include column headers.
[options.rowHeaders]booleanfalseoptional Include row headers.
[options.exportHiddenColumns]boolean
string
falseoptional Hidden columns: true exports them visible, false leaves them out, 'hide' writes them hidden in the sheet (XLSX only).
[options.exportHiddenRows]boolean
string
falseoptional 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
falseoptional Sanitization (CSV only).
[options.exportFormulas]booleanfalseoptional 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]stringoptional The sheet password, at most 255 characters. An empty one sets no password.

exportAsString

Source code

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:

  • Error When the license key names tiers and none of them includes Export to file.
ParamTypeDefaultDescription
formatstringExport format type eq. 'csv'.
optionsobjectExport options.
[options.mimeType]stringoptional MIME type (e.g. 'text/csv' for CSV). Default depends on format.
[options.fileExtension]stringoptional 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]booleanoptional 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]booleanfalseoptional Include column headers in the exported file.
[options.rowHeaders]booleanfalseoptional Include row headers in the exported file.
[options.exportHiddenColumns]boolean
string
falseoptional Controls how hidden columns are handled. true or 'hide' exports them as normal columns, false omits them.
[options.exportHiddenRows]boolean
string
falseoptional 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
falseoptional Controls the sanitization of cell values (CSV only).

isEnabled

Source code

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

Source code

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.

ParamTypeDescription
formatstringExport format — 'csv' or 'xlsx'.