SheetJS

The SheetJS Community Edition offers battle-tested open-source solutions for extracting useful data from almost any complex spreadsheet and generating new spreadsheets that will work with legacy and modern software alike.

SheetJS Pro offers solutions beyond data processing: Edit complex templates with ease; let out your inner Picasso with styling; make custom sheets with images/graphs/PivotTables; evaluate formula expressions and port calculations to web apps; automate common spreadsheet tasks, and much more!

Browser Test and Support Matrix

Supported File Formats

Table of Contents

Getting Started

Installation

Standalone Browser Scripts

The complete browser standalone build is saved to dist/xlsx.full.min.js and can be directly added to a page with a script tag:

<script lang="javascript" src="dist/xlsx.full.min.js"></script>

<script src="https://unpkg.com/xlsx/dist/xlsx.full.min.js"></script>

With bower:

$ bower install js-xlsx

ECMAScript Modules

The ECMAScript Module build is saved to xlsx.mjs and can be directly added to a page with a script tag using type=module:

<script type="module">
import { read, writeFileXLSX } from "./xlsx.mjs";

/* load the codepage support library for extended support with older formats  */
import { set_cptable } from "./xlsx.mjs";
import * as cptable from './dist/cpexcel.full.mjs';
set_cptable(cptable);
</script>

The npm package also exposes the module with the module parameter, supported in Angular and other projects:

import { read, writeFileXLSX } from "xlsx";

/* load the codepage support library for extended support with older formats  */
import { set_cptable } from "xlsx";
import * as cptable from 'xlsx/dist/cpexcel.full.mjs';
set_cptable(cptable);

Deno

xlsx.mjs can be imported in Deno. It is available from unpkg:

// @deno-types="https://unpkg.com/xlsx/types/index.d.ts"
import * as XLSX from 'https://unpkg.com/xlsx/xlsx.mjs';

/* load the codepage support library for extended support with older formats  */
import * as cptable from 'https://unpkg.com/xlsx/dist/cpexcel.full.mjs';
XLSX.set_cptable(cptable);

NodeJS

With npm:

$ npm install xlsx

By default, the module supports require:

var XLSX = require("xlsx");

The module also ships with xlsx.mjs for use with import:

import * as XLSX from 'xlsx/xlsx.mjs';

/* load 'fs' for readFile and writeFile support */
import * as fs from 'fs';
XLSX.set_fs(fs);

/* load 'stream' for stream support */
import { Readable } from 'stream';
XLSX.stream.set_readable(Readable);

/* load the codepage support library for extended support with older formats  */
import * as cpexcel from 'xlsx/dist/cpexcel.full.mjs';
XLSX.set_cptable(cpexcel);

Photoshop and InDesign

dist/xlsx.extendscript.js is an ExtendScript build for Photoshop and InDesign that is included in the npm package. It can be directly referenced with a #include directive:

#include "xlsx.extendscript.js"

<!-- add the shim first -->
<script type="text/javascript" src="shim.min.js"></script>
<!-- after the shim is referenced, add the library -->
<script type="text/javascript" src="xlsx.full.min.js"></script>

Usage

Most scenarios involving spreadsheets and data can be broken into 5 parts:

1. Acquire Data: Data may be stored anywhere: local or remote files, databases, HTML TABLE, or even generated programmatically in the web browser.

2. Extract Data: For spreadsheet files, this involves parsing raw bytes to read the cell data. For general JS data, this involves reshaping the data.

3. Process Data: From generating summary statistics to cleaning data records, this step is the heart of the problem.

4. Package Data: This can involve making a new spreadsheet or serializing with JSON.stringify or writing XML or simply flattening data for UI tools.

5. Release Data: Spreadsheet files can be uploaded to a server or written locally. Data can be presented to users in an HTML TABLE or data grid.

A common problem involves generating a valid spreadsheet export from data stored in an HTML table. In this example, an HTML TABLE on the page will be scraped, a row will be added to the bottom with the date of the report, and a new file will be generated and downloaded locally. XLSX.writeFile takes care of packaging the data and attempting a local download:

// Acquire Data (reference to the HTML table)
var table_elt = document.getElementById("my-table-id");

// Extract Data (create a workbook object from the table)
var workbook = XLSX.utils.table_to_book(table_elt);

// Process Data (add a new row)
var ws = workbook.Sheets["Sheet1"];
XLSX.utils.sheet_add_aoa(ws, [["Created "+new Date().toISOString()]], {origin:-1});

// Package and Release Data (`writeFile` tries to write and save an XLSB file)
XLSX.writeFile(workbook, "Report.xlsb");

This library tries to simplify steps 2 and 4 with functions to extract useful data from spreadsheet files (read / readFile) and generate new spreadsheet files from data (write / writeFile). Additional utility functions like table_to_book work with other common data sources like HTML tables.

This documentation and various demo projects cover a number of common scenarios and approaches for steps 1 and 5.

Utility functions help with step 3.

"Acquiring and Extracting Data" describes solutions for common data import scenarios.

"Packaging and Releasing Data" describes solutions for common data export scenarios.

"Processing Data" describes solutions for common workbook processing and manipulation scenarios.

"Utility Functions" details utility functions for translating JSON Arrays and other common JS structures into worksheet objects.

The Zen of SheetJS

Data processing should fit in any workflow

The library does not impose a separate lifecycle. It fits nicely in websites and apps built using any framework. The plain JS data objects play nice with Web Workers and future APIs.

JavaScript is a powerful language for data processing

The "Common Spreadsheet Format" is a simple object representation of the core concepts of a workbook. The various functions in the library provide low-level tools for working with the object.

For friendly JS processing, there are utility functions for converting parts of a worksheet to/from an Array of Arrays. The following example combines powerful JS Array methods with a network request library to download data, select the information we want and create a workbook file:

