JavaScript API

Introduction

phpxlsx Premium licenses include jsdocumentsxlsx, a JavaScript library to work with XLSX spreadsheets using nodejs, web browsers, and other JavaScript projects.

Developed with TypeScript, jsdocumentsxlsx is the best and most complete JavaScript library to generate XLSX spreadsheets from scratch and using XLSX templates.

Among its many features, the following can be highlighted:

Add new contents.
Apply styles.
Replace contents in templates.
Modify layouts.
Set settings.
RTL settings.
Transform measuring units.
...

Compatibility and included bundles

To achieve the best possible compatibility with nodejs and web browsers, jsdocumentsxlsx uses TypeScript with the following compiler options:

"target": "es2015",
"module": "node16",
"lib": ["es2017", "DOM"],
"moduleResolution": "node16",
"strict": true,

The following formats are included in the package:

CommonJS: cjs
ESM: mjs
IIFE: iife.js

in addition to map files and TypeScript type information.

To use jsdocumentsxlsx it's not mandatory to develop with TypeScript, but it's recommended. Vanilla JavaScript can also be used with jsdocumentsxlsx.

New spreadsheets

Creating a new XLSX is as simple as instance the CreateXlsx class, add new contents using the available methods and save the document.

The save method returns a Promise object.

For example, to add a cell using TypeScript with nodejs:

import { CreateXlsx, OptionsCellContents } from "build";
import * as fs from "fs";

const xlsx = new CreateXlsx();

let content: OptionsCellContents = {
    text: "Cell content",
};
xlsx.addCell(content, "A1");

xlsx.save().then(contents => {
    fs.writeFileSync("spreadsheet.xlsx", Buffer.from(contents));
});

fs.writeFileSync is available in nodejs File system.

The same sample using Vanilla JavaScript with nodejs and the ESM module:

import { CreateXlsx, OptionsCellContents } from "build/dist/jsdocumentsxlsx.mjs";
import * as fs from "fs";

const xlsx = new CreateXlsx();

let content: OptionsCellContents = {
    text: "Cell content",
};
xlsx.addCell(content, "A1");

xlsx.save().then(contents => {
    fs.writeFileSync("spreadsheet.xlsx", Buffer.from(contents));
});

The same sample using Vanilla JavaScript with nodejs and CommonJS:

"use strict";

var jsdocumentsxlsx = require("build");
var fs = require("fs");
var xlsx = new jsdocumentsxlsx.CreateXlsx();

xlsx.addCell({ text: "Cell content" }, "A1");

xlsx.save().then(function (contents) {
    fs.writeFileSync("spreadsheet.xlsx", Buffer.from(contents));
});

The following sample (generateXlsx.js) generates and downloads a new XLSX in a web browser with the ESM module:

import { CreateXlsx } from "./jsdocumentsxlsx.mjs";

const xlsx = new CreateXlsx();

xlsx.addCell({ text: "Cell content" }, "A1");

xlsx.save().then(contents => {
    saveAs(new Blob([contents]), "spreadsheet.xlsx");
});

<script src="//cdnjs.cloudflare.com/ajax/libs/FileSaver.js/2.0.4/FileSaver.min.js"></script>
<script src="./generateXlsx.js" type="module"></script>

saveAs, available in FileSaver.js is the easiest way to download the document in a web browser.

The same sample using the IIFE format:

const xlsx = new jsdocumentsxlsx.CreateXlsx();

xlsx.addCell({ text: "Cell content" }, "A1");

xlsx.save().then(contents => {
    saveAs(new Blob([contents]), "output.xlsx");
});

<script src="//cdnjs.cloudflare.com/ajax/libs/FileSaver.js/2.0.4/FileSaver.min.js"></script>
<script src="./jsdocumentsxlsx.iife.js"></script>
<script src="./generateXlsx.js"></script>

Template documents

The openTemplate method is used to open a XLSX template and replace, remove and add new contents.

The openTemplate method returns a Promise object.

For example, to open a XLSX template and replace text variables in the document target using TypeScript with nodejs:

import { CreateXlsx } from "build";
import * as fs from "fs";

const xlsxTemplate = fs.readFileSync("template.xlsx").buffer;

