syncfusion-javascript-excel

Syncfusion JavaScript Excel (@syncfusion/ej2-xlsx)

Programmatic Excel (.xlsx) create / open / edit / save for Node.js and browsers. This is a file-processing library, not a spreadsheet UI.

Package: @syncfusion/ej2-xlsx
Import surface: import { … } from '@syncfusion/ej2-xlsx' only
Not this skill: EJ2 Spreadsheet component, Grid UI, formula calculation engines, VBA execution

Table of contents

• When to use
• Documentation and navigation guide
• Quick start
• Core rules (always apply)
• Common patterns
• Import checklist

When to use

Use this skill when the user needs to:

• Build or transform .xlsx files in JS/TS (reports, exports, ETL, templates)
• Round-trip existing workbooks while preserving unknown OOXML
• Author cells, styles, tables, charts, validation, CF, comments, protection, etc.

Do not use for on-screen spreadsheet editing widgets or EJ2 Grid.

Documentation and navigation guide

Getting started

📄 Read: references/getting-started.md

• Install and import
• Workbook.create / open / save
• Node path vs browser bytes
• Minimal create → write cells → save

Workbook and sheets

📄 Read: references/workbook-and-sheets.md

• sheet(name|index), activeSheet, add/remove/move sheets
• Visibility, grid lines, zoom, column width / row height
• Named ranges (names), document properties, date1904
• Workbook protect / unprotect

Cells, values, and addresses

📄 Read: references/cells-values-and-addresses.md

• cell('A1') and cell(row, col) (1-based)
• value / text / number / dateTime
• Sparse grid; clear vs empty
• Error values (isCellError)

Formulas, merges, and hyperlinks

📄 Read: references/formulas-and-merged-hyperlinks.md

• Formula text only (never evaluated)
• No implicit =+/−/@ promotion on values
• Merged cells
• Hyperlinks (url | file | unc | workbook)

Styles and number formats

📄 Read: references/styles-number-formats.md

• CellStyle: font, fill, border, alignment, protection
• numberFormat and built-in vs custom codes
• Append-only style tables (never renumber)

Rich text and shared strings

📄 Read: references/rich-text-and-shared-strings.md

• workbook.createFont() + cell.richText
• Shared string storage behavior

Tables, filters, and sort

📄 Read: references/tables-filters-sort.md

• Excel Tables (tables.add)
• AutoFilter and sort metadata only (not runtime filter/sort engines)

Charts

📄 Read: references/charts.md

• addChart + ChartType.*
• Legend, title, series
• Do not use @syncfusion/ej2-xlsx/internal/charts in app samples

Images, shapes, and text boxes

📄 Read: references/images-shapes-textboxes.md

• addImage / addShape / addTextBox
• Anchors in points; preset shapes

Data validation

📄 Read: references/data-validation.md

• Whole, decimal, list, date, custom, etc.
• Operators, error UI, list dropdown polarity

Conditional formatting

📄 Read: references/conditional-formatting.md

• conditionalFormats.add(sqref)
• cellIs, expression, colorScale, dataBar, iconSet, top10, …
• DXF append-only; no runtime paint

Comments, form controls, and sheet protection

📄 Read: references/comments-controls-protection.md

• Classic notes and threaded comments
• Check boxes, combo boxes, and other form controls
• Sheet protect allow-flags; freeze panes

API conventions

📄 Read: references/api-conventions.md

• Index bases (sheet 0-based; cell row/col 1-based)
• Public surface vs internal
• Async save/open; TypeScript patterns

Capability boundaries

📄 Read: references/capability-boundaries.md

• What the library does not do
• OOXML preservation and security limits
• Workbook protect ≠ file encryption

Quick start

import { Workbook } from '@syncfusion/ej2-xlsx';

async function main(): Promise<void> {
  const wb = Workbook.create();
  const sheet = wb.sheet(0); // first sheet; index is 0-based

  sheet.cell('A1').value = 42;
  sheet.cell(1, 2).text = 'hello'; // row 1, column 2 → B1
  sheet.cell('A3').formula = 'SUM(A1:A1)'; // stored as text; leading = stripped
  sheet.cell('A4').numberFormat = '#,##0.00';
  sheet.cell('A4').value = 1234.5;

  // Browser / any host: bytes
  const bytes = await wb.save();

  // Round-trip
  const again = await Workbook.open(bytes);
  console.log(again.sheet(0).cell('A1').value); // 42

  // Node only: path overload
  // await wb.save('./out.xlsx');
  // const fromDisk = await Workbook.open('./out.xlsx');
}

void main();

Core rules (always apply)

1. Formulas are text. Never evaluate; never resolve external workbook links.
2. No implicit formula promotion. cell.value = '=1+1' stays a string, not a formula. Use cell.formula.
3. Sparse grid. Do not allocate cells from dimension/spans/column ranges alone.
4. Append-only shared tables. Shared strings, styles, number formats, dxf — never renumber existing indices.
5. Preserve unknown OOXML on load/save when the library does not model a part.
6. Public API only in samples: import from @syncfusion/ej2-xlsx. Do not teach ./internal/charts for application authors.
7. Indexing: sheet(i) is 0-based; cell(row, col) is 1-based; A1 strings always work.
8. Prefer sheet(0) or wb.activeSheet over non-public helpers in teaching samples.
9. getCell is deprecated — use cell.
10. Workbook/sheet protect is OOXML protection, not AES file encryption / password-to-open.

Common patterns

Write a column of values

const sheet = wb.sheet(0);
const rows = ['Name', 'Ada', 'Lin'];
for (let r = 0; r < rows.length; r++) {
  sheet.cell(r + 1, 1).text = rows[r];
}

Style a header

sheet.cell('A1').text = 'Total';
sheet.cell('A1').style = {
  font: { bold: true, size: 12 },
  fill: { type: 'pattern', patternType: 'solid', fgColor: { rgb: 'FF4472C4' } },
  alignment: { horizontal: 'center' },
};

Open → edit → save (Node)

const wb = await Workbook.open('./in.xlsx');
wb.sheet('Sheet1').cell('B2').value = 100;
await wb.save('./out.xlsx');

Import checklist

Typical named imports from @syncfusion/ej2-xlsx:

Need	Import
Workbook I/O	Workbook
Sheet handle	Worksheet (type)
Cells	Cell, CellValue, isCellError
Styles	CellStyle, BorderStyle, Font
Charts	ChartType, LegendPosition, Chart
Tables	Table, Tables
CF / DV	ConditionalFormats, DataValidations, …
Protection	SheetProtectionOptions, WorkbookProtectionOptions
Drawing	AutoShapeType, Image, TextBox, Shape

When unsure which reference to open: start at getting-started, then api-conventions, then the feature file that matches the user task.