XLSX

Parsing

Parse, inspect, and round-trip .xlsx files

The library provides two levels of parsing API:

parseWorkbook — High-level round-trip API that returns WorkbookOptions
parseXlsx — Low-level access to the raw XML parts of a .xlsx file

Both functions accept any DataType input: Uint8Array, ArrayBuffer, DataView, number[], base64 string, and more.

Round-Trip (parseWorkbook)

The parseWorkbook function parses a .xlsx file into the same WorkbookOptions format used by the Workbook constructor, enabling full round-trip (export → parse → re-export):

import { Workbook, Packer, parseWorkbook } from "@office-open/xlsx";
import { readFileSync } from "node:fs";

// Parse an existing .xlsx file
const opts = parseWorkbook(readFileSync("input.xlsx"));

// Modify cells if needed, then re-export
const wb = new Workbook(opts);
const buffer = await Packer.toBuffer(wb);

The returned options contain the same structure as the input format:

{
  "title": "My Workbook",
  "creator": "Author",
  "worksheets": [
    {
      "name": "Sheet1",
      "children": [
        { "cells": [{ "value": "Name" }, { "value": "Score" }] },
        { "cells": [{ "value": "Alice" }, { "value": 95 }] }
      ],
      "columns": [{ "min": 1, "max": 1, "width": 15 }],
      "mergeCells": [{ "from": { "row": 1, "col": 1 }, "to": { "row": 1, "col": 2 } }],
      "freezePanes": { "row": 1 },
      "autoFilter": "A1:B2"
    }
  ]
}

Parsed Fields

Field	Source	Description
`worksheets`	`xl/worksheets/sheet{n}`	Worksheet array with children and options
`title`	`docProps/core.xml`	Workbook title
`creator`	`docProps/core.xml`	Author name
`subject`	`docProps/core.xml`	Subject
`keywords`	`docProps/core.xml`	Keywords
`description`	`docProps/core.xml`	Description
`lastModifiedBy`	`docProps/core.xml`	Last modified by
`revision`	`docProps/core.xml`	Revision number

Worksheet Parsed Fields

Field	Description
`name`	Worksheet name
`children`	Array of rows, each with `cells`
`columns`	Column definitions with width
`mergeCells`	Merged cell ranges
`freezePanes`	Freeze pane configuration
`autoFilter`	Auto-filter range string
`dataValidations`	Data validation rules
`conditionalFormats`	Conditional formatting rules

Low-Level Parsing (parseXlsx)

The parseXlsx function reads a .xlsx file and provides access to its raw XML parts:

import { parseXlsx } from "@office-open/xlsx";
import { readFileSync } from "node:fs";

const doc = parseXlsx(readFileSync("input.xlsx"));

// Access workbook element
console.log(doc.workbook);

// Access worksheet paths
console.log(doc.worksheets);

// Access styles element
console.log(doc.styles);

// Access shared strings element
console.log(doc.sharedStrings);

XlsxDocument API

The returned XlsxDocument object contains:

Property	Type	Description
`doc`	`ParsedArchive`	Full parsed archive (all parts)
`workbook`	`Element \| undefined`	Workbook element (`xl/workbook.xml`)
`worksheets`	`string[]`	Worksheet paths
`styles`	`Element \| undefined`	Styles element
`sharedStrings`	`Element \| undefined`	Shared strings element
`partRefs`	`XlsxPartRefs`	References to charts, media, drawings
`coreProps`	`string \| undefined`	Path to core properties
`appProps`	`string \| undefined`	Path to app properties

Accessing Parts

const doc = parseXlsx(data);

// Get all parts by path
const workbook = doc.doc.get("xl/workbook.xml");
const styles = doc.doc.get("xl/styles.xml");
const sheet1 = doc.doc.get("xl/worksheets/sheet1.xml");

// Part references map to paths
for (const path of doc.partRefs.worksheets) {
  const sheet = doc.doc.get(path);
}

Working with XML Elements

The parsed elements use the @office-open/xml library's Element type:

import { attr } from "@office-open/xml";

// Access element attributes
for (const child of doc.workbook?.elements ?? []) {
  console.log(child.name);
}

Use Cases

Round-trip — Parse a .xlsx, modify cells, and re-export
Extract data — Walk the worksheet rows to extract cell values
Merge workbooks — Parse multiple .xlsx files and combine their sheets
Inspect formatting — Read style definitions and number formats
Transform — Modify parsed elements and rebuild a workbook