npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@polycyphers/spreadsheet

v1.4.5

Published

High-performance virtual-scrolled React spreadsheet with Excel I/O, formula engine, and plugin system

Readme

@polycyphers/spreadsheet

High-performance virtual-scrolled React spreadsheet with Excel I/O, a formula engine, and a plugin system.

Commercial. Production use requires a license — unlicensed instances render a visible watermark. A free 30-day trial is available, email-gated, no credit card. Details + pricing at packages.polycyphers.com/spreadsheet.

Highlights

  • Virtualized — handles 100k+ rows without dropping frames
  • Excel I/O — import/export XLSX with styles, formulas, merges
  • Formula engine — 70+ built-in functions, custom registrations, cross-sheet refs
  • Typed cells — text, number, currency, percentage, date, select, checkbox, formula
  • Sort / filter / pin / merge — all standard grid affordances
  • Clipboard + undo/redo — tab-delimited, batched history
  • Plugin system — CorePlugin<T> extension points for custom columns, validation, toolbars
  • React 19 + TypeScript-first, DaisyUI-compatible styles, tree-shakable

Install

npm install @polycyphers/spreadsheet

Setup

Import the stylesheet once in your app entry (e.g. main.tsx):

import "@polycyphers/spreadsheet/css";

For pages whose utility classes must beat the grid's own cell styles (cellClassName="bg-red-50 font-bold"), import the layered build instead — see Styling: cascade layer.

Peer dependencies — your app must have:

  • react >= 19.2.5
  • react-dom >= 19.2.5
  • exceljs >= 4.4.0 (optional — required only for Excel I/O)

Styling requirements (not peer deps, but expected by the CSS):

  • Tailwind CSS + DaisyUI — the stylesheet references DaisyUI theme CSS variables

Quick Start

import { Spreadsheet, type SpreadsheetColumn } from "@polycyphers/spreadsheet";

interface Employee {
  id: number;
  name: string;
  department: string;
}

const columns: SpreadsheetColumn<Employee>[] = [
  { key: "id", label: "ID", width: 60 },
  { key: "name", label: "Name", width: 200 },
  { key: "department", label: "Department", width: 150 },
];

function MyPage() {
  const [data, setData] = useState<Employee[]>([]);

  return (
    <Spreadsheet
      data={data}
      columns={columns}
      persistKey="my-spreadsheet"
    />
  );
}

Features

| Feature | Description | |---------|-------------| | Virtual Scrolling | Renders only visible rows — handles 100k+ rows smoothly | | Column Resize | Drag-to-resize with localStorage persistence, batch resize for multi-selected columns | | Row Height Resize | Drag row handles or double-click auto-fit; batch resize selected rows | | Sorting | Click column headers: ascending → descending → natural order. Blanks sort last; references order 1.9 < 1.10 | | Filtering & Search | Per-column value filters; accent-insensitive search with match count, ↑/↓ navigation and highlighting (filter or highlight mode) | | Cell Selection | Cell, row, column and range selection; Ctrl/Cmd+click adds ranges; Shift+Arrow / Ctrl+Shift+Arrow extend; Ctrl+A; the corner selects every row | | Inline Editing | Text, number, select, checkbox, date, and custom editors; type on a cell to replace it (Excel), F2 to edit, Space toggles checkboxes | | Keyboard | Excel keys: arrows, Ctrl+arrows (jump to block edge), Home/End, PageUp/Down, Tab/Enter, Delete clears, Ctrl+D fill down / duplicate rows, Alt+↑/↓ move rows, Shift+F10 menu — see Keyboard | | Row Operations | Insert above/below, duplicate, delete (confirmed), drag-to-reorder, drag rows onto a sheet tab — you perform them on your data through rowActions | | Column Groups | Banded group headers over adjacent columns, collapsible to a summary column, persisted | | Formats | Declarative column.format (number, currency, percentage, date, zero as dash) plus cellStyle and tooltip callbacks | | Validation | column.validate and plugin validateCell refuse a value; onValidationError reports it | | AutoComplete | Excel-style type-ahead: a text cell completes itself from the entries already in its column | | Excel Import (Full Fidelity) | Import .xlsx preserving fonts, colors, borders, alignment, number formats, merged cells, freeze panes, column widths, row heights, multi-sheet workbooks, and formulas | | Excel Export | Export to .xlsx with styling (via ExcelJS) | | CSV Export | RFC 4180-compliant CSV export | | Formula Engine | 70+ built-in functions, dependency graph, circular reference detection, live evaluation | | Formula Bar | View/edit active cell formula with commit button | | Multi-Sheet Tabs | Automatic sheet tabs from imported workbooks; configurable prop-based tabs | | Cell Merging | Merge cells across columns with O(1) lookup | | Freeze Panes | Freeze left columns and top rows (from props or auto-applied from Excel import) | | Copy / Paste | Ctrl+C/X/V through native clipboard events (no permission prompt). Excel TSV quoting (multi-line cells), HTML table on copy, a single value fills the selection, blocks tile across multiples, rows pasted past the end can be appended | | Undo / Redo | One step per gesture, labelled ("Undo Paste"), recorded by row id so it survives sorting; consumer steps (row insert/delete) join the same stack | | Status Bar | Sum, Avg, Count, Min, Max over every selected range (formula results included); a default column when nothing is selected; density switch | | Plugin System | Every hook is live: click, double-click, key, context menu, value transform, validation, data/column transforms, overlays | | Context Menu | Built-in clipboard and row items plus your own; keyboard-navigable, clamped to the viewport | | Density & Theming | Comfortable / compact rows, accent colour, overlay loading state, row kinds (total, subtotal, section), translatable UI strings | | Session Persistence | Column widths, sort state, filters and collapsed groups saved to storage |

Keyboard

The grid owns one keyboard handler for the whole body; it acts on the active cell, never on whichever DOM element happens to hold focus, and focus follows the active cell (scrolling it into view).

| Keys | Action | |------|--------| | Arrows | Move one cell | | Shift+Arrows | Extend the selection | | Ctrl/⌘+Arrows | Jump to the edge of the filled block (Excel); with Shift, extend to it | | Home / End, Ctrl/⌘+Home / End | Row start/end, sheet start/end | | PageUp / PageDown | Move one screen | | Tab / Shift+Tab, Enter / Shift+Enter | Move right/left, down/up | | Typing | Replace the active cell's content (opens the editor with that key; a custom renderEditor opens by click / F2 instead) | | F2 | Edit the active cell, caret at the end | | Delete / Backspace | Clear every editable cell in the selection (one undo step) | | Space | Toggle a checkbox cell | | Ctrl/⌘+A | Select all | | Ctrl/⌘+C / X / V | Copy / cut / paste | | Ctrl/⌘+Z, Ctrl/⌘+Y or Ctrl/⌘+Shift+Z | Undo, redo | | Ctrl/⌘+D | Duplicate the selected rows when rowActions.duplicate is set, otherwise fill down | | Ctrl/⌘+R | Fill right | | Alt+↑ / Alt+↓ | Move the selected rows (rowActions.reorder) | | Shift+F10 / Menu key | Open the context menu | | Escape | Close the menu, clear the copy marquee, collapse extra ranges |

