API Reference

API Reference

Initialization

initWasm()

Initialize the WASM module. Must be called once before any other operation.

import { initWasm } from 'modern-xlsx';
await initWasm();

I/O Functions

readFile(path: string): Promise<Workbook>

Read an XLSX file from disk. Node.js / Bun / Deno only.

readBuffer(data: Uint8Array): Promise<Workbook>

Read an XLSX file from a buffer. Works in all environments.

writeBlob(wb: Workbook): Blob

Write a workbook to a Blob for browser downloads.

Workbook

Constructor

const wb = new Workbook();

Properties

Property	Type	Description
sheetNames	string[]	Names of all sheets
sheetCount	number	Number of sheets
dateSystem	'date1900' | 'date1904'	Date epoch system
styles	StylesData	Styles collection
namedRanges	DefinedNameData[]	Named ranges
docProperties	DocPropertiesData | null	Document metadata
workbookViews	WorkbookViewData[]	View settings

Methods

Method	Returns	Description
addSheet(name)	Worksheet	Add a new sheet
getSheet(name)	Worksheet | undefined	Get sheet by name
getSheetByIndex(i)	Worksheet | undefined	Get sheet by index
removeSheet(nameOrIndex)	boolean	Remove a sheet
createStyle()	StyleBuilder	Create a style builder
addNamedRange(name, value, sheetId?)	void	Add named range
getNamedRange(name)	DefinedNameData | undefined	Get named range
removeNamedRange(name)	boolean	Remove named range
getPrintTitles(sheet)	{ rows?, cols? } | null	Get print title config
setPrintTitles(sheet, opts)	void	Set repeating rows/columns for printing
getPrintArea(sheet)	string | null	Get print area
setPrintArea(sheet, area)	void	Set print area range
toBuffer()	Promise<Uint8Array>	Serialize to buffer
toFile(path)	Promise<void>	Write to file
toJSON()	WorkbookData	Get raw data

DocPropertiesData

All fields are string | null. Set via wb.docProperties = { ... }.

Field	XML Source	Description
title	dc:title	Document title
subject	dc:subject	Document subject
creator	dc:creator	Author
keywords	cp:keywords	Keyword tags
description	dc:description	Comments/description
lastModifiedBy	cp:lastModifiedBy	Last editor
created	dcterms:created	Creation timestamp
modified	dcterms:modified	Last modified timestamp
category	cp:category	Category
contentStatus	cp:contentStatus	Status (e.g. "Draft")
revision	cp:revision	Revision number
application	Application	Generating application name
company	Company	Company name
manager	Manager	Manager name
appVersion	AppVersion	Application version string
hyperlinkBase	HyperlinkBase	Default hyperlink base URL

Worksheet

Properties

Property	Type	Description
name	string	Sheet name (read/write)
rows	RowData[]	All rows
columns	ColumnInfo[]	Column definitions
mergeCells	string[]	Merge ranges
autoFilter	AutoFilterData | null	Auto filter config
frozenPane	FrozenPane | null	Frozen pane config
hyperlinks	HyperlinkData[]	Hyperlinks
validations	DataValidationData[]	Validations
comments	CommentData[]	Cell comments
pageSetup	PageSetupData | null	Page setup
pageMargins	PageMarginsData | null	Page margins
sheetProtection	SheetProtectionData | null	Protection
usedRange	string | null	Computed cell extent (e.g. "B2:D5") or null if empty
tabColor	string | null	Sheet tab RGB hex color (read/write)
tables	TableDefinitionData[]	Tables on this sheet
headerFooter	HeaderFooterData | null	Headers and footers
outlineProperties	OutlinePropertiesData | null	Outline summary position

Methods

Method	Returns	Description
cell(ref)	Cell	Get or create a cell
setColumnWidth(col, width)	void	Set column width
setRowHeight(row, height)	void	Set row height
setRowHidden(row, hidden)	void	Hide/show row
addMergeCell(range)	void	Add merge
removeMergeCell(range)	boolean	Remove merge
addHyperlink(ref, location, opts?)	void	Add link
removeHyperlink(ref)	boolean	Remove link
addValidation(ref, rule)	void	Add validation
removeValidation(ref)	boolean	Remove validation
addComment(ref, author, text)	void	Add comment
removeComment(ref)	boolean	Remove comment
getTable(name)	TableDefinitionData | undefined	Find table by name
addTable(opts)	void	Add an Excel table
removeTable(name)	boolean	Remove table by name
groupRows(start, end, level?)	void	Set outline level on rows
ungroupRows(start, end)	void	Remove outline from rows
collapseRows(start, end)	void	Collapse grouped rows
expandRows(start, end)	void	Expand collapsed rows
groupColumns(start, end, level?)	void	Set outline level on columns
ungroupColumns(start, end)	void	Remove outline from columns

Cell

Properties