{
  "id": { /* (data omitted) */ },
  "name": {
    "first": "John",          // <-- first name
    "last": "Adams"           // <-- last name
  },
  "bio": {
    "birthday": "1735-10-19", // <-- birthday
    "gender": "M"
  },
  "terms": [
    { "type": "viceprez", /* (other fields omitted) */ },
    { "type": "viceprez", /* (other fields omitted) */ },
    { "type": "prez", /* (other fields omitted) */ } // <-- look for "prez"
  ]
}

const prez = raw_data.filter(row => row.terms.some(term => term.type === "prez"));

const rows = prez.map(row => ({
  name: row.name.first + " " + row.name.last,
  birthday: row.bio.birthday
}));

[
  { name: "George Washington", birthday: "1732-02-22" },
  { name: "John Adams", birthday: "1735-10-19" },
  // ... one row per President
]

const worksheet = XLSX.utils.json_to_sheet(rows);

const workbook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(workbook, worksheet, "Dates");

XLSX.utils.sheet_add_aoa(worksheet, [["Name", "Birthday"]], { origin: "A1" });

worksheet["!cols"] = [ { wch: 10 } ]; // set column A width to 10 characters

const max_width = rows.reduce((w, r) => Math.max(w, r.name.length), 10);
worksheet["!cols"] = [ { wch: max_width } ];

XLSX.writeFile(workbook, "Presidents.xlsx");

// Uncomment the next line for use in NodeJS:
// const XLSX = require("xlsx"), axios = require("axios");

(async() => {
  /* fetch JSON data and parse */
  const url = "https://theunitedstates.io/congress-legislators/executive.json";
  const raw_data = (await axios(url, {responseType: "json"})).data;

  /* filter for the Presidents */
  const prez = raw_data.filter(row => row.terms.some(term => term.type === "prez"));

  /* flatten objects */
  const rows = prez.map(row => ({
    name: row.name.first + " " + row.name.last,
    birthday: row.bio.birthday
  }));

  /* generate worksheet and workbook */
  const worksheet = XLSX.utils.json_to_sheet(rows);
  const workbook = XLSX.utils.book_new();
  XLSX.utils.book_append_sheet(workbook, worksheet, "Dates");

  /* fix headers */
  XLSX.utils.sheet_add_aoa(worksheet, [["Name", "Birthday"]], { origin: "A1" });

  /* calculate column width */
  const max_width = rows.reduce((w, r) => Math.max(w, r.name.length), 10);
  worksheet["!cols"] = [ { wch: max_width } ];

  /* create an XLSX file and try to save to Presidents.xlsx */
  XLSX.writeFile(workbook, "Presidents.xlsx");
})();

<script src="https://unpkg.com/xlsx/dist/xlsx.full.min.js"></script>
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
<script src="snippet.js"></script>

File formats are implementation details

The parser covers a wide gamut of common spreadsheet file formats to ensure that "HTML-saved-as-XLS" files work as well as actual XLS or XLSX files.

The writer supports a number of common output formats for broad compatibility with the data ecosystem.

To the greatest extent possible, data processing code should not have to worry about the specific file formats involved.

JS Ecosystem Demos

The demos directory includes sample projects for:

Frameworks and APIs

• angularjs
• angular and ionic
• knockout
• meteor
• react and react-native
• vue 2.x and weex
• XMLHttpRequest and fetch
• nodejs server
• databases and key/value stores
• typed arrays and math

Bundlers and Tooling

• browserify
• fusebox
• parcel
• requirejs
• rollup
• systemjs
• typescript
• webpack 2.x

Platforms and Integrations

• deno
• electron application
• nw.js application
• Chrome / Chromium extensions
• Download a Google Sheet locally
• Adobe ExtendScript
• Headless Browsers
• canvas-datagrid
• x-spreadsheet
• react-data-grid
• vue3-table-light
• Swift JSC and other engines
• "serverless" functions
• internet explorer

Other examples are included in the showcase.

https://sheetjs.com/demos/modify.html shows a complete example of reading, modifying, and writing files.

https://github.com/SheetJS/sheetjs/blob/HEAD/bin/xlsx.njs is the command-line tool included with node installations, reading spreadsheet files and exporting the contents in various formats.

Acquiring and Extracting Data

Parsing Workbooks

API

Extract data from spreadsheet bytes

var workbook = XLSX.read(data, opts);

The read method can extract data from spreadsheet bytes stored in a JS string, "binary string", NodeJS buffer or typed array (Uint8Array or ArrayBuffer).

Read spreadsheet bytes from a local file and extract data

var workbook = XLSX.readFile(filename, opts);

The readFile method attempts to read a spreadsheet file at the supplied path. Browsers generally do not allow reading files in this way (it is deemed a security risk), and attempts to read files in this way will throw an error.

The second opts argument is optional. "Parsing Options" covers the supported properties and behaviors.

Examples

Here are a few common scenarios (click on each subtitle to see the code):

var XLSX = require("xlsx");

var workbook = XLSX.readFile("test.xlsx");

import { readFileSync } from "fs";
import { read } from "xlsx/xlsx.mjs";

const buf = readFileSync("test.xlsx");
/* buf is a Buffer */
const workbook = read(buf);

// @deno-types="https://deno.land/x/sheetjs/types/index.d.ts"
import * as XLSX from 'https://deno.land/x/sheetjs/xlsx.mjs'

const workbook = XLSX.readFile("test.xlsx");

// XLSX is a global from the standalone script

async function handleDropAsync(e) {
  e.stopPropagation(); e.preventDefault();
  const f = e.dataTransfer.files[0];
  /* f is a File */
  const data = await f.arrayBuffer();
  /* data is an ArrayBuffer */
  const workbook = XLSX.read(data);

  /* DO SOMETHING WITH workbook HERE */
}
drop_dom_element.addEventListener("drop", handleDropAsync, false);

