Skip to content

ImportFile

See the Import from Excel guide for examples and configuration details. See the Infer column types guide for examples and configuration details.

Options

importFile

Can be set at: grid

Source code

importFile.importFile : boolean | object

The importFile option configures the ImportFile plugin.

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

SettingDescription
undefinedUse the ImportFile plugin with the default configuration
trueUse the ImportFile plugin with the default configuration
falseDisable the ImportFile plugin
An objectEnable the ImportFile plugin and modify the plugin options

If you set the importFile 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 import through ExcelJS instead of the built-in engine.

false disables the plugin. Any other value, including leaving the option out, enables it.

Read more:

Default: undefined
Since: 19.0.0
Example

// XLSX import with the built-in engine
importFile: true,
// or import XLSX through ExcelJS
import ExcelJS from 'exceljs';
importFile: {
engines: { xlsx: ExcelJS },
},

Members

LICENSE

Source code

ImportFile.LICENSE

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

PLUGIN_KEY

Source code

ImportFile.PLUGIN_KEY

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

PLUGIN_PRIORITY

Source code

ImportFile.PLUGIN_PRIORITY

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

SETTING_KEYS

Source code

ImportFile.SETTING_KEYS

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

Methods

convertToInferredTypes

Source code

importFile.convertToInferredTypes()

Returns a copy of data with every value converted to what its column’s inferred cell type stores: a number for numeric, YYYY-MM-DD for date, YYYY-MM-DDTHH:mm:ss for intl-datetime, HH:mm:ss for time, and a boolean for checkbox. A Date converts to its local date and time. A value the column cannot read, such as a Total row, is kept as it is, so the cell type’s validator marks it. When the result found a header row, that row is left out. data itself is not changed.

Throws:

  • Error When the license key names tiers and none of them includes Import from file.

destroy

Source code

importFile.destroy()

Removes the instance-owned stylesheet installed by a previous import before the base plugin teardown runs.

disablePlugin

Source code

importFile.disablePlugin()

Disables the plugin functionality for this Handsontable instance and removes the stylesheet a previous import installed, so htImported-* rules stop painting cells whose meta still carries the class. Every import still reading is made stale too: the enabled check at apply time sees only the state at the end of the read, so importFile: false and then true during a read let that read apply.

enablePlugin

Source code

importFile.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

importFromArrayBuffer

Source code

importFile.importFromArrayBuffer(format, buffer, [options]) ⇒ Promise<ImportResult>

Reads a workbook from an ArrayBuffer (or a view onto one, such as a Uint8Array) and maps it into an ImportResult. Applies the result to the grid unless options.apply is false or a beforeImport hook returns false.

When a newer import that applies its result starts on the same instance before this one finishes, this one is not applied and the returned promise rejects: the import started last wins. An apply: false import neither cancels another import nor is cancelled by one. Turning the plugin off (importFile: false) while the file is being read rejects the import too, even when the plugin is turned back on before the read ends. So does a Core#loadData call made while the file is being read, for example a sheets bar switch: the result is not applied over the data loaded in the meantime.

Throws:

  • Error The returned promise rejects when the license key names tiers and none of them includes Import from file.
ParamTypeDescription
formatstringThe import format, e.g. 'xlsx'.
bufferArrayBuffer
ArrayBufferView
The file’s bytes.
[options]ImportOptionsoptional Import options.

importFromBlob

Source code

importFile.importFromBlob(format, blob, [options]) ⇒ Promise<ImportResult>

Reads a workbook from a Blob (e.g. a File from an <input type="file">) and maps it into an ImportResult. Applies the result to the grid unless options.apply is false or a beforeImport hook returns false.

When a newer import that applies its result starts on the same instance before this one finishes, this one is not applied and the returned promise rejects: the import started last wins. An apply: false import neither cancels another import nor is cancelled by one. Turning the plugin off (importFile: false) while the file is being read rejects the import too, even when the plugin is turned back on before the read ends. So does a Core#loadData call made while the file is being read, for example a sheets bar switch: the result is not applied over the data loaded in the meantime.

Throws:

  • Error The returned promise rejects when the license key names tiers and none of them includes Import from file.
ParamTypeDescription
formatstringThe import format, e.g. 'xlsx'.
blobBlobThe file.
[options]ImportOptionsoptional Import options.

inferColumnTypes

Source code

importFile.inferColumnTypes()

Infers a cell type and format for every column of raw, untyped data: rows parsed from a CSV file, pasted text split into cells, or values from an API. Works without an engine.

Returns { columns, headerRow }. Each column is { settings, confidence, inputFormat, title, stats }. settings holds the column options (type, numericFormat, dateFormat, dateTimeFormat, timeFormat, source, and data for object rows) and can be passed to columns as it is. confidence is the share of values the type reads, inputFormat is how the raw values were written, title is the header (see the headerRow option), and stats is set with the stats option. A column that no type reads with at least minConfidence falls back to 'text'.

The result is deterministic: it reads sampleSize rows (the first ones, or with sampling: 'spread' rows spaced evenly across the data) and settles an ambiguous column (1.234, 12/03/2026) with options.locale, which defaults to the grid’s locale. The dateFormats option lists date formats to read, and booleanValues lists words a checkbox column reads as true and false.

Throws:

  • Error When the license key names tiers and none of them includes Import from file.

Example

const importFile = hot.getPlugin('importFile');
const result = importFile.inferColumnTypes(rows, { locale: 'de-DE', headerRow: 'auto' });
hot.updateSettings({
columns: result.columns.map(({ settings }) => settings),
colHeaders: result.columns.map(({ title }) => title),
data: importFile.convertToInferredTypes(rows, result),
});

isEnabled

Source code

importFile.isEnabled()

Enabled unless the importFile option is false; the engine decides what it can import.

supportsImportFormat

Source code

importFile.supportsImportFormat(format) ⇒ boolean

Returns true when the format can be read: xlsx, through the built-in engine or the one configured in engines. An engine of unknown shape reads nothing and answers false. 'xlsx' also answers false whenever an xlsx import would throw for the license: when the license key names tiers and none of them includes feat:import_file, the plugin’s own feature, or none includes xlsx:import. A key that names no tier is not restricted.

ParamTypeDescription
formatstringThe import format, e.g. 'xlsx'.