# Jspreadsheet

> Jspreadsheet is a JavaScript spreadsheet library for building Excel-like data grid experiences in web applications. It includes a front-end component with cell editing, formulas, multi-sheet workbooks, XLSX import/export, and real-time collaboration, plus a Node.js server (`@jspreadsheet/server`) for real-time sync via Socket.IO. The Community Edition (CE) is MIT-licensed and free. The Pro version adds enterprise features and requires a commercial license.

The front-end component and its features are detailed in the Core Features section below. Jspreadsheet Server handles conflict resolution and sync; authentication and data persistence are the developer's responsibility.

The current major version is v12. TypeScript definitions ship with the package.

## Getting started

### Installation

Three options:

**npm** — install the core package, or the framework wrappers:
```bash
npm install jspreadsheet@12

# React
npm install @jspreadsheet/react@12

# Vue
npm install @jspreadsheet/vue@12

# All extensions bundled
npm install @jspreadsheet/bundle
```

Angular uses the vanilla JS package directly — there is no Angular-specific wrapper.

**CDN** — Jspreadsheet depends on [jsuites](https://jsuites.net), so you need both:
```html
<script src="https://cdn.jsdelivr.net/npm/jspreadsheet@12/dist/index.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/jspreadsheet@12/dist/jspreadsheet.min.css" />
<script src="https://cdn.jsdelivr.net/npm/jsuites@6/dist/jsuites.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/jsuites@6/dist/jsuites.min.css" />
```

**Download** — grab the zip and host the files yourself: https://jspreadsheet.com/v12/jspreadsheet.zip

### License

The Pro version requires a license string. You generate a certificate from your account at https://jspreadsheet.com/me. Certificates are valid for 12 months. The 30-day trial certificate works the same way.

Call `setLicense` once before any spreadsheet is initialized:
```js
jspreadsheet.setLicense('your-license-string-here');
```

CE (community edition) is MIT-licensed and does not require a license call.

### Basic initialization

```js
jspreadsheet(document.getElementById('spreadsheet'), {
    worksheets: [{
        data: [
            ['Mazda', 2001, 2000],
            ['Peugeot', 2010, 5000],
        ],
        columns: [
            { title: 'Model', width: '300px' },
            { title: 'Year', width: '80px' },
            { title: 'Price', width: '100px' },
        ]
    }]
});
```

The `worksheets` array supports multiple sheets. Each sheet is configured independently.

### Importing files

To load CSV, ODS, and other common formats, use [TabularJS](https://www.npmjs.com/package/tabularjs) — a separate package that converts 16+ file formats into Jspreadsheet-compatible JSON. TabularJS can read `.xlsx` files too, but it does not preserve styles or formulas. For full-fidelity `.xlsx` import, use the paid Import from XLSX extension (see Extensions).
```bash
npm install tabularjs
```

**Docs:** https://jspreadsheet.com/docs/getting-started

---

## Core features

### Workbook and sheet structure

A spreadsheet instance holds one or more worksheets. Each worksheet is configured independently — its own data, columns, rows, and settings. Sheets can be added, removed, renamed, or reordered programmatically at runtime.

### Cell types and editors

Every column (or individual cell) gets a type that controls how data is entered and displayed. Built-in types: `text`, `number`, `numeric`, `percent`, `dropdown`, `autocomplete`, `calendar`, `checkbox`, `radio`, `color`, `image`, `html`, `tags`, `email`, `url`, `progressbar`, `rating`, `autonumber`, `notes`, `hidden`, `record`, `time`. (`number` and `numeric` are aliases; `percent` formats as a percentage.) You can also write custom editors — any JavaScript component that implements the open/close/getValue interface — and register them globally or per column.

### Formulas

Jspreadsheet ships with two formula tiers:

- **Formula Basic** — included in the core package. Covers standard arithmetic, text, logical, and date functions compatible with Excel and Google Sheets.
- **Formula Pro** — a separate paid extension. Required for advanced functions, array formulas, named ranges, and broader Excel compatibility. See https://jspreadsheet.com/products/formulas

Formulas auto-update when cells are moved, copied, or pasted. You can register custom functions in JavaScript and they behave like native ones. All formula names must be uppercase.

### Data operations

- **Sorting** — click a column header or call `orderBy()` programmatically. Supports custom sort functions.
- **Filtering** — column filters with Excel-style dropdowns. Also supports range-based filters.
- **Search** — built-in search across the dataset, works alongside pagination.
- **Pagination** — splits large datasets into pages. Page size is configurable.

### Layout controls

- **Frozen rows and columns** — rows or columns that stay fixed while the user scrolls.
- **Merged cells** — merge a range into a single cell; merge state survives serialization.
- **Nested headers** — multi-level column headers for organizing grouped data visually.
- **Column and row groups** — collapsible groups for hiding related rows or columns.
- **Resize** — columns and rows are resizable by drag; width/height can also be set programmatically.

### Selection and clipboard

Selection supports single cells, ranges, and non-consecutive ranges (Ctrl+click). The clipboard copies data, formulas, and styles between cells or between different spreadsheet instances on the same page. Paste behavior on existing data is configurable.

### History

All changes are tracked automatically. Undo is Ctrl+Z, redo is Ctrl+Y. You can also call `undo()` and `redo()` programmatically, inspect the history stack, or mark specific operations as non-undoable.

### Validation and conditional formatting

Rules can be defined per column or cell range — data type checks, value ranges, regex patterns, or custom functions. Conditional formatting changes cell appearance based on the same rule types.

### Performance

For large datasets, there are two options:

- **Viewport rendering** — only renders visible rows, so DOM node count stays constant regardless of row count. (The underlying data array still lives in memory.)
- **Pagination** — limits the DOM to one page of rows at a time.

Both can be combined with server-side data loading.

### Events and plugins

Every user action fires an event (`onchange`, `onsort`, `onselection`, etc.). You can intercept actions before they happen by returning `false` from the relevant `onbefore*` event.

The plugin system gives you a hook into the full spreadsheet lifecycle. Plugins can add toolbar buttons, context menu items, custom keyboard shortcuts, or new cell types. The official extensions are built on the same plugin API.

### Extensions

Extensions are paid add-ons sold separately or bundled by license tier (Enterprise or Ultimate).

**Enterprise extensions:**

- **Formula Pro** — advanced formula engine: array formulas, cross-sheet references, named ranges, extended function library. Required for anything beyond basic Excel-compatible functions. https://jspreadsheet.com/products/formulas
- **Export to XLSX** — exports the current spreadsheet to an Excel-compatible `.xlsx` file. https://jspreadsheet.com/products/export-to-xlsx
- **Import from XLSX** — parses an `.xlsx` file and loads it into Jspreadsheet. https://jspreadsheet.com/products/import-from-xlsx
- **Charts** — embeds interactive charts driven by spreadsheet data. https://jspreadsheet.com/products/charts
- **Validations** — adds a UI for building and managing data validation rules per column or range. https://jspreadsheet.com/products/validations
- **Advanced CSV importer** — imports CSV files into the spreadsheet. https://jspreadsheet.com/products/csv-importer
- **Advanced Comments** — floating comment threads with author name, avatar, and timestamp. https://jspreadsheet.com/products/comments
- **Search and Replace** — find and replace across the sheet. https://jspreadsheet.com/products/search
- **Spreadsheet to Form** — generates an HTML form from the column definition of a worksheet. https://jspreadsheet.com/products/forms

**Ultimate extensions** (includes all Enterprise extensions plus):

- **Jspreadsheet Server** — Node.js server for real-time multi-user sync via Socket.IO. https://jspreadsheet.com/products/server
- **Jspreadsheet Client** — front-end connector that links a spreadsheet instance to a Jspreadsheet Server. https://jspreadsheet.com/products/client
- **Edition Bar** — adds an Excel-style formula bar above the worksheet. https://jspreadsheet.com/products/edition-bar
- **Format** — lets users configure number formatting, date masks, and display format per column or cell. https://jspreadsheet.com/products/format
- **Topmenu** — adds a customizable top-level menu bar to the spreadsheet interface. https://jspreadsheet.com/products/topmenu
- **Export to PDF** — exports the spreadsheet to PDF or triggers the browser print dialog. https://jspreadsheet.com/products/export-to-pdf
- **Google Sheets Importer** — imports a Google Sheets document into Jspreadsheet. https://jspreadsheet.com/products/import-from-google-sheets
- **Shapes** — overlays drawing shapes on the spreadsheet canvas. https://jspreadsheet.com/products/shapes
- **OpenAI / ChatGPT** — calls the ChatGPT API from within a spreadsheet cell or formula context. https://jspreadsheet.com/products/openai
- **Pivot Tables** — builds pivot tables from worksheet data. https://jspreadsheet.com/products/pivot

**All extensions:** https://jspreadsheet.com/products

**Full feature list:** https://jspreadsheet.com/docs

---

## API reference

### Structure

The API has two levels:

**Global** — methods on the `jspreadsheet` function itself, used for setup and lifecycle:

| Method | Signature |
|---|---|
| `setLicense` | `jspreadsheet.setLicense(license: string)` |
| `setExtensions` | `jspreadsheet.setExtensions(extensions: object \| null)` |
| `setDictionary` | `jspreadsheet.setDictionary(translations: object)` |
| `destroy` | `jspreadsheet.destroy(element: HTMLElement \| object, unbindEvents?: boolean)` |
| `destroyAll` | `jspreadsheet.destroyAll()` |
| `getWorksheetInstanceByName` | `jspreadsheet.getWorksheetInstanceByName(name: string, namespace?: string)` |

**Worksheet instance** — methods on the object returned by `jspreadsheet()`. Each sheet in a workbook is a separate instance. When you call `jspreadsheet(element, options)`, it returns an array of worksheet instances — one per sheet defined in `worksheets`.

```js
const worksheets = jspreadsheet(element, { worksheets: [{...}, {...}] });
const ws = worksheets[0]; // first sheet
ws.getData();
ws.setValue('A1', 'hello');
```

---

### Data methods

| Method | Description |
|---|---|
| `getData(highlighted?, processed?, delimiter?, asJson?, includeFilteredRows?)` | Get all data. Pass `true` for `highlighted` to get only selected cells. |
| `getDataFromRange(range: string)` | Get data from a range like `"A1:C5"`. |
| `getRowData(rowNumber)` | Get one row by zero-indexed number. |
| `getColumnData(colNumber)` | Get one column by zero-indexed number. |
| `getValue(cellName, processed?, raw?)` | Get a cell value by name (`"A1"`). |
| `getValueFromCoords(x, y, processed?, raw?)` | Get a cell value by coordinates. |
| `setData(data: [][])` | Replace all data. |
| `loadData(data: [][], adjustDimensions?)` | Replace all data without triggering events. |
| `setValue(cellName \| changes[], value?, force?)` | Set one or multiple cell values. |
| `setValueFromCoords(x, y, value, force?)` | Set a cell value by coordinates. |
| `setRowData(rowNumber, data[], force?)` | Replace one row. |
| `setColumnData(colNumber, data[], force?)` | Replace one column. |
| `download(includeHeaders?, processed?)` | Download the worksheet as CSV. |

**Docs:** https://jspreadsheet.com/docs/data

---

### Column methods

| Method | Description |
|---|---|
| `insertColumn(columns?, position?, insertBefore?)` | Insert one or more columns. |
| `deleteColumn(columns, numOfColumns?)` | Delete columns by index. |
| `moveColumn(from, to)` | Reorder a column. |
| `showColumn(columns)` / `hideColumn(columns)` | Toggle column visibility. |
| `getWidth(colNumber?)` | Get column width(s). |
| `setWidth(col, width)` | Set column width. |
| `autoWidth(columns?)` | Resize columns to fit their content. |
| `getColumn(colNumber)` | Get column settings object. |
| `setProperty(colNumber, properties)` | Update column settings. (Note: same method name as the cell-level `setProperty(col, row, properties)` — when called with 2 args it targets the column, with 3 args it targets a cell.) |

**Docs:** https://jspreadsheet.com/docs/columns

---

### Row methods

| Method | Description |
|---|---|
| `insertRow(rows?, rowNumber?, insertBefore?)` | Insert one or more rows. |
| `deleteRow(rowNumber, numOfRows?)` | Delete rows by index. |
| `moveRow(from, to)` | Reorder a row. |
| `showRow(rowNumber)` / `hideRow(rowNumber)` | Toggle row visibility. |
| `getHeight(rowNumber?)` | Get row height. |
| `setHeight(rowNumber, height)` | Set row height. |

**Docs:** https://jspreadsheet.com/docs/rows

---

### Cell methods

| Method | Description |
|---|---|
| `getCell(cellName)` | Get the DOM element for a cell by name (`"A1"`). |
| `getCellFromCoords(x, y)` | Get the DOM element by coordinates. |
| `getProperty(col, row)` | Get cell-level configuration. |
| `setProperty(col, row, properties)` | Update cell-level configuration. |

See the Cell types and editors section above for the full list of built-in `type` values.

**Docs:** https://jspreadsheet.com/docs/cells

---

### Style methods

| Method | Description |
|---|---|
| `getStyle(cellName?, onlyIndexes?)` | Get styles for a cell or all cells. |
| `setStyle(cell, property?, value?, forceOverwrite?)` | Apply CSS styles to cells or ranges. |
| `resetStyle(cellName)` | Remove styles from cells. |

**Docs:** https://jspreadsheet.com/docs/style

---

### Worksheet methods

These live on the top-level workbook object, not on the individual worksheet instances returned by `jspreadsheet()`. To call them, use the element reference or the `parent` property of any worksheet instance (e.g., `worksheets[0].parent.createWorksheet(...)`):

| Method | Description |
|---|---|
| `createWorksheet(options, position?)` | Add a new sheet. |
| `deleteWorksheet(position?)` | Remove a sheet. |
| `renameWorksheet(position, title)` | Rename a sheet. |
| `moveWorksheet(from, to)` | Reorder sheets. |
| `openWorksheet(position?)` | Switch to a sheet. |
| `getWorksheetActive()` | Get the index of the active sheet. |
| `getWorksheetInstanceByName(name)` | Get a sheet instance by name. |

**Docs:** https://jspreadsheet.com/docs/worksheets

---

### Events

Events are passed as properties in the spreadsheet configuration object. Every action has an `onbefore*` version that can cancel the action by returning `false`, and an `on*` version that fires after.

Key events:

| Event | Fires when |
|---|---|
| `onload` | Spreadsheet data is ready. |
| `onchange` | A cell value changes. |
| `onafterchanges` | A batch of changes completes (paste, fill-handle). |
| `onbeforechange` | Before a cell value changes — return a new value to override, `false` to cancel. |
| `oninsertrow` / `ondeleterow` | Row inserted or deleted. |
| `oninsertcolumn` / `ondeletecolumn` | Column inserted or deleted. |
| `onselection` | Selection changes. |
| `onsort` | Column sorted. |
| `onmerge` | Cells merged. |
| `onundo` / `onredo` | History action applied. |
| `onerror` | An error occurs. |

**Full events list:** https://jspreadsheet.com/docs/events

---

### Configuration

Configuration is split across two levels. Spreadsheet-level options apply to the whole workbook. Worksheet-level options go inside the `worksheets` array and apply per sheet.

```js
jspreadsheet(element, {
    // spreadsheet-level
    tabs: true,
    toolbar: true,
    onchange: (worksheet, cell, x, y, newVal, oldVal) => { ... },

    worksheets: [{
        // worksheet-level
        data: [...],
        columns: [...],
        minDimensions: [10, 10],
        tableOverflow: true,
        tableWidth: '800px',
    }]
});
```

**Config reference:** https://jspreadsheet.com/docs/config

---

## Changelog and versioning

### Current version

**jspreadsheet v12.3.10** — released 26 Feb 2026.

Each package in the ecosystem versions independently. `jspreadsheet` (core), `@jspreadsheet/formula-pro`, `@jspreadsheet/server`, and other extensions all have their own version numbers. The changelog tracks all of them together.

**Changelog:** https://jspreadsheet.com/docs/changelog

---

### What changed in v12

v12 is the current major version. Key changes from v11:

- Viewport rendering now handles over 1 million rows with real DOM elements (not canvas).
- Copy-paste from Excel and Google Sheets preserves styles.
- Worksheet tables — named regions with configurable headers, dropdown filters, total rows, and theme styling. Compatible with structured reference syntax from other spreadsheet software.
- Web component support for custom cell editors.
- Multi-column and multi-row drag-and-drop.
- New `time` editor type.
- `undefined`/`null` now treated differently from empty strings in `getData()` and formula calculations. To explicitly store an empty string, prefix the value with a single quote:
  ```js
  ws.setValue('A1', "''"); // stores empty string, not null
  ```
- `autoNames` replaces the removed `ignoreUndefinedColumns` property.

**v12 upgrade guide:** https://jspreadsheet.com/docs/upgrades

---

### Breaking changes when upgrading to v12

**Formula Pro:** v12 requires Formula Pro 6. Formula Pro 5 (used with v11) is not compatible.

```html
<!-- v12 requires this -->
<script src="https://cdn.jsdelivr.net/npm/@jspreadsheet/formula-pro@6/dist/index.min.js"></script>
```

**jsuites:** v12 requires jsuites 6.

```html
<script src="https://cdn.jsdelivr.net/npm/jsuites@6/dist/jsuites.min.js"></script>
```

**Persistence API:** The per-worksheet `persistence`, `server`, and `save` options were removed. Use the spreadsheet-level `persistence` function instead. The `onbeforesave`, `onsave`, and `onbeforesend` events were also removed.

---

### Older version docs

Documentation for older major versions is available at:

- v11: https://jspreadsheet.com/docs/v11
- v10: https://jspreadsheet.com/docs/v10

---

## Framework integrations

### React

Install the React wrapper:

```bash
npm install @jspreadsheet/react
```

The wrapper exposes `<Spreadsheet>` and `<Worksheet>` as JSX components. Each `<Worksheet>` maps to one sheet in the workbook. Access the spreadsheet instance via a `ref` on `<Spreadsheet>` — `ref.current[0]` gives you the first worksheet instance, from which you can call any API method.

```jsx
import { useRef } from "react";
import { Spreadsheet, Worksheet, jspreadsheet } from "@jspreadsheet/react";
import "jsuites/dist/jsuites.css";
import "jspreadsheet/dist/jspreadsheet.css";

jspreadsheet.setLicense('your-license-key');

export default function App() {
    const spreadsheet = useRef();
    return (
        <Spreadsheet ref={spreadsheet}>
            <Worksheet data={data} columns={columns} />
        </Spreadsheet>
    );
}
```

You can also use the core library directly with `useRef` + `useEffect` if you prefer to avoid the wrapper. TypeScript definitions are included.

One dependency to be aware of: Material Icons must be loaded separately for toolbar and context menu icons to render correctly:

```html
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Material+Icons" />
```

**Docs:** https://jspreadsheet.com/docs/react

---

### Vue

Install the Vue wrapper:

```bash
npm install @jspreadsheet/vue
```

The wrapper uses the same `<Spreadsheet>` / `<Worksheet>` component pattern as React. One Vue-specific detail: use the `styles` prop instead of `style` on Jspreadsheet components — the wrapper renames it to avoid conflicts with Vue's built-in `style` attribute.

The wrapper works with both the Options API and the Composition API. You can also skip the wrapper and call the core library directly from `onMounted`, using a template ref to get the DOM element.

**Docs:** https://jspreadsheet.com/docs/vue

---

### Angular

There is no Angular-specific wrapper package. Use the core `jspreadsheet` package directly:

```bash
npm install jspreadsheet
```

The standard pattern is to grab the DOM element with `@ViewChild` and initialize inside `ngAfterViewInit`:

```typescript
import { Component, ViewChild, ElementRef, AfterViewInit } from "@angular/core";
import jspreadsheet from "jspreadsheet";
import "jspreadsheet/dist/jspreadsheet.css";
import "jsuites/dist/jsuites.css";

jspreadsheet.setLicense('your-license-key');

@Component({
    standalone: true,
    selector: "app-root",
    template: `<div #spreadsheet></div>`
})
export class AppComponent implements AfterViewInit {
    @ViewChild("spreadsheet") spreadsheet: ElementRef;
    worksheets: jspreadsheet.worksheetInstance[];