function handleDrop(e) {
  e.stopPropagation(); e.preventDefault();
  var f = e.dataTransfer.files[0];
  /* f is a File */
  var reader = new FileReader();
  reader.onload = function(e) {
    var data = e.target.result;
    /* reader.readAsArrayBuffer(file) -> data will be an ArrayBuffer */
    var workbook = XLSX.read(data);

    /* DO SOMETHING WITH workbook HERE */
  };
  reader.readAsArrayBuffer(f);
}
drop_dom_element.addEventListener("drop", handleDrop, false);

<input type="file" id="input_dom_element">

// XLSX is a global from the standalone script

async function handleFileAsync(e) {
  const file = e.target.files[0];
  const data = await file.arrayBuffer();
  /* data is an ArrayBuffer */
  const workbook = XLSX.read(data);

  /* DO SOMETHING WITH workbook HERE */
}
input_dom_element.addEventListener("change", handleFileAsync, false);

function handleFile(e) {
  var file = e.target.files[0];
  var reader = new FileReader();
  reader.onload = function(e) {
    var data = e.target.result;
    /* reader.readAsArrayBuffer(file) -> data will be an ArrayBuffer */
    var workbook = XLSX.read(e.target.result);

    /* DO SOMETHING WITH workbook HERE */
  };
  reader.readAsArrayBuffer(file);
}
input_dom_element.addEventListener("change", handleFile, false);

// XLSX is a global from the standalone script

(async() => {
  const url = "http://oss.sheetjs.com/test_files/formula_stress_test.xlsx";
  const data = await (await fetch(url)).arrayBuffer();
  /* data is an ArrayBuffer */
  const workbook = XLSX.read(data);

  /* DO SOMETHING WITH workbook HERE */
})();

var url = "http://oss.sheetjs.com/test_files/formula_stress_test.xlsx";

/* set up async GET request */
var req = new XMLHttpRequest();
req.open("GET", url, true);
req.responseType = "arraybuffer";

req.onload = function(e) {
  var workbook = XLSX.read(req.response);

  /* DO SOMETHING WITH workbook HERE */
};

req.send();

#include "xlsx.extendscript.js"

/* Read test.xlsx from the Documents folder */
var workbook = XLSX.readFile(Folder.myDocuments + "/test.xlsx");

/* From the renderer process */
var XLSX = require("xlsx");

var workbook = XLSX.readFile(path);

import XLSX from "xlsx";
import { FileSystem } from "react-native-file-access";

const b64 = await FileSystem.readFile(path, "base64");
/* b64 is a base64 string */
const workbook = XLSX.read(b64, {type: "base64"});

import XLSX from "xlsx";
import { readFile } from "react-native-fs";

const bstr = await readFile(path, "ascii");
/* bstr is a binary string */
const workbook = XLSX.read(bstr, {type: "binary"});

const XLSX = require("xlsx");
const http = require("http");
const formidable = require("formidable");

const server = http.createServer((req, res) => {
  const form = new formidable.IncomingForm();
  form.parse(req, (err, fields, files) => {
    /* grab the first file */
    const f = Object.entries(files)[0][1];
    const path = f.filepath;
    const workbook = XLSX.readFile(path);

    /* DO SOMETHING WITH workbook HERE */
  });
}).listen(process.env.PORT || 7262);

const XLSX = require("xlsx");

const data = await (await fetch(url)).arrayBuffer();
/* data is an ArrayBuffer */
const workbook = XLSX.read(data);

var XLSX = require("xlsx");
var request = require("request");

request({url: url, encoding: null}, function(err, resp, body) {
  var workbook = XLSX.read(body);

  /* DO SOMETHING WITH workbook HERE */
});

const XLSX = require("xlsx");
const axios = require("axios");

(async() => {
  const res = await axios.get(url, {responseType: "arraybuffer"});
  /* res.data is a Buffer */
  const workbook = XLSX.read(res.data);

  /* DO SOMETHING WITH workbook HERE */
})();

const XLSX = require("xlsx");
const { net } = require("electron");

const req = net.request(url);
req.on("response", (res) => {
  const bufs = []; // this array will collect all of the buffers
  res.on("data", (chunk) => { bufs.push(chunk); });
  res.on("end", () => {
    const workbook = XLSX.read(Buffer.concat(bufs));

    /* DO SOMETHING WITH workbook HERE */
  });
});
req.end();

var fs = require("fs");
var XLSX = require("xlsx");

function process_RS(stream, cb) {
  var buffers = [];
  stream.on("data", function(data) { buffers.push(data); });
  stream.on("end", function() {
    var buffer = Buffer.concat(buffers);
    var workbook = XLSX.read(buffer, {type:"buffer"});

    /* DO SOMETHING WITH workbook IN THE CALLBACK */
    cb(workbook);
  });
}

// XLSX is a global from the standalone script

async function process_RS(stream) {
  /* collect data */
  const buffers = [];
  const reader = stream.getReader();
  for(;;) {
    const res = await reader.read();
    if(res.value) buffers.push(res.value);
    if(res.done) break;
  }

  /* concat */
  const out = new Uint8Array(buffers.reduce((acc, v) => acc + v.length, 0));

  let off = 0;
  for(const u8 of arr) {
    out.set(u8, off);
    off += u8.length;
  }

  return out;
}

const data = await process_RS(stream);
/* data is Uint8Array */
const workbook = XLSX.read(data);

More detailed examples are covered in the included demos

Processing JSON and JS Data

JSON and JS data tend to represent single worksheets. This section will use a few utility functions to generate workbooks.

Create a new Workbook

var workbook = XLSX.utils.book_new();