In an editor: Enter / Tab commit and move. An editor opened by typing or F2 then returns to the grid (Excel); one opened with the mouse continues into the next cell's editor (data-entry chain). Escape cancels. A custom renderEditor gets the same Enter / Tab handling unless it calls stopPropagation on those keys; it keeps Escape for itself.

Delete, Cut and fill skip columns with a custom renderEditor unless the column sets clearable: true. editShortcuts={{ clear: false, fill: false, typeToEdit: false }} switches those shortcuts off (a grid that saves every cell to a server). editShortcuts={{ tilePaste: false }} pastes a copied value or block once at the top-left of the selection instead of repeating it to fill a larger selection. Ctrl/⌘+Z in an editor that has not been typed into undoes in the grid; onKeyDown sees it first (return true to take it), and with history={false} it stays the input's own undo. onKeyDown (and a plugin's onKeyDown) runs before all of this and can take any key by returning true.

Undo / redo

Every gesture is one undo step — a typed edit, a paste, a Delete, a fill — with a label. Steps are recorded against the row id (getRowId), so undo lands on the right row after the view is sorted or filtered.

<Spreadsheet
  onHistoryChange={({ canUndo, canRedo, undoLabel }) => setHistory(...)}  // toolbar buttons
  onUndoRedo={(direction, entry) => persist(entry.changes)}               // save what was replayed
/>

ref.current.batch("Assign profit", () => ref.current.applyChanges(changes)); // one step
ref.current.recordHistory({ label: "Delete 3 rows", undo: restoreRows, redo: deleteAgain });
ref.current.clearHistory();   // a save point (TOMWEB's markSaved)

history={false} turns the grid's history off: Ctrl/⌘+Z and Ctrl/⌘+Y then reach onKeyDown and the page, in an editor too. With sheetTabs, a step remembers its tab: undoing it from another tab calls onSheetTabChange to go back, and replays once that tab's rows are shown.

A page that mounts a fresh grid per tab (key={tab}) keeps its undo stack with history={{ stateKey: "budget-boq" }}: grids that share the key resume the same stacks (for the life of the page). Steps recorded with recordHistory keep the callbacks they were given, so those must still work after a remount.

Rows, menu and drag

The grid never owns your rows: it asks you to change them through rowActions, and offers each action only when you supply its handler.

<Spreadsheet
  getRowId={(r) => r.id}
  rowActions={{
    insert: ({ position, anchorIndex }) => insertAt(position === "above" ? anchorIndex : anchorIndex + 1),
    duplicate: (rows) => duplicate(rows),
    delete: (rows) => remove(rows),              // confirmed first; confirmDelete: false or a function to change that
    reorder: ({ rows, toIndex }) => moveTo(rows, toIndex),   // grip drag + Alt+↑/↓, natural order only
    moveToTab: ({ rows, tabKey }) => moveToTrade(rows, tabKey),   // drop rows on a sheet tab
    requestMoveToTab: (rows) => openTradePicker(rows),            // "Move to…" in the menu
  }}
  features={{ contextMenu: { items: [{ label: "Price details", action: "details" }], onAction: (a, row) => ... } }}
/>

The menu shows Cut / Copy / Paste / Clear contents, then the row items your handlers allow ("Duplicate 3 rows", "Delete 3 rows" follow the selection), then your own items (or getItems(context) to build them from what was right-clicked). Pick built-ins with builtIns: ["grid:copy", …] or hide them with builtIns: false.

rowActions.reorderMenu: true adds "Move up" / "Move down" (Alt+↑/↓) to the menu; they move the selected rows one step through reorder, and are greyed out at the edges, for scattered rows, or while the view is sorted, filtered or searched. They are off by default so a page that adds its own does not show them twice (listing "grid:move-up" / "grid:move-down" in builtIns also turns them on).

features.inlineRowCreation adds a blank row under the data: typing into it, or Enter/↓ past the last row, creates a row from template(); rows pasted past the end are handed to onCreateRows.

Search across tabs

A grid with sheet tabs can search all of them, as TOMWEB's Angular grid did.

  • Scope chip: the search box gets one, reading "All 12 tabs", "This tab" or "3 tabs". It opens a menu with All tabs, This tab only, and a checkbox per tab showing its match count.
  • Tab counts: while a search runs, each tab shows how many rows match.
  • Stepping: Enter / Shift+Enter and the ↑↓ buttons walk the matches tab by tab, opening each tab.
  • Auto-jump: a term with no match in the open tab opens the first tab that has one.
  • Status: the chip reads "3/17 · 4 tabs", with a spinner while the server searches.
  • Empty states: "No matches in any tab", or, on a tab without matches, "No matches in this tab · 5 in other tabs" with Show first match.
<Spreadsheet
  sheetTabs={trades}
  activeSheetTab={tradeKey}
  onSheetTabChange={setTradeKey}
  getRowId={(r) => r.id}
  tabSearch={{
    // tabs whose rows are in memory are searched here...
    getTabRows: (key) => rowsByTrade[key],
    // ...and tabs loaded on demand by the server (debounced, aborted when stale)
    provider: async (term, signal) => {
      const res = await api.search(buildingId, term, { signal });
      return { matches: res.items.map((m) => ({ tabKey: String(m.tradeId), rowId: m.boqId })), truncated: res.isTruncated };
    },
  }}
/>

A page that mounts a fresh grid per tab (key={tab}) passes tabSearch.stateKey (for example, one per building). The search then survives the remount and keeps walking from tab to tab.

The open tab is always searched in the grid itself. Server hits on the open tab stay visible even when the grid does not show the field that matched. An imported workbook's sheets are searched with no setup.

showSearch={false} hides the grid's box, for pages that pass their own search as toolbar, which renders in the same row. showFormulaInput={false} keeps a slim bar with only the toolbar and the search, for read-only views such as reports and imported workbooks.

Freeze panes

Users freeze from the grid. Right-click a column header for Freeze up to “Item”, which freezes through that column, or through the rightmost column of a column selection, and Unfreeze columns. A row number does the same for rows. Freezing is a view setting, so it works in mode="view" too. A freeze that would leave no room to scroll is greyed out.