    ngAfterViewInit() {
        this.worksheets = jspreadsheet(this.spreadsheet.nativeElement, {
            worksheets: [{ minDimensions: [10, 10] }]
        });
    }
}
```

TypeScript definitions ship with the package and cover all API methods, events, and configuration options.

**Docs:** https://jspreadsheet.com/docs/angular

---

## Licensing

### Editions

| | CE (Community) | Enterprise | Ultimate | Tailored |
|---|---|---|---|---|
| Cost | Free (MIT) | Paid | Paid | Custom quote |
| Developers | Unlimited | Up to 5 | Up to 10 | 10+ |
| Applications | Unlimited | 1 | 1 | Custom |
| Enterprise extensions | No | Yes | Yes | Yes |
| Ultimate extensions | No | No | Yes | Yes |

**CE** is the open-source edition on GitHub. It covers core spreadsheet functionality and has no license requirement.

**Enterprise** is for teams of up to 5 developers building a single application. Includes all Enterprise extensions (Formula Pro, XLSX, Charts, Validations, Comments, CSV importer, Search and Replace, Spreadsheet to Form).

**Ultimate** is for teams of up to 10 developers building a single application. Adds all Ultimate extensions on top of Enterprise (Server, Client, Edition Bar, Format, Topmenu, PDF export, Google Sheets importer, Shapes, OpenAI, Pivot Tables).

**Tailored** is for teams larger than 10 developers or projects needing multiple applications. Contact sales for pricing.

Both internal tools and SaaS/on-premise applications are covered by all paid plans. End-user count is unlimited.

**Pricing page:** https://jspreadsheet.com/pricing

---

### Payment and purchasing

- Monthly, annual, and perpetual license options are available.
- Perpetual licenses include 12 months of updates; you may use any version released during that window indefinitely, but support and upgrades stop after 12 months.
- Annual subscriptions include support and upgrades for the duration.
- Payments by credit card or bank wire.
- Up to 50% discount for nonprofits, educational organizations, and startups — contact contact@jspreadsheet.com.
- Resellers are available in some regions: https://jspreadsheet.com/resellers

---

### Certificates

A license is a self-signed string called a certificate. You generate it from your account at https://jspreadsheet.com/me and pass it to `jspreadsheet.setLicense()` once before initializing any spreadsheet.

- Subscription certificates are valid for 12 months and must be renewed annually.
- Perpetual purchase certificates are valid for 100 years.
- Trial certificates are valid for 30 days and cover all Pro features.
- Generating a new certificate does not invalidate the previous one.
- Validation happens entirely offline — no network request is made at runtime.
- Certificates are domain-scoped. Domains are treated as wildcards (subdomains included). Register domains without `http://`, `www`, or port numbers. `localhost` is included in all certificates automatically.
- To verify a certificate manually: https://jspreadsheet.com/me/validate