The book_new utility function creates an empty workbook with no worksheets.

Spreadsheet software generally require at least one worksheet and enforce the requirement in the user interface. This library enforces the requirement at write time, throwing errors if an empty workbook is passed to write functions.

API

Create a worksheet from an array of arrays of JS values

var worksheet = XLSX.utils.aoa_to_sheet(aoa, opts);

The aoa_to_sheet utility function walks an "array of arrays" in row-major order, generating a worksheet object. The following snippet generates a sheet with cell A1 set to the string A1, cell B1 set to B1, etc:

var worksheet = XLSX.utils.aoa_to_sheet([
  ["A1", "B1", "C1"],
  ["A2", "B2", "C2"],
  ["A3", "B3", "C3"]
]);

"Array of Arrays Input" describes the function and the optional opts argument in more detail.

Create a worksheet from an array of JS objects

var worksheet = XLSX.utils.json_to_sheet(jsa, opts);

The json_to_sheet utility function walks an array of JS objects in order, generating a worksheet object. By default, it will generate a header row and one row per object in the array. The optional opts argument has settings to control the column order and header output.

"Array of Objects Input" describes the function and the optional opts argument in more detail.

Examples

"Zen of SheetJS" contains a detailed example "Get Data from a JSON Endpoint and Generate a Workbook"

x-spreadsheet is an interactive data grid for previewing and modifying structured data in the web browser. The xspreadsheet demo includes a sample script with the xtos function for converting from x-spreadsheet data object to a workbook. https://oss.sheetjs.com/sheetjs/x-spreadsheet is a live demo.

const XLSX = require("xlsx");
const tf = require('@tensorflow/tfjs');

/* suppose xs and ys are vectors (1D tensors) -> tfarr will be a typed array */
const tfdata = tf.stack([xs, ys]).transpose();
const shape = tfdata.shape;
const tfarr = tfdata.dataSync();

/* construct the array of arrays */
const aoa = [];
for(let j = 0; j < shape[0]; ++j) {
  aoa[j] = [];
  for(let i = 0; i < shape[1]; ++i) aoa[j][i] = tfarr[j * shape[1] + i];
}
/* add headers to the top */
aoa.unshift(["x", "y"]);

/* generate worksheet */
const worksheet = XLSX.utils.aoa_to_sheet(aoa);

Processing HTML Tables

API

Create a worksheet by scraping an HTML TABLE in the page

var worksheet = XLSX.utils.table_to_sheet(dom_element, opts);

The table_to_sheet utility function takes a DOM TABLE element and iterates through the rows to generate a worksheet. The opts argument is optional. "HTML Table Input" describes the function in more detail.

Create a workbook by scraping an HTML TABLE in the page

var workbook = XLSX.utils.table_to_book(dom_element, opts);

The table_to_book utility function follows the same logic as table_to_sheet. After generating a worksheet, it creates a blank workbook and appends the spreadsheet.

The options argument supports the same options as table_to_sheet, with the addition of a sheet property to control the worksheet name. If the property is missing or no options are specified, the default name Sheet1 is used.

Examples

Here are a few common scenarios (click on each subtitle to see the code):

<!-- include the standalone script and shim.  this uses the UNPKG CDN -->
<script src="https://unpkg.com/xlsx/dist/shim.min.js"></script>
<script src="https://unpkg.com/xlsx/dist/xlsx.full.min.js"></script>

<!-- example table with id attribute -->
<table id="tableau">
  <tr><td>Sheet</td><td>JS</td></tr>
  <tr><td>12345</td><td>67</td></tr>
</table>

<!-- this block should appear after the table HTML and the standalone script -->
<script type="text/javascript">
  var workbook = XLSX.utils.table_to_book(document.getElementById("tableau"));

  /* DO SOMETHING WITH workbook HERE */
</script>

/* create new workbook */
var workbook = XLSX.utils.book_new();

/* convert table "table1" to worksheet named "Sheet1" */
var sheet1 = XLSX.utils.table_to_sheet(document.getElementById("table1"));
XLSX.utils.book_append_sheet(workbook, sheet1, "Sheet1");

/* convert table "table2" to worksheet named "Sheet2" */
var sheet2 = XLSX.utils.table_to_sheet(document.getElementById("table2"));
XLSX.utils.book_append_sheet(workbook, sheet2, "Sheet2");

/* workbook now has 2 worksheets */

var htmlstr = document.getElementById("tableau").outerHTML;
var workbook = XLSX.read(htmlstr, {type:"string"});

/* in the worker script */
chrome.runtime.onMessage.addListener(function(msg, sender, cb) {
  /* pass a message like { sheetjs: true } from the extension to scrape */
  if(!msg || !msg.sheetjs) return;
  /* create a new workbook */
  var workbook = XLSX.utils.book_new();
  /* loop through each table element */
  var tables = document.getElementsByTagName("table")
  for(var i = 0; i < tables.length; ++i) {
    var worksheet = XLSX.utils.table_to_sheet(tables[i]);
    XLSX.utils.book_append_sheet(workbook, worksheet, "Table" + i);
  }
  /* pass back to the extension */
  return cb(workbook);
});

const XLSX = require("xlsx");
const { readFileSync } = require("fs"), puppeteer = require("puppeteer");

const url = `https://sheetjs.com/demos/table`;

/* get the standalone build source (node_modules/xlsx/dist/xlsx.full.min.js) */
const lib = readFileSync(require.resolve("xlsx/dist/xlsx.full.min.js"), "utf8");