<Spreadsheet
  pinning={{ columns: 2 }}                 // the page's default
  persistKey="tender-final"                // remembers the user's choice per grid
  onPinningChange={(p) => save(p)}         // { columns, rows } after each change
/>

The user's choice holds until pinning changes value. A fresh object with the same numbers counts as the same value. features={{ freezeMenu: false }} leaves the browser's own menu on headers. Labels: freezeUpToColumn ("Freeze up to “{name}”"), unfreezeColumns, freezeUpToRow ("Freeze up to row {row}"), unfreezeRows. Frozen columns and rows look like the rest of the sheet: no shadow and no heavier line, as in Excel.

Selecting from the headers works as in Excel:

  • Clicking a column's name selects the column, sortable or not.
  • Shift-click extends the column selection; Ctrl/Cmd-click adds a column.
  • A right-click inside a column selection keeps it.
  • A right-click on a row number selects that row, unless it is already part of a row selection.
  • After any of these, the keyboard and Ctrl/Cmd+C act on the selection.

Columns: formats, groups, styles

const columns: SpreadsheetColumn<Line>[] = [
  { key: "qty", label: "Quantity", width: 90, type: "number", editable: true,
    format: { type: "number", decimals: 2 } },
  { key: "base", label: "Base", width: 90, type: "number",
    format: { type: "currency", currency: "MAD" },
    group: { id: "sub-1", label: "Subcontractor A", tone: 2, collapsible: true, summaryKey: "subTotal" } },
  { key: "subTotal", label: "Total", width: 110, type: "number",
    group: { id: "sub-1", label: "Subcontractor A", tone: 2, collapsible: true, summaryKey: "subTotal" },
    cellStyle: (v) => (v < 0 ? { color: "var(--color-error)" } : undefined),
    tooltip: (_v, row) => row.priceSource },
  { key: "unit", label: "Unit", width: 70, type: "select", options: units, editable: true },   // shows labels, stores values
  { key: "up", label: "Unit price", width: 100, type: "number", editable: true,
    validate: (v) => (v < 0 ? "A price cannot be negative" : undefined) },
];

format formats the stored value for display only (sorting, filtering and the editor keep the raw number). decimals fixes the decimals; minDecimals / maxDecimals give a range instead ({ minDecimals: 2, maxDecimals: 4 }: 12 → "12.00", 0.12345 → "0.1235"). Zero shows as "-" by default (zero: "empty" | "value"); percentScale: "whole" reads 10 as 10%. cellStyle is inline, so it always beats the package CSS. hidden: true hides a column without changing formula letters. emptyText sets what an empty cell shows (default "-"; "" for blank).

Typed and pasted numbers accept "1 234,5", "1.234,5", "1,234.5" and "12,5"; the one ambiguous form ("1,234") follows decimalSeparator (default: the browser locale). A number column's parser receives that number when the text reads as one, and the raw text otherwise ("PM"), as does the column when it has no parser; use validate to refuse such text.

Computed columns

{ key: "amount", label: "Amount", width: 120, type: "number",
  value: (r) => (r.qty ?? 0) * r.rate,              // derived, not read from row.amount
  format: { type: "currency", currency: "MAD", minDecimals: 2 } }

value is what the cell shows (through formatter / format / render) and what sort, filters, search, copy, the status bar and totals use. Computed columns are read-only: editing, paste, Delete and fill skip them. Formulas typed in other cells do not see them (they read stored values). readCell(row, column) (exported) returns a cell's value, computed or stored.

Totals row

const columns = [
  { key: "code", label: "Code", width: 90 },
  { key: "desc", label: "Description", width: 240 },
  { key: "qty", label: "Qty", width: 90, type: "number", summary: "sum" },
  { key: "rate", label: "Rate", width: 90, type: "number", summary: "avg", format: { type: "number", decimals: 2 } },
  { key: "amount", label: "Amount", width: 120, value: (r) => r.qty * r.rate, summary: "sum",
    format: { type: "currency", currency: "MAD" } },
  { key: "lines", label: "Lines", width: 70, summary: "count" },
  { key: "best", label: "Best", width: 90, summary: (rows) => bestOf(rows),
    summaryFormat: (v) => <b>{String(v)}</b> },
];

<Spreadsheet columns={columns} data={rows} summaryLabel="Total" />

A column's summary ("sum" | "avg" | "min" | "max" | "count" or (rows) => value) makes the grid draw a totals row under the data, sticky at the bottom and on the same tracks as the header and rows: row number, frozen columns (which stay put), hidden columns and folded groups (a folded group shows its summaryKey column's total), and the actions column. Sum / avg / min / max read numbers, formula results and numeric text included; count counts non-empty cells. The value is shown with summaryFormat (a CellFormat or a function), else the column's format, else as a number with up to two decimals (count: a whole number).

summaryLabel goes in the columns left of the first total (spanning them), or in the row-number cell when the first column has a total. Totals cover the rows on screen (after filters and search); summaryScope="all" adds up every row of data. A summaryRow render prop, when given, is used instead.

A summary function may ignore rows and return a value from the server (summary: () => totals.amount); a summaryFormat function may return JSX, which is rendered as is. A totals cell may hold several lines (an amount with a coloured "+12% vs budget" under it): the row grows to fit, stays sticky, and its frozen and scrolling parts keep the same height. Single-line rows keep the row height.

<Spreadsheet
  columns={columns}
  data={rows}
  summaryLabel="Total"
  summaryLabelColumn="desc"            // label starts here, spans up to the first total
  summaryGutter="Σ"                     // row-number cell of the totals row
  summaryClassName="vo-totals"          // e.g. .vo-totals { --total-row-bg: #f3e8ff; border-top: 2px solid #7c3aed }
  summaryFooter={hidden > 0 ? `${hidden} rows hidden by filters` : undefined}
  onVisibleRowsChange={setShownRows}    // rows on screen after filters, sort, search
/>

| Prop | What it does | |------|--------------| | summaryLabelColumn | Column key the label starts in; it spans up to the first column with a total. Columns before it and the row-number cell stay empty. Default: the first column, or the row-number cell when the first column has a total | | summaryGutter | Content of the totals row's row-number cell (e.g. "Σ"); ignored when the label sits there | | summaryClassName / summaryStyle | Class / inline style on the whole totals row (frozen and scrolling parts, row-number and actions cells). With either set, every cell takes the row's background and font weight | | summaryFooter | A full-width line under the totals row, in the same sticky block; it stays at the left while columns scroll. Also works with a summaryRow render prop, or alone | | onVisibleRowsChange | (rows) => void: the rows on screen after filters, sort and search. Called on mount, then only when the rows or their order change (compared row by row), not on every render |

