---
title: "Import and load spreadsheets"
canonical_url: "https://www.nutrient.io/guides/document-authoring/spreadsheets/import-and-load/"
md_url: "https://www.nutrient.io/guides/document-authoring/spreadsheets/import-and-load.md"
last_updated: "2026-10-14T00:00:00.000Z"
description: "Open XLSX files and saved SheetJSON spreadsheets in Document Authoring, show import progress, and cancel an import."
---

# Import and load spreadsheets

Use [`importSpreadsheet()`](https://www.nutrient.io/api/document-authoring/types/docauthsystem/#importspreadsheet) to open an XLSX file. Use [`loadSpreadsheet()`](https://www.nutrient.io/api/document-authoring/types/docauthsystem/#loadspreadsheet) to reopen a spreadsheet saved as SheetJSON. Both methods return a [`DocAuthSpreadsheet`](https://www.nutrient.io/api/document-authoring/types/docauthspreadsheet/) that you can display in an editor, save, or export.

Before you start, install and run the Document Authoring library in your app. If you haven’t set it up, refer to the [getting started](https://www.nutrient.io/guides/document-authoring/spreadsheets/getting-started.md) guide.

The examples omit error handling. Add it before you use this code in production.

## Supported formats

`importSpreadsheet()` reads these formats:

- `xlsx` — Microsoft Excel.

- `sheetjson` — Document Authoring’s native spreadsheet format.

Document Authoring doesn’t read macro-enabled XLSM files, XLTX templates, binary XLS files, CSV, or ODS. The import method rejects these files with an error.

## Import an XLSX file

Pass the file to `importSpreadsheet()` to import it. Document Authoring detects the format from the file content and uses `fileName` as a hint. Use the file’s actual name because an incorrect extension can cause the import to fail:

```js

const fileInput = document.querySelector('input[type="file"]');

fileInput.addEventListener('change', async () => {
  const file = fileInput.files?.[0];
  if (!file) {
    return;
  }

  const spreadsheet = await system.importSpreadsheet(file, { fileName: file.name });
  editor.setCurrentSpreadsheet(spreadsheet);
});

```

### Import with an explicit format

If you know the format, pass it in `format` to skip detection. Document Authoring still checks the file content and rejects files that don’t match:

```js

const spreadsheet = await system.importSpreadsheet(blob, { format: 'xlsx' });

```

## Load a saved spreadsheet

Use `loadSpreadsheet()` to reopen a spreadsheet saved with [`saveSpreadsheet()`](https://www.nutrient.io/api/document-authoring/types/docauthspreadsheet/#savespreadsheet). This method reads SheetJSON only:

```js

const spreadsheet = await system.loadSpreadsheet(fetch('/api/spreadsheets/123'));

```

`loadSpreadsheet()` accepts a `Blob`, `Response`, `ArrayBuffer`, `Uint8Array`, JSON string, parsed object, or promise of these values. For large spreadsheets, pass a `Blob`, `Response`, or bytes. Strings and parsed objects must fit in memory.

## Show import progress

Pass `onProgress` to show the user the import progress. `loadSpreadsheet()` accepts this option too.

Progress can include up to three phases: `reading`, `indexing`, and `loading`. Some imports skip phases. The `done` and `total` counts restart for each phase, so report progress separately for each one:

```js

const status = document.getElementById('status');

const spreadsheet = await system.importSpreadsheet(file, {
  fileName: file.name,
  onProgress: ({ phase, done, total }) => {
    if (total === null) {
      status.textContent = `${phase}…`;
      return;
    }

    const percent = Math.min(100, Math.round((done / total) * 100));
    status.textContent = `${phase} ${percent}%`;
  },
});

```

When a file doesn’t provide a phase total, `total` is `null`. In that case, the example displays only the phase name.

Document Authoring reports progress up to about 10 times per second. A small spreadsheet might open without progress reports. Show a loading state when the import starts, not when `onProgress` first runs.

## Cancel an import

Pass an `AbortSignal` to enable cancellation. A canceled import rejects and never returns a partial spreadsheet:

```js

const controller = new AbortController();
cancelButton.addEventListener('click', () => controller.abort());

const spreadsheet = await system.importSpreadsheet(file, {
  fileName: file.name,
  abortSignal: controller.signal,
});

```

Cancellation is best effort. After the method returns, check `controller.signal.aborted` and discard the result if it’s `true`.

## Open documents and spreadsheets from one file picker

If one file picker accepts documents and spreadsheets, first call [`detectFileKind()`](https://www.nutrient.io/api/document-authoring/types/docauthsystem/#detectfilekind). Then call the matching import method and create its editor:

```js

const target = document.getElementById('editor');
const kind = await system.detectFileKind(file);

if (kind === 'spreadsheet') {
  const spreadsheet = await system.importSpreadsheet(file, { fileName: file.name });
  await system.createSpreadsheetEditor(target, { spreadsheet });
} else {
  const importedDocument = await system.import(file, { fileName: file.name });
  await system.createEditor(target, { document: importedDocument });
}

```

`detectFileKind()` returns `'spreadsheet'` for XLSX and SheetJSON files. It returns `'document'` for all other files, including files neither importer can open. The method reads the entire file into memory, so pass a `File` or `Blob`, and not a `Response` that you plan to import afterward.

## Create a blank spreadsheet

Use [`createSpreadsheetFromPlaintext()`](https://www.nutrient.io/api/document-authoring/types/docauthsystem/#createspreadsheetfromplaintext) to create a spreadsheet with one empty sheet:

```js

const spreadsheet = await system.createSpreadsheetFromPlaintext('');

```

Document Authoring puts the supplied text in cell A1 without splitting it into rows or columns. This method can’t import CSV or tab-separated data.

## Learn more

**[Save and export](https://www.nutrient.io/guides/document-authoring/spreadsheets/save-and-export.md)**\
Store spreadsheets as SheetJSON, and export XLSX and PDF.

**[Spreadsheets in Node.js](https://www.nutrient.io/guides/document-authoring/spreadsheets/nodejs.md)**\
Import and convert spreadsheets on a server.
---

## Related pages

- [Spreadsheets](/guides/document-authoring/spreadsheets.md)
- [Spreadsheet editor](/guides/document-authoring/spreadsheets/editor.md)
- [Spreadsheet formulas](/guides/document-authoring/spreadsheets/formulas.md)
- [Get started with spreadsheets](/guides/document-authoring/spreadsheets/getting-started.md)
- [Spreadsheets in Node.js](/guides/document-authoring/spreadsheets/nodejs.md)
- [Save and export spreadsheets](/guides/document-authoring/spreadsheets/save-and-export.md)
- [Spreadsheet JSON support with SheetJSON](/guides/document-authoring/spreadsheets/sheetjson.md)