(async() => {
  /* start browser and go to web page */
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto(url, {waitUntil: "networkidle2"});

  /* inject library */
  await page.addScriptTag({content: lib});

  /* this function `s5s` will be called by the script below, receiving the Base64-encoded file */
  await page.exposeFunction("s5s", async(b64) => {
    const workbook = XLSX.read(b64, {type: "base64" });

    /* DO SOMETHING WITH workbook HERE */
  });

  /* generate XLSB file in webpage context and send back result */
  await page.addScriptTag({content: `
    /* call table_to_book on first table */
    var workbook = XLSX.utils.table_to_book(document.querySelector("TABLE"));

    /* generate XLSX file */
    var b64 = XLSX.write(workbook, {type: "base64", bookType: "xlsb"});

    /* call "s5s" hook exposed from the node process */
    window.s5s(b64);
  `});

  /* cleanup */
  await browser.close();
})();

var XLSX = require('xlsx');
var page = require('webpage').create();

/* this code will be run in the page */
var code = [ "function(){",
  /* call table_to_book on first table */
  "var wb = XLSX.utils.table_to_book(document.body.getElementsByTagName('table')[0]);",

  /* generate XLSB file and return binary string */
  "return XLSX.write(wb, {type: 'binary', bookType: 'xlsb'});",
"}" ].join("");

page.open('https://sheetjs.com/demos/table', function() {
  /* Load the browser script from the UNPKG CDN */
  page.includeJs("https://unpkg.com/xlsx/dist/xlsx.full.min.js", function() {
    /* The code will return an XLSB file encoded as binary string */
    var bin = page.evaluateJavaScript(code);

    var workbook = XLSX.read(bin, {type: "binary"});
    /* DO SOMETHING WITH workbook HERE */

    phantom.exit();
  });
});

const XLSX = require("xlsx");
const { readFileSync } = require("fs");
const { JSDOM } = require("jsdom");

/* obtain HTML string.  This example reads from test.html */
const html_str = fs.readFileSync("test.html", "utf8");
/* get first TABLE element */
const doc = new JSDOM(html_str).window.document.querySelector("table");
/* generate workbook */
const workbook = XLSX.utils.table_to_book(doc);

Processing Data

The "Common Spreadsheet Format" is a simple object representation of the core concepts of a workbook. The utility functions work with the object representation and are intended to handle common use cases.

Modifying Workbook Structure

API

Append a Worksheet to a Workbook

XLSX.utils.book_append_sheet(workbook, worksheet, sheet_name);

The book_append_sheet utility function appends a worksheet to the workbook. The third argument specifies the desired worksheet name. Multiple worksheets can be added to a workbook by calling the function multiple times. If the worksheet name is already used in the workbook, it will throw an error.

Append a Worksheet to a Workbook and find a unique name

var new_name = XLSX.utils.book_append_sheet(workbook, worksheet, name, true);

If the fourth argument is true, the function will start with the specified worksheet name. If the sheet name exists in the workbook, a new worksheet name will be chosen by finding the name stem and incrementing the counter:

XLSX.utils.book_append_sheet(workbook, sheetA, "Sheet2", true); // Sheet2
XLSX.utils.book_append_sheet(workbook, sheetB, "Sheet2", true); // Sheet3
XLSX.utils.book_append_sheet(workbook, sheetC, "Sheet2", true); // Sheet4
XLSX.utils.book_append_sheet(workbook, sheetD, "Sheet2", true); // Sheet5

List the Worksheet names in tab order

var wsnames = workbook.SheetNames;

The SheetNames property of the workbook object is a list of the worksheet names in "tab order". API functions will look at this array.

Replace a Worksheet in place

workbook.Sheets[sheet_name] = new_worksheet;

The Sheets property of the workbook object is an object whose keys are names and whose values are worksheet objects. By reassigning to a property of the Sheets object, the worksheet object can be changed without disrupting the rest of the worksheet structure.

Examples

var ws_name = "SheetJS";

/* Create worksheet */
var ws_data = [
  [ "S", "h", "e", "e", "t", "J", "S" ],
  [  1 ,  2 ,  3 ,  4 ,  5 ]
];
var ws = XLSX.utils.aoa_to_sheet(ws_data);

/* Add the worksheet to the workbook */
XLSX.utils.book_append_sheet(wb, ws, ws_name);

Modifying Cell Values

API

Modify a single cell value in a worksheet

XLSX.utils.sheet_add_aoa(worksheet, [[new_value]], { origin: address });

Modify multiple cell values in a worksheet

XLSX.utils.sheet_add_aoa(worksheet, aoa, opts);

The sheet_add_aoa utility function modifies cell values in a worksheet. The first argument is the worksheet object. The second argument is an array of arrays of values. The origin key of the third argument controls where cells will be written. The following snippet sets B3=1 and E5="abc":

XLSX.utils.sheet_add_aoa(worksheet, [
  [1],                             // <-- Write 1 to cell B3
  ,                                // <-- Do nothing in row 4
  [/*B5*/, /*C5*/, /*D5*/, "abc"]  // <-- Write "abc" to cell E5
], { origin: "B3" });

"Array of Arrays Input" describes the function and the optional opts argument in more detail.

Examples

XLSX.utils.sheet_add_aoa(worksheet, [
  ["first row after data", 1],
  ["second row after data", 2]
], { origin: -1 });

Modifying Other Worksheet / Workbook / Cell Properties

The "Common Spreadsheet Format" section describes the object structures in greater detail.

Packaging and Releasing Data

Writing Workbooks

API

Generate spreadsheet bytes (file) from data

var data = XLSX.write(workbook, opts);

The write method attempts to package data from the workbook into a file in memory. By default, XLSX files are generated, but that can be controlled with the bookType property of the opts argument. Based on the type option, the data can be stored as a "binary string", JS string, Uint8Array or Buffer.

The second opts argument is required. "Writing Options" covers the supported properties and behaviors.

Generate and attempt to save file

XLSX.writeFile(workbook, filename, opts);