Background and weight of the totals row:

  • Variables work with either stylesheet: set --total-row-bg (cell background) and --summary-font-weight (default 400) from summaryClassName, e.g. [--total-row-bg:var(--color-base-200)], or in summaryStyle.
  • summaryStyle={{ background }} always wins.
  • Utility classes (bg-base-200, font-medium, border-t-2) win over the grid's own rules with @polycyphers/spreadsheet/css/layered; with /css add ! (!bg-base-200), as for cellClassName.

AutoComplete

Typing in a text cell completes it from the entries already in the same column, the way Excel's AutoComplete for cell values does. A column that already holds Abdo: type ab, and abdo appears with do selected; Tab or Enter accepts it and stores Abdo — the existing spelling, so the column does not end up holding abdo, Abdo and ABDO as three different beneficiaries.

  • The nearest entry wins. Candidates are ordered by distance from the cell being edited, so the completion is the value most recently typed in that column. Requiring a unique match (as Excel does) makes the feature never fire on real data — one near-duplicate, such as Relations Employés beside Relations Employes, is enough to keep every prefix ambiguous forever.
  • Backspace / Delete rejects the completion and leaves the typed characters. Typing on refines it; typing something that no longer matches drops it.
  • The whole column, nearest first. Excel stops at the first blank cell, but a grid that offers blank rows to type into would then give only the first of them any candidates — every row below it sees a blank neighbour and offers nothing. Blanks are skipped instead.
  • Text only — numbers, dates, formulas and select cells are never completed, and neither is a caret parked mid-word (that is an edit, not a new entry). Numeric-looking entries are not candidates either, so a reference column counting 1, 2, … 12 never turns a fresh 1 into the 12 three rows up.
<Spreadsheet data={rows} columns={columns} autoComplete={false} />  // off for the sheet
// Per column. Free-text columns take part by default; a column with a
// `formatter` (display text ≠ stored value) or `options` stays out.
{ key: "beneficiary", label: "Beneficiary", width: 160, editable: true },
{ key: "invoiceNo",   label: "Invoice #",   width: 120, editable: true, autoComplete: false },

Excel Import — Full Fidelity

The spreadsheet can display an imported .xlsx workbook, including supported cell formatting. It is not a pixel-for-pixel Excel renderer: the grid uses its own layout and font by default, and some colors are adjusted for dark themes. Apple Numbers files must be exported as .xlsx before import.

Basic import (matched columns)

const ref = useRef<SpreadsheetRef<MyRow>>(null);

// Trigger from a file input
const handleFile = (e: React.ChangeEvent<HTMLInputElement>) => {
  const file = e.target.files?.[0];
  if (file) ref.current?.importFromExcel(file);
};

Free-form import (auto-generates columns from Excel headers)

When you don't know the column structure ahead of time, use freeFormImport. The spreadsheet will auto-generate column definitions from the Excel header row and display the file exactly as-is.

<Spreadsheet
  data={data}
  columns={columns}
  excelConfig={{ freeFormImport: true }}
  ref={ref}
/>

Raw-grid import (show a workbook as Excel draws it)

For a read-only report — a budget, an IPC, an exported statement — use rawGrid. Every sheet row becomes a grid row under lettered columns (A, B, C…), so merges, headers spread over two rows and blank spacer rows land exactly where they are in Excel.

<Spreadsheet data={[]} columns={[]} mode="view" ref={ref} excelConfig={{ rawGrid: true }} />
// then: await ref.current.importFromExcel(file)

For both rawGrid and freeFormImport:

  • Column widths are converted for the grid's font (Excel measures them in digits of Calibri), and a column too narrow for one of its numbers is widened to it. Amounts are never cut off.
  • Empty cells are blank, not "-".
  • Cells use the grid's font. The workbook's bold, italic and colours are kept; its font family and size only with keepFonts: true, since templates often bake in Times or Cambria.
  • On a dark page the workbook's fills, text and borders are flipped in lightness (hue kept). A pale label fill becomes a dark one with light text, and it follows the theme live.

What is extracted

| Excel property | Extracted | |---|---| | Cell values | ✅ | | Formulas (=SUM(A1:B5), etc.) | ✅ evaluated live by formula engine | | Font (bold, italic, underline, strikethrough, color) | ✅ | | Font family and size | ✅ with excelConfig.keepFonts | | Background fill color | ✅ (lightness-inverted on a dark theme) | | Text alignment (horizontal + vertical) | ✅ | | Word wrap | ✅ | | Borders (top, bottom, left, right — style + color) | ✅ | | Number formats | ✅ positive/negative/zero sections, accounting ((1,234.50), - for zero), literals, [$€-40C], %, #,##0, scaling, scientific | | Merged cells | ✅ | | Freeze panes | ✅ | | Column widths | ✅ converted for the grid's font | | Row heights | ✅ | | All sheets (multi-sheet workbook) | ✅ tabs rendered automatically | | Rich text | ✅ (text content extracted) | | Dates | ✅ |

Types for custom import processing

import type {
  CellStyle,
  CellStyleMap,
  ExcelImportMeta,
  ExcelSheetData,
} from "@polycyphers/spreadsheet";

Exports

Component

import { Spreadsheet } from "@polycyphers/spreadsheet";

Sub-Components

import { SheetTabs, LongTextDialog } from "@polycyphers/spreadsheet";

Hooks

import {
  useVirtualScroll,
  useColumnResize,
  useRowHeightResize,
  useSelection,
  useSorting,
  useFiltering,
  useExcelIO,
  useFormulaEngine,
  usePinning,
  useMergedCells,
  useStatusBar,
  useClipboard,
  useUndoRedo,
  useDynamicColumns,
  useOverflowDetection,
} from "@polycyphers/spreadsheet";

Plugin Utilities

import { usePlugins, createPlugin, composePlugins } from "@polycyphers/spreadsheet";

Feature Hooks

import {
  useHourValidation,
  useCostCodes,
  useInlineRowCreation,
  useContextMenu,
} from "@polycyphers/spreadsheet";

Types