Property	Type	Description
reference	string	Cell reference (e.g. "A1")
type	CellType	Value type
value	string | number | boolean | null	Cell value (read/write)
formula	string | null	Formula (read/write)
styleIndex	number | null	Style index (read/write)
numberFormat	string | null	Resolved format code from style index
dateValue	Date | null	Returns Date if cell contains a date-formatted number

StyleBuilder

Fluent builder for creating cell styles:

const idx = wb.createStyle()
  .font({ name: 'Arial', size: 12, bold: true, color: 'FF0000' })
  .fill({ pattern: 'solid', fgColor: 'FFFF00' })
  .border({ top: { style: 'thin', color: '000000' } })
  .alignment({ horizontal: 'center', wrapText: true })
  .protection({ locked: true })
  .numberFormat('#,##0.00')
  .build(wb.styles);

Utility Functions

Sheet Conversions

Function	Description
aoaToSheet(data, opts?)	Array-of-arrays to Worksheet
jsonToSheet(data, opts?)	JSON array to Worksheet
sheetToJson(ws, opts?)	Worksheet to JSON array
sheetToCsv(ws, opts?)	Worksheet to CSV string
sheetToHtml(ws, opts?)	Worksheet to HTML table
sheetAddAoa(ws, data, opts?)	Append array data
sheetAddJson(ws, data, opts?)	Append JSON data
sheetToTxt(ws, opts?)	Worksheet to tab-separated text
sheetToFormulae(ws)	Extract all values/formulas as ["A1=100", "A3='SUM(A1:A2)"]

Date Utilities

Function	Description
dateToSerial(date)	Date/Temporal to Excel serial
serialToDate(serial)	Excel serial to Date
isDateFormatId(id)	Check if built-in date format
isDateFormatCode(code)	Check if date format string

Cell References

Function	Description
encodeCellRef(row, col)	(0, 0) → "A1"
decodeCellRef(ref)	"A1" → { row: 0, col: 0 }
encodeRange(start, end)	Addresses to range string
decodeRange(range)	Range string to addresses
columnToLetter(col)	0 → "A"
letterToColumn(letter)	"A" → 0
encodeRow(row)	0 → "1" (0-based to 1-based)
decodeRow(str)	"1" → 0 (1-based to 0-based)
splitCellRef(ref)	"$A$1" → { col: "A", row: "1", absCol: true, absRow: true }

Formatting

Function	Description
formatCell(value, format)	Format value with Excel format code
formatCellRich(value, format)	Format value, returns { text, color } with color metadata
getBuiltinFormat(id)	Get built-in format string by ID
loadFormat(id, code)	Register a custom format code at runtime
loadFormatTable(table)	Bulk-register format codes by ID (Record<number, string>)

Table Layout Engine

drawTable(wb, ws, opts): TableResult

Draw a styled table on a worksheet from declarative options.

import { drawTable, Workbook } from 'modern-xlsx';

const wb = new Workbook();
const ws = wb.addSheet('Report');

const result = drawTable(wb, ws, {
  headers: ['Name', 'Department', 'Salary'],
  rows: [
    ['Alice', 'Engineering', 95000],
    ['Bob', 'Marketing', 72000],
  ],
  columnWidths: [20, 18, 12],
  headerColor: '2F5496',
  alternateRowColor: 'D6E4F0',
  freezeHeader: true,
  autoFilter: true,
  columns: [
    { align: 'left' },
    { align: 'center' },
    { align: 'right', numberFormat: '$#,##0' },
  ],
});

console.log(result.range); // "A1:C3"

drawTableFromData(wb, ws, data, opts?): TableResult

Create a table from a JSON array with auto-extracted headers.

import { drawTableFromData } from 'modern-xlsx';

drawTableFromData(wb, ws, [
  { name: 'Alice', age: 30, city: 'NYC' },
  { name: 'Bob', age: 25, city: 'LA' },
], {
  headerMap: { name: 'Full Name', age: 'Age', city: 'City' },
  autoWidth: true,
});

Table Types

Type	Description
DrawTableOptions	Full options for drawTable (headers, rows, styling, merges, cellStyles)
DrawTableFromDataOptions	Extends DrawTableOptions with headerMap and optional headers override
TableResult	{ range, rowCount, colCount, firstDataRow, lastDataRow }
TableColumn	{ header?, width?, align?, numberFormat? }
CellStyle	{ font?, fill?, border?, alignment?, numberFormat? }

See the Table Layout Engine guide for full options reference, recipes, and composition patterns.

Barcode & QR Generation

Encoding Functions

Function	Description
encodeCode39(data)	Code 39 barcode matrix
encodeCode128(data)	Code 128 barcode matrix
encodeEAN13(data)	EAN-13 barcode matrix
encodeUPCA(data)	UPC-A barcode matrix
encodeITF14(data)	ITF-14 barcode matrix
encodeGS1128(data)	GS1-128 barcode matrix
encodeQR(data)	QR Code matrix
encodeDataMatrix(data)	Data Matrix barcode matrix
encodePDF417(data)	PDF417 barcode matrix