The writeFile method packages the data and attempts to save the new file. The export file format is determined by the extension of filename (SheetJS.xlsx signals XLSX export, SheetJS.xlsb signals XLSB export, etc).

The writeFile method uses platform-specific APIs to initiate the file save. In NodeJS, fs.readFileSync can create a file. In the web browser, a download is attempted using the HTML5 download attribute, with fallbacks for IE.

Generate and attempt to save an XLSX file

XLSX.writeFileXLSX(workbook, filename, opts);

The writeFile method embeds a number of different export functions. This is great for developer experience but not amenable to tree shaking using the current developer tools. When only XLSX exports are needed, this method avoids referencing the other export functions.

The second opts argument is optional. "Writing Options" covers the supported properties and behaviors.

Examples

var XLSX = require("xlsx");

/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsb");

import { writeFileSync } from "fs";
import { write } from "xlsx/xlsx.mjs";

const buf = write(workbook, {type: "buffer", bookType: "xlsb"});
/* buf is a Buffer */
const workbook = writeFileSync("out.xlsb", buf);

// @deno-types="https://deno.land/x/sheetjs/types/index.d.ts"
import * as XLSX from 'https://deno.land/x/sheetjs/xlsx.mjs'

XLSX.writeFile(workbook, "test.xlsx");

#include "xlsx.extendscript.js"

/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsx");
/* at this point, out.xlsx is a file that you can distribute */

/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsb");
/* at this point, out.xlsb will have been downloaded */

/* bookType can be any supported output type */
var wopts = { bookType:"xlsx", bookSST:false, type:"array" };

var wbout = XLSX.write(workbook,wopts);

/* the saveAs call downloads a file on the local machine */
saveAs(new Blob([wbout],{type:"application/octet-stream"}), "test.xlsx");

Downloadify.create(id,{
  /* other options are required! read the downloadify docs for more info */
  filename: "test.xlsx",
  data: function() { return XLSX.write(wb, {bookType:"xlsx", type:"base64"}); },
  append: false,
  dataType: "base64"
});

/* in this example, send a base64 string to the server */
var wopts = { bookType:"xlsx", bookSST:false, type:"base64" };

var wbout = XLSX.write(workbook,wopts);

var req = new XMLHttpRequest();
req.open("POST", "/upload", true);
var formdata = new FormData();
formdata.append("file", "test.xlsx"); // <-- server expects `file` to hold name
formdata.append("data", wbout); // <-- `data` holds the base64-encoded data
req.send(formdata);

var XLSX = require('xlsx');
var fs = require('fs');

/* generate a binary string */
var bin = XLSX.write(workbook, { type:"binary", bookType: "xlsx" });
/* write to file */
fs.write("test.xlsx", bin, "wb");

The included demos cover mobile apps and other special deployments.

Writing Examples

• http://sheetjs.com/demos/table.html exporting an HTML table
• http://sheetjs.com/demos/writexlsx.html generates a simple file

Streaming Write

The streaming write functions are available in the XLSX.stream object. They take the same arguments as the normal write functions but return a NodeJS Readable Stream.

• XLSX.stream.to_csv is the streaming version of XLSX.utils.sheet_to_csv.
• XLSX.stream.to_html is the streaming version of XLSX.utils.sheet_to_html.
• XLSX.stream.to_json is the streaming version of XLSX.utils.sheet_to_json.

var output_file_name = "out.csv";
var stream = XLSX.stream.to_csv(worksheet);
stream.pipe(fs.createWriteStream(output_file_name));

/* to_json returns an object-mode stream */
var stream = XLSX.stream.to_json(worksheet, {raw:true});

/* the following stream converts JS objects to text via JSON.stringify */
var conv = new Transform({writableObjectMode:true});
conv._transform = function(obj, e, cb){ cb(null, JSON.stringify(obj) + "\n"); };

stream.pipe(conv); conv.pipe(process.stdout);

<meta charset="utf8">
<script src="xlsx.full.min.js"></script>
<script src="xlsx.zahl.js"></script>
<script>
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
  ["SheetJS", "<3","விரிதாள்"],
  [72,,"Arbeitsblätter"],
  [,62,"数据"],
  [true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL, compression: true});
</script>

var XLSX = require("./xlsx.flow");
var XLSX_ZAHL = require("./dist/xlsx.zahl");
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
  ["SheetJS", "<3","விரிதாள்"],
  [72,,"Arbeitsblätter"],
  [,62,"数据"],
  [true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL, compression: true});

import * as XLSX from './xlsx.mjs';
import XLSX_ZAHL from './dist/xlsx.zahl.mjs';