import type {
  // Core
  SpreadsheetColumn,
  SpreadsheetProps,
  SpreadsheetRef,
  SpreadsheetMode,              // "view" | "edit" | "create"
  SpreadsheetVariant,           // "default" | "compact" | "pointage" | "tasks"
  SpreadsheetExcelConfig,
  SpreadsheetFeatures,
  CellEditorType,               // "text" | "number" | "select" | "checkbox" | "date" | "custom"

  // Selection & navigation
  CellPosition,
  SelectionRange,
  SelectionMode,                // "cell" | "row" | "column"
  NavigationDirection,          // "down" | "up" | "right" | "left"
  PersistedSheetState,

  // Sheet tabs
  SheetTab,

  // Excel import
  CellBorder,
  CellStyle,
  CellStyleMap,
  ExcelImportMeta,
  ExcelSheetData,

  // Feature configs
  InlineRowCreationConfig,
  RowHeightResizeConfig,
  ContextMenuConfig,
  ContextMenuItem,
  CostCodeDialogConfig,
  HourValidationConfig,
  HourValidationError,
  CalculatedFieldConfig,
  DirtyTrackingConfig,
  DynamicColumnConfig,
  MultiRowSelectionConfig,
  PositionSummaryConfig,

  // Plugin system
  SpreadsheetPlugin,
  PluginContext,
  CellInfo,
} from "@polycyphers/spreadsheet";

Hook option/result types (UseVirtualScrollOptions, VirtualScrollResult, UseColumnResizeOptions, ColumnResizeResult, UseSelectionOptions, SelectionResult, UseSortingOptions, SortingResult, UseFilteringOptions, FilteringResult, UseExcelIOOptions, ExcelIOResult, UseClipboardOptions, ClipboardResult, UseUndoRedoOptions, UndoRedoResult, CellChange, UndoRedoEntry, UsePinningOptions, PinningResult, PinningConfig, UseMergedCellsOptions, MergedCellsResult, MergedCellRange, MergedCellInfo, UseStatusBarOptions, StatusBarResult, StatusBarStats, UseFormulaEngineOptions, FormulaEngineResult, UseRowHeightResizeOptions, RowHeightResizeResult, UseDynamicColumnsOptions, DynamicColumnsResult, UseHourValidationOptions, UseHourValidationResult, UseCostCodesOptions, UseCostCodesResult, UseInlineRowCreationOptions, UseInlineRowCreationResult, UseContextMenuOptions, UseContextMenuResult, UsePluginsOptions, UsePluginsResult, PointagePluginConfig, TasksPluginConfig) are all exported for advanced composition.

Formula Engine

import {
  FormulaEngine,               // standalone class
  DependencyGraph,             // cell dependency graph
  Errors, FormulaError, isError,
  builtinFunctions, functionCatalog,
  colToNum, numToCol, cellId, parseCellId, adjustFormulaRefs,
} from "@polycyphers/spreadsheet";

import type {
  CellValue,
  CellMatrix,
  CellData,
  CellRef,
  FormulaFunction,
  FunctionInfo,
  ASTNode,
} from "@polycyphers/spreadsheet";

Editor sub-components

import {
  CellTextEditor,
  CellSelectEditor,
  OverflowCellContent,
} from "@polycyphers/spreadsheet";

import type {
  CellTextEditorProps,
  CellSelectEditorProps,
  OverflowCellContentProps,
} from "@polycyphers/spreadsheet";

Utilities

import {
  columnIndexToLetter,
  getValue,
  useOverflowDetection,
} from "@polycyphers/spreadsheet";

Constants

import {
  DEFAULT_ROW_HEIGHT,          // 32
  DEFAULT_OVERSCAN,            // 8
  DEFAULT_MIN_BUFFER_ROWS,     // 8
  DEFAULT_MIN_RENDER_ROWS,     // 30
  DEFAULT_COLUMN_MIN_WIDTH,    // 60
  DEFAULT_COLUMN_MAX_WIDTH,    // 600
} from "@polycyphers/spreadsheet";

License

import {
  setLicense,
  getLicenseStatus,
  isLicensed,
} from "@polycyphers/spreadsheet";

import type { LicenseStatus } from "@polycyphers/spreadsheet";

Props Reference

Core

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | T[] | — | Row objects | | columns | SpreadsheetColumn<T>[] | — | Column definitions | | mode | "view" \| "edit" \| "create" | "view" | Interaction mode | | editContextKey | string \| number \| null | — | Changing this flushes pending edits (e.g. switching record) | | loading | boolean | false | Show loading state | | loadingMode | "replace" \| "overlay" | "replace" | Replace the grid with the spinner, or dim it under an overlay | | loadingConfig | { title?, description? } | — | Loading text | | emptyMessage | string | — | Message shown when data is empty (a filtered-away sheet shows "No rows match" + Clear filters) | | labels | Partial<SpreadsheetLabels> | English | Every built-in UI string (menu, search, status, loading) — see DEFAULT_LABELS | | containerClassName | string | — | Extra class on the outer container | | persistKey | string | — | localStorage/sessionStorage key for column widths, sort, filters | | variant | "default" \| "compact" \| "pointage" \| "tasks" | "default" | Styling variant (pointage, tasks); use density for compact rows | | density | "comfortable" \| "compact" | "comfortable" | Compact rows are 8px shorter with smaller type | | densityToggle | boolean | false | Show the density switch in the status bar (onDensityChange reports it) | | accentColor | string | app --color-primary | Selection / focus colour |

Layout / Virtualization

| Prop | Type | Default | Description | |------|------|---------|-------------| | rowHeight | number \| (row,i)=>number | 32 | Fixed or per-row height | | maxHeight | number \| string | — | Scroll region max height | | overscan | number | 8 | Extra rows rendered outside viewport | | minBufferRows | number | 8 | Minimum buffered rows above/below viewport | | minRenderRows | number | 30 | Minimum rendered rows (prevents underdraw) | | padRows | boolean | true | When false, only data.length rows render — no empty padding rows extend to viewport height | | pinning | {columns?,rows?} | — | Freeze left columns / top rows (users can change it, see Freeze panes) | | onPinningChange | (p: {columns, rows}) => void | — | The user froze or unfroze from the grid | | mergedCells | [{row,col,rowspan,colspan}] | — | Merged cell ranges |

Slots

| Prop | Type | Description | |------|------|-------------| | toolbar | ReactNode | Custom formula bar toolbar | | toolbarLeft | ReactNode | Content pinned to left of toolbar | | formulaBarStart | ReactNode | Content before formula bar | | hideFormulaBar | boolean | Hide the formula bar entirely (legacy — superseded by showFormulaBar) | | showFormulaBar | boolean | Show/hide the formula bar (default true); takes precedence over hideFormulaBar when set | | footer | ReactNode | Footer content below the grid | | slotBelowHeader | ReactNode | Content injected below the column headers | | summaryRow | (rows, ctx?) => ReactNode | Totals/summary row renderer (wins over the built-in totals row) | | summaryLabel | ReactNode | Label of the built-in totals row (columns with summary) — see Totals row | | summaryScope | "visible" \| "all" | Rows the built-in totals cover (default "visible": after filters and search) | | summaryLabelColumn | string | Column the totals label starts in (spans up to the first total) | | summaryGutter | ReactNode | Row-number cell of the built-in totals row (e.g. "Σ") | | summaryClassName | string | Class on the built-in totals row; its background and weight reach every cell | | summaryStyle | CSSProperties | Inline style on the built-in totals row | | summaryFooter | ReactNode | Full-width line under the totals row, inside its sticky block | | onVisibleRowsChange | (rows) => void | Rows on screen (after filters, sort, search) changed | | sheetTabs | SheetTab[] | Multi-sheet tabs | | activeSheetTab | string | Active sheet tab key | | onSheetTabChange | (key) => void | Tab change handler | | onImportedSheetChange | (name, index) => void | The sheet shown from an imported workbook changed (tab click, a search opening it, or a new import → sheet 0) |

