Import and load spreadsheets

Use importSpreadsheet() to open an XLSX file. Use loadSpreadsheet() to reopen a spreadsheet saved as SheetJSON. Both methods return a 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 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:

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:

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

Load a saved spreadsheet

Use loadSpreadsheet() to reopen a spreadsheet saved with saveSpreadsheet(). This method reads SheetJSON only:

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:

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:

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(). Then call the matching import method and create its editor:

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() to create a spreadsheet with one empty sheet:

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
Store spreadsheets as SheetJSON, and export XLSX and PDF.

Spreadsheets in Node.js
Import and convert spreadsheets on a server.