var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
  ["SheetJS", "<3","விரிதாள்"],
  [72,,"Arbeitsblätter"],
  [,62,"数据"],
  [true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textports.numbers", {numbers: XLSX_ZAHL, compression: true});

https://github.com/sheetjs/sheetaki pipes write streams to nodejs response.

Generating JSON and JS Data

JSON and JS data tend to represent single worksheets. The utility functions in this section work with single worksheets.

The "Common Spreadsheet Format" section describes the object structure in more detail. workbook.SheetNames is an ordered list of the worksheet names. workbook.Sheets is an object whose keys are sheet names and whose values are worksheet objects.

The "first worksheet" is stored at workbook.Sheets[workbook.SheetNames[0]].

API

Create an array of JS objects from a worksheet

var jsa = XLSX.utils.sheet_to_json(worksheet, opts);

Create an array of arrays of JS values from a worksheet

var aoa = XLSX.utils.sheet_to_json(worksheet, {...opts, header: 1});

The sheet_to_json utility function walks a workbook in row-major order, generating an array of objects. The second opts argument controls a number of export decisions including the type of values (JS values or formatted text). The "JSON" section describes the argument in more detail.

By default, sheet_to_json scans the first row and uses the values as headers. With the header: 1 option, the function exports an array of arrays of values.

Examples

x-spreadsheet is an interactive data grid for previewing and modifying structured data in the web browser. The xspreadsheet demo includes a sample script with the stox function for converting from a workbook to x-spreadsheet data object. https://oss.sheetjs.com/sheetjs/x-spreadsheet is a live demo.

import { useEffect, useState } from "react";
import DataGrid from "react-data-grid";
import { read, utils } from "xlsx";

const url = "https://oss.sheetjs.com/test_files/RkNumber.xls";

export default function App() {
  const [columns, setColumns] = useState([]);
  const [rows, setRows] = useState([]);
  useEffect(() => {(async () => {
    const wb = read(await (await fetch(url)).arrayBuffer(), { WTF: 1 });

    /* use sheet_to_json with header: 1 to generate an array of arrays */
    const data = utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]], { header: 1 });

    /* see react-data-grid docs to understand the shape of the expected data */
    setColumns(data[0].map((r) => ({ key: r, name: r })));
    setRows(data.slice(1).map((r) => r.reduce((acc, x, i) => {
      acc[data[0][i]] = x;
      return acc;
    }, {})));
  })(); });

  return <DataGrid columns={columns} rows={rows} />;
}

const XLSX = require("xlsx");
const tf = require('@tensorflow/tfjs');

const key = "age"; // this is the field we want to pull
const ages = XLSX.utils.sheet_to_json(worksheet).map(r => r[key]);
const tf_data = tf.tensor1d(ages);

const XLSX = require("xlsx");
const tf = require('@tensorflow/tfjs');

/* array of arrays of the data starting on the second row */
const aoa = XLSX.utils.sheet_to_json(worksheet, {header: 1}).slice(1);
/* dataset in the "correct orientation" */
const tf_dataset = tf.tensor2d(aoa).transpose();
/* pull out each dataset with a slice */
const tf_field0 = tf_dataset.slice([0,0], [1,tensor.shape[1]]).flatten();
const tf_field1 = tf_dataset.slice([1,0], [1,tensor.shape[1]]).flatten();

Generating HTML Tables

API

Generate HTML Table from Worksheet

var html = XLSX.utils.sheet_to_html(worksheet);

The sheet_to_html utility function generates HTML code based on the worksheet data. Each cell in the worksheet is mapped to a <TD> element. Merged cells in the worksheet are serialized by setting colspan and rowspan attributes.

Examples

The sheet_to_html utility function generates HTML code that can be added to any DOM element by setting the innerHTML:

var container = document.getElementById("tavolo");
container.innerHTML = XLSX.utils.sheet_to_html(worksheet);

Combining with fetch, constructing a site from a workbook is straightforward:

<body>
  <style>TABLE { border-collapse: collapse; } TD { border: 1px solid; }</style>
  <div id="tavolo"></div>
  <script src="https://unpkg.com/xlsx/dist/xlsx.full.min.js"></script>
  <script type="text/javascript">
(async() => {
  /* fetch and parse workbook -- see the fetch example for details */
  const workbook = XLSX.read(await (await fetch("sheetjs.xlsx")).arrayBuffer());

  let output = [];
  /* loop through the worksheet names in order */
  workbook.SheetNames.forEach(name => {

    /* generate HTML from the corresponding worksheets */
    const worksheet = workbook.Sheets[name];
    const html = XLSX.utils.sheet_to_html(worksheet);

    /* add a header with the title name followed by the table */
    output.push(`<H3>${name}</H3>${html}`);
  });
  /* write to the DOM at the end */
  tavolo.innerHTML = output.join("\n");
})();
  </script>
</body>

function Tabeller(props) {
  /* the workbook object is the state */
  const [workbook, setWorkbook] = React.useState(XLSX.utils.book_new());

  /* fetch and update the workbook with an effect */
  React.useEffect(() => { (async() => {
    /* fetch and parse workbook -- see the fetch example for details */
    const wb = XLSX.read(await (await fetch("sheetjs.xlsx")).arrayBuffer());
    setWorkbook(wb);
  })(); });

  return workbook.SheetNames.map(name => (<>
    <h3>name</h3>
    <div dangerouslySetInnerHTML={{
      /* this __html mantra is needed to set the inner HTML */
      __html: XLSX.utils.sheet_to_html(workbook.Sheets[name])
    }} />
  </>));
}

import { read, utils } from 'xlsx';
import { reactive } from 'vue';

const S5SComponent = {
  mounted() { (async() => {
    /* fetch and parse workbook -- see the fetch example for details */
    const workbook = read(await (await fetch("sheetjs.xlsx")).arrayBuffer());
    /* loop through the worksheet names in order */
    workbook.SheetNames.forEach(name => {
      /* generate HTML from the corresponding worksheets */
      const html = utils.sheet_to_html(workbook.Sheets[name]);
      /* add to state */
      this.wb.wb.push({ name, html });
    });
  })(); },
  /* this state mantra is required for array updates to work */
  setup() { return { wb: reactive({ wb: [] }) }; },
  template: `
  <div v-for="ws in wb.wb" :key="ws.name">
    <h3>{{ ws.name }}</h3>
    <div v-html="ws.html"></div>
  </div>`
};

Generating Single-Worksheet Snapshots

The sheet_to_* functions accept a worksheet object.

API

Generate a CSV from a single worksheet

var csv = XLSX.utils.sheet_to_csv(worksheet, opts);

This snapshot is designed to replicate the "CSV UTF8 (.csv)" output type. "Delimiter-Separated Output" describes the function and the optional opts argument in more detail.

Generate "Text" from a single worksheet

var txt = XLSX.utils.sheet_to_txt(worksheet, opts);

