GridPath

gridpath

Real Excel files, in your web app and in your agent. Open the .xlsx your users already have, keep every formula live at full size, let AI edit it with review, and save back the same file.

Both run the same engine (a fork of IronCalc): real formulas evaluated in process, and saves that patch the original file so untouched parts come back byte-identical. Recalculated formulas and supported chart data caches carry current values; chart definitions remain native Excel XML.

In your web app

• Quick start · Next.js · What users get
• Workbooks and documents · CSV and text files · Saving · Saving to your backend
• Errors · Excel's saved values · AI
• Options · Methods · Bundlers · How saving works

Quick start

npm install gridpath react react-dom

React and React DOM are peer dependencies. Your app doesn't have to use React: createSpreadsheet mounts the spreadsheet into any element.

import { Spreadsheet } from "gridpath";

(sheetRef.current = sheet)} onError={(err) => console.error(err.code, err.message, err.hint)} /> ;

Without React:

import { createSpreadsheet } from "gridpath";

const sheet = await createSpreadsheet(document.getElementById("sheet")!, { file: await file.arrayBuffer() }); sheet.setCell("Sheet1", "B2", "=SUM(A1:A10)"); console.log(await sheet.getCell("Sheet1", "B2")); // { value: 55, formula: "=SUM(A1:A10)" } const xlsx = await sheet.save(); // Uint8Array

createSpreadsheet resolves once the workbook is open. If it can't open it rejects with a GridPathError and leaves the element empty.

Next.js

No configuration is needed. This was tested on Next.js 16 with React 19, with Turbopack and with webpack, in next dev and in production builds.

• Render the spreadsheet from a client component ("use client"). The page around it can stay a server component.
• gridpath/agent works in a route handler.

examples/nextjs-demo is a complete app. Each user has a list of workbooks saved to the app's own API: app/api/books/[[...path]]/route.ts holds the REST routes httpStore calls, with auth. Each workbook has its own URL. The example shows:

• uploading and starting new workbooks;
• a loading indicator;
• what to do for each error code;
• switching workbooks, which saves the one being left.

What users get without any code

• A toolbar for formatting:
• undo and redo;
• font and size;
• bold, italic and underline;
• font and fill colour;
• alignment and wrap;
• currency, percent, comma, and more or fewer decimals;
• number formats;
• inserting and deleting rows and columns;
• sort, filter, freeze panes and clear.

Keyboard shortcuts (⌘B, ⌘Z, ⌘S…) work in the grid. toolbar={false} hides the toolbar.

• A save status that says where things are saved: "Saved in this browser", "Saved to your account", "Saving…", "Unsaved changes", or "Couldn't save · Retry".
• Edits are saved two seconds after they pause. ⌘S or the Save button saves at once.
• Reopening where they left off: after a reload, the workbook comes back and so does the cell the user was on.
• A File menu with Open…, New and Recent workbooks. fileMenu={false} removes those entries when your app has its own list.
• Version history: restore an earlier version, or download it. Restoring keeps the state it replaces as a version too.
• Download as .xlsx, a separate button from Save.
• An "AI changes" panel when an agent works through sheet.ai. Each change shows what it did ("D2: empty → =C2/B2-1") and where, with Accept and Reject buttons. Clicking a change shows its cells.
• reviewPanel={false} turns the panel off if your app has its own review UI.
• Plain explanations in place of the grid when a file can't be opened, for example "an old-format .xls workbook or a password-protected .xlsx".
• A count of formulas showing Excel's saved value in the toolbar, with a list of them.
• Its own question before anything is lost: opening another workbook over changes that can't be saved asks "Discard unsaved changes?".

Workbooks and documents

A spreadsheet shows one workbook at a time. You identify a workbook by its documentId, which defaults to fileName. Together with a store, the ID is how a workbook is loaded:

<Spreadsheet store={store} documentId={book.id} fileName={book.name} />

The spreadsheet opens the stored state for that ID. If you also pass a file, the stored state wins only when it was saved from that same file; otherwise file opens. With nothing stored and no file, the workbook starts blank.

Switching workbooks can be done in two ways:

1. Remount per document. Give the component key={book.id}, as the Next.js example does with a page per workbook.
2. Call `open()` or `openStored()` on the same spreadsheet. Both follow the same rules:

The File menu follows the same rules and asks the user before it discards anything.

Cleaning up.

• Unmount the component, or call `destroy()` (createSpreadsheet only). If there are edits that aren't saved yet, they are saved first. This covers a client-side navigation, which fires no beforeunload. Then the engine's worker stops. From then on, every call on the old sheet object fails with not-ready.
• Closing the page while edits are unsaved prompts the browser's "Leave site?" warning.

CSV and text files

file, open() and the File menu also take CSV and other delimited text. It opens as a new workbook, which saves as .xlsx: sales.csv becomes sales.xlsx, with one sheet named sales, and the toolbar says so.

• Delimiters: comma, tab, semicolon or pipe, whichever the first lines agree on. Excel's sep=; first line is honoured. In semicolon files a comma is the decimal point (1.234,5 is 1234.5).
• Encodings: UTF-8 (with or without a byte-order mark), UTF-16 with a mark (Excel's "Unicode Text"), otherwise Windows-1252.
• Values are read as if typed into the cell: numbers, currency, percentages, ISO and US dates, TRUE/FALSE, and = formulas, which calculate. A formula that doesn't parse stays text.
• Kept as text, where Excel would lose them: digits with leading zeros (ZIP codes, IDs) and digit strings longer than 15 (card and account numbers).
• Columns are widened to fit their text, up to 60 characters.

Text that isn't a table (.json, .xml, .html, .md…) is refused with unsupported-file. A 17 MB CSV (2 million cells) opens in 7 to 10 seconds in Chromium on a recent Mac.

Saving

Saving happens in three ways:

• Autosave: two seconds after edits pause. Change the delay with autosave (milliseconds), or turn it off with false.
• ⌘S and the Save button.
• `sheet.saveNow()` from your code.

Each save writes the workbook to the store and calls onSave. Watch it with onStatusChange or getStatus():

save() and saveBlob() return the bytes without touching the store, for an upload of your own.

Saving to your backend

By default, everything is kept in the user's browser (IndexedDB) by browserStore(). Saves within five minutes of each other share one version. The newest 20 versions are kept as they are, then one per day for 30 days. Tune this with browserStore({ checkpointMinutes, keepRecent, keepDays }).

To save to the signed-in user's account, point httpStore at your API:

import { httpStore } from "gridpath";

const store = httpStore({ url: "/api/books", // Called before every request, so a refreshed token is picked up. Leave it // out with cookie sessions. headers: async () => ({ Authorization: Bearer ${await getToken()} }), });

;

The routes it calls, all relative to url. Ids are URL-encoded:

When the backend can't be reached or answers with an error, the user's edits are not lost:

1. The status reads "Saved in this browser only · Retry", with keptLocally: true.
2. Autosave retries after 2, 5, 15 and 30 seconds, then every minute.
3. A copy of the edits waits in this browser.
4. If the page is closed first, the copy is reopened next time, newer than the backend's, and saved there. The status line says "Restored changes that weren't saved to your account".

If the backend can't be reached when a workbook *opens*, the spreadsheet shows the error with Try again.