Rendering

Function	Description
renderBarcodePNG(matrix, opts?)	Render barcode matrix to PNG Uint8Array

Options: { scale?: number, margin?: number }

XLSX Embedding

Function	Description
generateBarcode(wb, ws, opts)	One-call barcode generation + XLSX embedding
generateDrawingXml(anchors)	Generate drawing XML for image anchors
generateDrawingRels(rels)	Generate drawing relationships XML

DrawBarcodeOptions:

{
  type: BarcodeType;  // 'code39' | 'code128' | 'ean13' | 'upca' | 'itf14' | 'gs1128' | 'qr' | 'datamatrix' | 'pdf417'
  data: string;
  anchor: ImageAnchor;
  scale?: number;
  margin?: number;
}

Types

Type	Description
BarcodeMatrix	{ rows: number[][]; width: number; height: number }
BarcodeType	Union of supported barcode format strings
DrawBarcodeOptions	Options for generateBarcode()
ImageAnchor	{ from: { col, row }, to: { col, row } }
RenderOptions	{ scale?: number; margin?: number }

Excel Tables (ListObjects)

ws.addTable(opts)

Add a native Excel table to a worksheet.

ws.addTable({
  name: 'SalesTable',
  ref: 'A1:D10',
  columns: [
    { name: 'Product' },
    { name: 'Region' },
    { name: 'Revenue', totalsRowFunction: 'sum' },
    { name: 'Count', totalsRowFunction: 'count' },
  ],
  style: { name: 'TableStyleMedium9', showRowStripes: true },
  totalsRowCount: 1,
});

Built-in Table Styles

import { TABLE_STYLES, VALID_TABLE_STYLES } from 'modern-xlsx';

TABLE_STYLES.light;   // ['TableStyleLight1', ..., 'TableStyleLight21']
TABLE_STYLES.medium;  // ['TableStyleMedium1', ..., 'TableStyleMedium28']
TABLE_STYLES.dark;    // ['TableStyleDark1', ..., 'TableStyleDark11']

VALID_TABLE_STYLES.has('TableStyleMedium9'); // true

Table Types

Type	Description
TableDefinitionData	Full table definition (name, ref, columns, style, autoFilter, totals)
TableColumnData	Column with name, id, optional totalsRowFunction/calculatedColumnFormula
TableStyleInfoData	Style name + show flags (rowStripes, columnStripes, firstColumn, lastColumn)
TotalsRowFunction	'sum' | 'count' | 'average' | 'min' | 'max' | 'countNums' | 'stdDev' | 'var' | 'custom' | 'none'

Headers & Footers

HeaderFooterBuilder

import { HeaderFooterBuilder } from 'modern-xlsx';

const hf = new HeaderFooterBuilder()
  .left(HeaderFooterBuilder.date())
  .center(HeaderFooterBuilder.bold('Sales Report'))
  .right(`Page ${HeaderFooterBuilder.pageNumber()} of ${HeaderFooterBuilder.totalPages()}`)
  .build();

ws.headerFooter = {
  oddHeader: hf,
  oddFooter: new HeaderFooterBuilder()
    .center(HeaderFooterBuilder.fileName())
    .build(),
};

Formatting Codes

Method	Code	Output
pageNumber()	&P	Current page number
totalPages()	&N	Total pages
date()	&D	Current date
time()	&T	Current time
fileName()	&F	File name
sheetName()	&A	Sheet name
filePath()	&Z	File path
bold(text)	&B...&B	Bold text
italic(text)	&I...&I	Italic text
fontSize(n, text)	&n...	Set font size
fontName(name, text)	&"name"...	Set font
color(hex, text)	&K...	Set color

Row & Column Grouping

// Group rows 2-10 at outline level 1
ws.groupRows(2, 10);

// Nested group at level 2
ws.groupRows(3, 5, 2);

// Collapse/expand
ws.collapseRows(2, 10);
ws.expandRows(2, 10);

// Group columns A-C
ws.groupColumns(1, 3);

// Set summary position
ws.outlineProperties = { summaryBelow: true, summaryRight: true };

Print Titles & Areas

// Repeat row 1 on every printed page
wb.setPrintTitles('Sheet1', { rows: { start: 1, end: 1 } });

// Repeat columns A-B
wb.setPrintTitles('Sheet1', { cols: { start: 1, end: 2 } });

// Both rows and columns
wb.setPrintTitles('Sheet1', {
  rows: { start: 1, end: 2 },
  cols: { start: 1, end: 1 },
});

// Set print area
wb.setPrintArea('Sheet1', 'A1:G50');

// Get current config
const titles = wb.getPrintTitles('Sheet1');
const area = wb.getPrintArea('Sheet1');