Callbacks

| Prop | Type | Description | |------|------|-------------| | onCellChange | (rowIndex, columnKey, value, row) => void | Single cell value changed | | onRowChange | (rowIndex, row) => void | Any cell on a row changed | | onDataChange | (rows) => void | Full dataset changed (paste, import, undo, etc.) | | onRowClick | (row, index) => void | Row clicked | | onRowDoubleClick | (row, index) => void | Row double-clicked | | onRowContextMenu | (row, index, event) => void | Row right-clicked | | onSelectionChange | (cell \| null, row?) => void | Active cell changed | | onSelectionRangeChange | (selection) => void | Every selection change: all ranges, the rows they touch, row ids, whole-row flag | | onCellsChange | (changes, { source, label }) => void | Every gesture's writes once, with old and new values; source is edit / paste / cut / clear / fill / undo / redo / api | | onCellClick / onCellDoubleClick | (info, event) => void \| boolean | Cell clicks; return true from double-click to open your own dialog instead of the editor | | onKeyDown | (event, cell) => boolean \| void | Runs before the grid's keys; return true to take the key | | onCopy / onPaste | (info) => boolean \| void | Return true to take over the clipboard gesture | | onValidationError | (error) => void | A value refused by column.validate or a plugin | | onHistoryChange / onUndoRedo | see Undo / redo | History state; replayed steps | | onSearchChange | (search) => void | Global search text changed — switches search to server mode (the grid then only highlights and navigates matches) |

Row customization

| Prop | Type | Description | |------|------|-------------| | rowClassName | (row, i) => string \| undefined | Extra class per row | | rowStyle | (row, i) => CSSProperties \| undefined | Per-row inline style — wins over the package's own row background regardless of stylesheet load order | | rowNumberRender | (row, i) => ReactNode | Custom row number cell | | rowNumberTitle | (row, i) => string \| undefined | Tooltip for row number | | isCellEditable | (row, column, i) => boolean | Per-cell edit guard (overrides column.editable) | | actionsRender | (row, i) => ReactNode | Right-hand actions column renderer | | actionsColumnWidth | number | Width of actions column | | actionsColumnResizable | boolean | Allow actions column to be resized | | getRowId | (row, i) => string \| number | Stable row identity (undo, row actions, scrollToRowId) | | scrollToRowId | string \| number \| null | Imperatively scroll to a row by id | | rowKind | (row, i) => "total" \| "subtotal" \| "section" \| undefined | Built-in styling for summary rows | | highlightActiveRow | boolean | Tint the active cell's whole row | | rowActions | RowActions<T> | Row insert / duplicate / delete / reorder / move-to-tab — see Rows, menu and drag |

Feature flags

| Prop | Type | Default | Description | |------|------|---------|-------------| | autoComplete | boolean | true | Excel-style type-ahead on text cells (see AutoComplete) | | allowKeyboardNavigation | boolean | true | Arrow/Tab/Enter navigation | | allowColumnResize | boolean | true | Drag-to-resize column widths | | allowFilters | boolean | true | Column filter dropdowns | | allowSorting | boolean | true | Column header sort | | showStatusBar | boolean | false | Sum/Avg/Count/Min/Max bar | | statusBarDefaultColumn | string | — | Column summed in the status bar when nothing is selected | | searchMode | "filter" \| "highlight" | "filter" | Search hides non-matching rows, or keeps them and highlights matches | | history / maxHistory | boolean \| { stateKey } / number | true / 100 | Built-in undo/redo; false leaves Ctrl/⌘+Z/Y to the page; stateKey keeps the stacks across remounts | | editShortcuts | { clear?, fill?, typeToEdit?, tilePaste? } | all true | Switch off Delete, fill (Ctrl/⌘+D/R), type-to-edit, or tiling a paste over a larger selection | | formulas | boolean | true | Evaluate = formulas typed into cells (+ shorthand in number columns only) | | formulaFunctions | Record<string, fn \| { fn, minArgs, maxArgs }> | — | Custom formula functions | | formulaBarReadOnly | boolean | false | Show the formula bar without editing through it | | decimalSeparator | "." \| "," \| "auto" | "auto" | How typed/pasted "1,234" is read | | tabSearch | { getTabRows?, provider?, defaultScope?, stateKey? } | — | Search across sheet tabs (see Search across tabs) | | showFormulaInput | boolean | true | false: a slim bar with only the toolbar and the search box | | showSearch | boolean | true | The grid's own search box. Turn it off when the page passes its own search as toolbar (same row) | | zeroDisplay | "dash" \| "value" | "value" | "dash": number columns show zero as "-" (Excel accounting), also when a formatter prints "0" / "0.00". Display only. A column's own zeroDisplay wins | | collapsedGroups / onCollapsedGroupsChange | string[] / fn | — | Control collapsed column groups (otherwise kept and persisted by the grid) |

Excel I/O

| Prop | Type | Description | |------|------|-------------| | excelConfig.fileName | string | Download filename for export | | excelConfig.sheetName | string | Sheet name for export | | excelConfig.freeFormImport | boolean | Auto-generate columns from Excel headers | | excelConfig.rawGrid | boolean | Show each sheet as Excel draws it: lettered columns, every row (see "Raw-grid import") | | excelConfig.keepFonts | boolean | Keep the workbook's font family and size on import (default: the grid's font) | | excelConfig.exportBuilder | fn | Custom workbook builder | | excelConfig.importParser | fn | Custom import parser (bypasses fidelity import) |

Extensibility

| Prop | Type | Description | |------|------|-------------| | plugins | SpreadsheetPlugin<T>[] | Lifecycle/event/render plugin array | | features | SpreadsheetFeatures<T> | Feature config bag: inlineRowCreation, rowHeightResize, contextMenu, multiRowSelection, costCodeDialog, hourValidation, positionSummary, calculatedFields, dirtyTracking, dynamicColumns | | aiId | string | AI integration id (for external assistants) |

SpreadsheetRef methods