const xlsx = new CreateXlsx();
// load the template
xlsx.openTemplate(xlsxTemplate).then(xlsx => {
    const variables = new Map<string, string>();
    variables.set("VAR_1", "New value 1");
    variables.set("VAR_2", "New value 2");
    xlsx.replaceVariableText(variables, "sheets");

    // save the XLSX
    xlsx.save().then(contents => {
        fs.writeFileSync("spreadsheet.xlsx", Buffer.from(contents));
    });
});

fs.readFileSync is available in nodejs File system.

The same sample using Vanilla JavaScript with nodejs and the ESM module:

import { CreateXlsx } from "build/dist/jsdocumentsxlsx.mjs";
import * as fs from "fs";

const xlsxTemplate = fs.readFileSync("template.xlsx").buffer;

const xlsx = new CreateXlsx();
// load the template
xlsx.openTemplate(xlsxTemplate).then(xlsx => {
    const variables = new Map();
    variables.set("VAR_1", "New value 1");
    variables.set("VAR_2", "New value 2");
    xlsx.replaceVariableText(variables, "sheets");

    // save the XLSX
    xlsx.save().then(contents => {
        fs.writeFileSync("spreadsheet.xlsx", Buffer.from(contents));
    });
});

The following sample (generateXlsxFromTemplate.js) opens an XLSX template, generates and downloads a new XLSX in a web browser:

import { CreateXlsx } from "./jsdocumentsxlsx.mjs";

const xlsxTemplate = new FileReader();
// XLSX file as blob. For example from "const files = event.currentTarget.files;"
xlsxTemplate.readAsArrayBuffer(files[0]);

xlsxTemplate.onload = function() {
    const xlsx = new CreateXlsx();
    // load the template
    xlsx.openTemplate(xlsxTemplate.result).then(xlsx => {
        const variables = new Map();
        variables.set("VAR_1", "New value 1");
        variables.set("VAR_2", "New value 2");
        xlsx.replaceVariableText(variables, "sheets");

        // save the XLSX
        xlsx.save().then(contents => {
            saveAs(new Blob([contents]), "output_template.xlsx");
        });
    });
};

Using FileReader API is the easiest approach to generate an ArrayBuffer from a local file (a File or a Blob object) in a web browser.

In addition to replacing contents, jsdocumentsxlsx includes methods to delete contents, get existing variables, and customise the symbols used to define variables.

External files

External files such as images, XLSX templates and XLSX outputs in jsdocumentsxlsx use ArrayBuffer objects for maximum compatibility. Any JavaScript function or library compatible with ArrayBuffer can be used.

For example, to load an image using TypeScript with nodejs:

import { CreateXlsx, OptionsImage } from "build";
import * as fs from "fs";

const xlsx = new CreateXlsx();

const image = fs.readFileSync("image.jpg").buffer;

const optionsImage: OptionsImage = {
    colSize: 3,
    rowSize: 7,
};
xlsx.addImage(image, "A1", optionsImage);

The same sample using Vanilla JavaScript with nodejs and the ESM module:

import { CreateXlsx } from "build/dist/jsdocumentsxlsx.mjs";
import * as fs from "fs";

const xlsx = new CreateXlsx();

const image = fs.readFileSync("image.jpg").buffer;

const optionsImage = {
    colSize: 3,
    rowSize: 7,
};
xlsx.addImage(image, "A1", optionsImage);

Using the FileReader API is the easiest approach to generate an ArrayBuffer from a local file (a File or a Blob object) in a web browser:

import { CreateXlsx } from "build/dist/jsdocumentsxlsx.mjs";

const xlsx = new CreateXlsx();

const image = new FileReader();
// XLSX file as blob. For example from "const files = event.currentTarget.files;"
image.readAsArrayBuffer(files[0]);

image.onload = function() {
    const optionsImage = {
        colSize: 3,
        rowSize: 7,
    };

    xlsx.addImage(image.result, "A1", optionsImage);

    xlsx.save().then(contents => {
        saveAs(new Blob([contents]), "output_image.xlsx");
    });
}

The Fetch API can be used to fetch external files.

More information

On JavaScript API are available the documentation pages, with all methods, options and samples of use. In addition to this documentation, phpxlsx Premium packages include many samples to illustrate how to use all methods.

jsdocumentsxlsx has an official website at jsdocuments.com.