**License docs:** https://jspreadsheet.com/docs/license

---

## Support and community

### Documentation

The main docs site covers all configuration options, methods, events, and extensions with code examples for vanilla JS, React, Vue, and Angular.

https://jspreadsheet.com/docs

### Technical support

Paid license holders get support via email and chat.

- Technical issues: support@jspreadsheet.com
- Sales and general questions: contact@jspreadsheet.com
- Contact form: https://jspreadsheet.com/contact

### GitHub

The Pro repository is used for bug reports and discussions:
https://github.com/jspreadsheet/pro

The CE (community edition) repository:
https://github.com/jspreadsheet/ce

### npm

- Core: https://www.npmjs.com/package/jspreadsheet
- CE: https://www.npmjs.com/package/jspreadsheet-ce
- React wrapper: https://www.npmjs.com/package/@jspreadsheet/react
- Vue wrapper: https://www.npmjs.com/package/@jspreadsheet/vue
- Server: https://www.npmjs.com/package/@jspreadsheet/server
- Formula Pro: https://www.npmjs.com/package/@jspreadsheet/formula-pro
- Bundle (all extensions): https://www.npmjs.com/package/@jspreadsheet/bundle

---

**Site:** https://jspreadsheet.com
**Docs:** https://jspreadsheet.com/docs
**Changelog:** https://jspreadsheet.com/docs/changelog
**npm:** `npm install jspreadsheet@12`
**CDN:** https://cdn.jsdelivr.net/npm/jspreadsheet@12/dist/index.min.js