const ref = useRef<SpreadsheetRef<T>>(null);

ref.current.exportToExcel()         // download .xlsx
ref.current.importFromExcel(file)   // load file with full fidelity
ref.current.exportToCSV()           // download .csv
ref.current.undo()
ref.current.redo()
ref.current.getData()               // get current rows
ref.current.resetColumnWidths()

// History
ref.current.canUndo() / canRedo() / getHistoryState()
ref.current.clearHistory()          // save point
ref.current.batch(label, fn)        // one undo step
ref.current.recordHistory({ label, undo, redo })

// Writes & selection
ref.current.applyChanges([{ rowIndex, columnKey, value }], { label })
ref.current.getSelection()          // { active, ranges, rowIndexes, rows, rowIds, wholeRows }
ref.current.selectCell(row, key) / selectRange(range) / selectRows([i…]) / selectAll() / clearSelection()
ref.current.scrollToRow(index | { id }, "nearest")
ref.current.focus() / startEditing(row, key) / stopEditing()
ref.current.copy() / cut() / paste() / clearSelectedCells()
ref.current.getVisibleRows() / setSearch(term) / clearFilters() / setSort(key, dir)
ref.current.getFormulaEngine()

Plugin System

Plugins implement the SpreadsheetPlugin<T> interface. Every hook is optional — implement only what you need — and every hook is wired (before 1.2 only the lifecycle hooks and renderFooterExtension ran). Return true from an event hook to prevent the default behavior. A plugin is mounted once; its context always reads the current grid state.

Plugin lifecycle & hook surface

| Hook | Signature | Purpose | |------|-----------|---------| | onMount | (context) => void \| (() => void) | Mount hook; return function runs on unmount | | onUnmount | () => void | Explicit unmount callback | | onDataChange | (data, prevData) => void | Fires when the row array reference changes | | renderCellOverlay | (cell) => ReactNode | Overlay UI rendered above a cell | | renderRowOverlay | (row, i) => ReactNode | Overlay rendered per row | | renderToolbarExtension | (context) => ReactNode | Injects content into the formula bar toolbar | | renderFooterExtension | (context) => ReactNode | Injects content into the footer area | | onCellClick / onCellDoubleClick | (cell, event) => boolean \| void | Return true to prevent default | | onCellChange | (cell, newValue, prevValue) => any | Return a value to transform the committed value | | onRowClick | (row, i, event) => boolean \| void | Return true to prevent default | | onKeyDown | (event, cell) => boolean \| void | Return true to prevent default | | onContextMenu | (row, i, event) => boolean \| void | Return true to prevent default | | transformData | (data) => data | Reorder or drop rows for display. Return the same row objects (not copies) so edits land on the right row | | transformColumns | (columns) => columns | Last-mile column transform | | validateCell | (cell, newValue) => { valid, message? } | Veto a cell edit |

PluginContext<T> provides { data, columns, mode, selectedCell, selectionRange, updateCellValue, setSelectedCell, getRow, getColumn, forceUpdate }.

Building a plugin

import { createPlugin, type SpreadsheetPlugin } from "@polycyphers/spreadsheet";

const uppercasePlugin: SpreadsheetPlugin<MyRow> = createPlugin({
  name: "uppercase-names",
  onCellChange: (cell, newValue) => {
    if (cell.columnKey === "name" && typeof newValue === "string") {
      return newValue.toUpperCase();
    }
  },
});

<Spreadsheet data={rows} columns={cols} plugins={[uppercasePlugin]} />

Combine plugins with composePlugins(a, b, c).

Built-in plugins

| Plugin | Factory | Exported columns | Use case | |--------|---------|------------------|----------| | Pointage | createPointagePlugin(config) | POINTAGE_COLUMNS | Hour validation, bulk regular hours, position summary, salary type grouping | | Tasks | createTasksPlugin(config) | TASK_COLUMNS | Inline row creation, context menu, row height resize, status/category dropdowns |

Config types: PointagePluginConfig, TasksPluginConfig.

Variants

The variant prop selects a styling variant (row density is the density prop):

| Variant | Description | |---------|-------------| | "default" | Standard spreadsheet | | "compact" | No effect of its own — use density="compact" | | "pointage" | Optimized for attendance/hours entry | | "tasks" | Optimized for task management |

Formula Engine

Supports 70+ Excel-compatible functions. Introspect the full set at runtime via the exported functionCatalog.

Math: SUM, AVERAGE, COUNT, COUNTA, MIN, MAX, ROUND, ROUNDUP, ROUNDDOWN, CEILING, FLOOR, ABS, POWER, SQRT, MOD, INT, PRODUCT, PI, RAND, SIGN
Statistical: MEDIAN, MODE, STDEV, VAR, LARGE, SMALL, RANK, PERCENTILE
Logical: IF, IFS, AND, OR, NOT, IFERROR, SWITCH
Text: CONCATENATE, LEFT, RIGHT, MID, LEN, UPPER, LOWER, TRIM, SUBSTITUTE, FIND, SEARCH, TEXT, VALUE
Date: TODAY, NOW, DATE, YEAR, MONTH, DAY, DATEDIF, DAYS
Lookup: VLOOKUP, HLOOKUP, INDEX, MATCH
Financial: PMT, FV, PV, RATE
Information: ISBLANK, ISERROR, ISNUMBER, ISTEXT, SUMIF, COUNTIF, AVERAGEIF

Cell references support absolute ($A$1), relative (A1), and mixed forms.

Consumer integration

Required app setup

  1. Install the package — npm install @polycyphers/spreadsheet.
  2. Install peer deps in the app — react >= 19.2.5, react-dom >= 19.2.5, and exceljs >= 4.4.0 if Excel I/O is used.
  3. Import the stylesheet once in the app entry:
    // main.tsx
    import "@polycyphers/spreadsheet/css";
  4. Tailwind + DaisyUI must be configured in the host app — the stylesheet consumes DaisyUI theme CSS variables (e.g. --b1, --bc, --p).

Vite alias — live source development

Use this pattern in a consumer's vite.config.ts to skip the build step while iterating on the package. Verified in PORTAL/Claims/vite.config.ts:

import path from "path";

const spreadsheetSourceRoot = path.resolve(
  __dirname,
  "../../karament-spreadsheet/src"
);

export default defineConfig({
  resolve: {
    dedupe: ["react", "react-dom", "@iconify/react"],
    alias: [
      { find: "@polycyphers/spreadsheet/css", replacement: path.join(spreadsheetSourceRoot, "spreadsheet.css") },
      { find: "@polycyphers/spreadsheet",      replacement: path.join(spreadsheetSourceRoot, "index.ts") },
    ],
  },
  optimizeDeps: {
    exclude: ["@polycyphers/spreadsheet"],
  },
});