This snapshot is designed to replicate the "UTF16 Text (.txt)" output type. "Delimiter-Separated Output" describes the function and the optional opts argument in more detail.

Generate a list of formulae from a single worksheet

var fmla = XLSX.utils.sheet_to_formulae(worksheet);

This snapshot generates an array of entries representing the embedded formulae. Array formulae are rendered in the form

Current Tags

• 0.18.5                                ...           latest (3 years ago)

108 Versions

• 0.18.5                                ...           3 years ago
• 0.18.4                                ...           3 years ago
• 0.18.3                                ...           3 years ago
• 0.18.2                                ...           3 years ago
• 0.18.1                                ...           3 years ago
• 0.18.0                                ...           3 years ago
• 0.17.5                                ...           3 years ago
• 0.17.4                                ...           3 years ago
• 0.17.3                                ...           3 years ago
• 0.17.2                                ...           3 years ago
• 0.17.1                                ...           3 years ago
• 0.17.0                                ...           4 years ago
• 0.16.9                                ...           4 years ago
• 0.16.8                                ...           4 years ago
• 0.16.7                                ...           4 years ago
• 0.16.6                                ...           4 years ago
• 0.16.5                                ...           4 years ago
• 0.16.4                                ...           4 years ago
• 0.16.3                                ...           4 years ago
• 0.16.2                                ...           4 years ago
• 0.16.1                                ...           5 years ago
• 0.16.0                                ...           5 years ago
• 0.15.6                                ...           5 years ago
• 0.15.5                                ...           5 years ago
• 0.15.4                                ...           5 years ago
• 0.15.3                                ...           5 years ago
• 0.15.2                                ...           5 years ago
• 0.15.1                                ...           5 years ago
• 0.15.0                                ...           5 years ago
• 0.14.5                                ...           5 years ago
• 0.14.4                                ...           5 years ago
• 0.14.3                                ...           6 years ago
• 0.14.2                                ...           6 years ago
• 0.14.1                                ...           6 years ago
• 0.14.0                                ...           6 years ago
• 0.13.5                                ...           6 years ago
• 0.13.4                                ...           6 years ago
• 0.13.3                                ...           6 years ago
• 0.13.2                                ...           6 years ago
• 0.13.1                                ...           6 years ago
• 0.13.0                                ...           7 years ago
• 0.12.13                                ...           7 years ago
• 0.12.12                                ...           7 years ago
• 0.12.11                                ...           7 years ago
• 0.12.10                                ...           7 years ago
• 0.12.9                                ...           7 years ago
• 0.12.8                                ...           7 years ago
• 0.12.7                                ...           7 years ago
• 0.12.6                                ...           7 years ago
• 0.12.5                                ...           7 years ago
• 0.12.4                                ...           7 years ago
• 0.12.3                                ...           7 years ago
• 0.12.2                                ...           7 years ago
• 0.12.1                                ...           7 years ago
• 0.12.0                                ...           7 years ago
• 0.11.19                                ...           7 years ago
• 0.11.18                                ...           7 years ago
• 0.11.17                                ...           7 years ago
• 0.11.16                                ...           7 years ago
• 0.11.15                                ...           7 years ago
• 0.11.14                                ...           7 years ago
• 0.11.13                                ...           7 years ago
• 0.11.12                                ...           7 years ago
• 0.11.11                                ...           7 years ago
• 0.11.10                                ...           7 years ago
• 0.11.9                                ...           7 years ago
• 0.11.8                                ...           7 years ago
• 0.11.7                                ...           7 years ago
• 0.11.6                                ...           7 years ago
• 0.11.5                                ...           7 years ago
• 0.11.4                                ...           7 years ago
• 0.11.3                                ...           7 years ago
• 0.11.2                                ...           7 years ago
• 0.11.1                                ...           7 years ago
• 0.11.0                                ...           7 years ago
• 0.10.9 [deprecated]           ...           7 years ago
• 0.10.8 [deprecated]           ...           7 years ago
• 0.10.7 [deprecated]           ...           7 years ago
• 0.10.6 [deprecated]           ...           7 years ago
• 0.10.5 [deprecated]           ...           7 years ago
• 0.10.3 [deprecated]           ...           8 years ago
• 0.10.1 [deprecated]           ...           8 years ago
• 0.10.0 [deprecated]           ...           8 years ago
• 0.9.13 [deprecated]           ...           8 years ago
• 0.9.12 [deprecated]           ...           8 years ago
• 0.9.11 [deprecated]           ...           8 years ago
• 0.9.10 [deprecated]           ...           8 years ago
• 0.9.9 [deprecated]           ...           8 years ago
• 0.9.8 [deprecated]           ...           8 years ago
• 0.9.6 [deprecated]           ...           8 years ago
• 0.9.4 [deprecated]           ...           8 years ago
• 0.9.3 [deprecated]           ...           8 years ago
• 0.9.2 [deprecated]           ...           8 years ago
• 0.9.0 [deprecated]           ...           8 years ago
• 0.8.8 [deprecated]           ...           8 years ago
• 0.8.0 [deprecated]           ...           10 years ago
• 0.7.12 [deprecated]           ...           10 years ago
• 0.7.0 [deprecated]           ...           11 years ago
• 0.6.1 [deprecated]           ...           11 years ago
• 0.6.0 [deprecated]           ...           11 years ago
• 0.5.17 [deprecated]           ...           11 years ago
• 0.5.8 [deprecated]           ...           11 years ago
• 0.5.7 [deprecated]           ...           11 years ago
• 0.5.6 [deprecated]           ...           11 years ago
• 0.5.0 [deprecated]           ...           11 years ago
• 0.4.3 [deprecated]           ...           11 years ago
• 0.3.10 [deprecated]           ...           11 years ago
• 0.3.3 [deprecated]           ...           11 years ago