Key points:

| Setting | Why | |---------|-----| | resolve.dedupe: ["react", "react-dom", "@iconify/react"] | Prevents duplicate React copies (needed for hooks to work when package is resolved from source) | | alias for @polycyphers/spreadsheet | Points import directly at src/index.ts — no rebuild to pick up edits | | Separate alias for /css | CSS lives outside the JS entry; must be aliased explicitly | | optimizeDeps.exclude | Keeps Vite from pre-bundling the package when using the alias |

Without the alias, consumers just use the published dist/ output — no special config required.

Styling: cascade layer

@polycyphers/spreadsheet/css is unlayered, so it beats Tailwind 4 / DaisyUI utilities (which live in @layer utilities): cellClassName="bg-red-50" loses to the cell's own background unless it uses !. To let utilities win, import the layered build instead (or, in Tailwind 4 CSS, @import "@polycyphers/spreadsheet/css" layer(components);):

import "@polycyphers/spreadsheet/css/layered";

It puts the stylesheet in @layer components.polycyphers-spreadsheet after declaring Tailwind 4's order (theme, base, components, utilities), so wherever it is imported it sits above preflight and below utilities. What changes:

  • Utility classes (and any unlayered page CSS) now beat the grid's styles of the same property, whatever their specificity — cellClassName, rowClassName and containerClassName work without !. A page with broad unlayered rules (button { … }, input { … }, div { … }) will also restyle the grid.
  • The other way round for !important: the grid's few !important rules (the selection outline and tint, the editor's font) now beat ! utilities.
  • The cell editor's input reset stays outside the layer, so DaisyUI's .input / .select still do not restyle it.
  • Inline cellStyle / rowStyle win either way.

Without such overrides a Tailwind 4 + DaisyUI page looks the same with either file.

Adopter gotchas

  • Do not import @polycyphers/spreadsheet/css inside the package's own JS — imports happen once in the app entry, never transitively from the library. Breaking this splits the CSS out of the single-file bundle.
  • React version mismatch is the #1 failure mode when using the Vite alias (duplicate copies → Invalid hook call). Always add resolve.dedupe.
  • ExcelJS is optional but peerDependenciesMeta marks it so — the app gets a bundler warning if it's missing and Excel I/O is called. Install it if importFromExcel / exportToExcel are used.
  • persistKey writes column widths, sort state, and filters to storage. Use a unique key per page; reusing a key across pages cross-contaminates state.
  • editContextKey must be bumped when the underlying record changes (e.g. navigating from record A to record B with the same page mounted). Without it, pending edits from A will flush into B.
  • Merged cells and pinning from Excel import override any mergedCells / pinning props on the component — imported files are treated as authoritative.
  • CSS is one file (spreadsheet.css, not code-split). Size is predictable; import it only once.
  • Icons — the package ships its own @iconify/react + @iconify/icons-lucide runtime dependencies. If the app also uses Iconify, add it to resolve.dedupe (see above) to avoid two registries.
  • Free-form Excel import re-generates columns from the file header row — any column props you pass in are discarded when excelConfig.freeFormImport: true.

Porting from TOMWEB's app-sam-table-spreadsheet

| sam-table (Angular) | @polycyphers/spreadsheet | |---|---| | [sheets] + [activeSheetId] + (sheetChange) | data for the active sheet + sheetTabs / activeSheetTab / onSheetTabChange (selection is cleared and scroll is remembered per tab) | | sheet.itemCount / sheet.badge | SheetTab.count / SheetTab.badge | | [loading] + [loadingConfig] | loading + loadingConfig (loadingMode="overlay" keeps the grid visible) | | config.readOnly | mode="view" | | config.enableUndoRedo + (journalChange) + (undoStateChange) + markSaved() | built-in history + onUndoRedo + onHistoryChange + ref.clearHistory() | | runAsSingleUndoStep(label, fn) | ref.batch(label, fn) | | journal row-insert / row-delete / row-move | your rowActions handler + ref.recordHistory({ undo, redo }) | | (cellEdit) | onCellsChange (old/new values, source) or onCellChange | | (rowAction) insert / duplicate / delete, disableRowInsert / disableRowDelete | rowActions.insert / duplicate / delete (omit one to hide it) | | enableRowReorder + (rowReorder), Alt+↑/↓ | rowActions.reorder | | enableRowDragToSheet + (rowDroppedOnSheet) + (moveRowsToSheetRequest) | rowActions.moveToTab + rowActions.requestMoveToTab | | (cellSelect) / (rowSelect) / (selectionChange) | onSelectionChange / onSelectionRangeChange (wholeRows, rowIds) / onCellClick | | (cellDoubleClick), (formulaDialogRequest) | onCellDoubleClick (return true to keep the editor closed) | | (contextMenuAction) | features.contextMenu.onAction | | column.format (number, currency, percentage, date, decimals, showZeroAsDash) | column.format (zero, percentScale: "whole" for whole-number percentages) | | column.validation.type: "dropdown" + options | type: "select" + options (a value outside the list is kept) | | cell.style / column.style | column.cellStyle / rowStyle | | cell.tooltip | column.tooltip | | column.group (tone, collapsible, summary) | column.group (tone, collapsible, summaryKey) | | total / subtotal / section-header rows | rowKind | | config.frozenColumns / frozenRows | pinning={{ columns, rows }} | | config.statusBarConfig.defaultSumColumn | statusBarDefaultColumn | | config.highlightRowOnCellSelect | highlightActiveRow | | config.formulaBarReadOnly | formulaBarReadOnly | | densityMode / accentColor | density (+ densityToggle) / accentColor (any CSS colour) | | [searchProvider] (server search) | onSearchChange (the grid still counts and walks the matches it holds) | | enableInlineEditing add-row placeholder | features.inlineRowCreation | | footerHelpTooltip / customActions / customControls | footer / toolbar / toolbarLeft slots (render your own buttons) | | enablePagination / rowsPerPage | not needed — rows are virtualised |

Updating

When a new version is tagged:

npm install @polycyphers/spreadsheet

Development

git clone https://github.com/melejel2/karament-spreadsheet.git
cd karament-spreadsheet
npm install
npm run build        # Build dist/
npm run dev          # Watch mode
npm run type-check   # TypeScript validation

License

Commercial. See LICENSE.md and EULA.md. Trial + pricing at packages.polycyphers.com/spreadsheet.

Release maintenance: keep PKG_VERSION in src/Spreadsheet.tsx synchronized with package.json so version-scoped license tokens are checked against the published version.


Polycyphers © 2025-2026 | All rights reserved