Spreadsheet Grid

A small spreadsheet you can type straight into: arrow keys move, Shift + arrows extend the selection, double-click or Enter edits, and the formula bar on top shows the active cell's raw content (a formula shows as =B2*C2, not its result). A hand-written formula engine supports arithmetic, cell references, ranges and SUM / AVERAGE / MIN / MAX / COUNT, and uses a dependency graph to recalculate only the cells that are affected. The selection box springs to its new position, and after a commit the edited cell flashes together with every formula cell that depends on it, so you can see exactly what a change ripples into. The first key of an IME such as Zhuyin or Cangjie starts editing directly and is never lost.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<SpreadsheetGrid/>

    </div>
  );
}

Installation

Usage

import * as React from "react";
import { SpreadsheetGrid } from "@/components/ui/spreadsheet-grid";

export function Budget() {
  const [cells, setCells] = React.useState<Record<string, string>>({
    A1: "品項",
    B1: "數量",
    C1: "單價",
    D1: "小計",
    A2: "便當",
    B2: "32",
    C2: "110",
    D2: "=B2*C2",
    A3: "合計",
    D3: "=SUM(D2:D2)",
  });

  return (
    <SpreadsheetGrid
      rows={20}
      cols={6}
      value={cells}
      onChange={setCells}
      columnWidths={{ A: 140 }}
      frozenRows={1}
      frozenCols={1}
      onSelectionChange={(s) => console.log(s.range, s.display)}
    />
  );
}

Props

SpreadsheetSelection

The SpreadsheetCellValue, SpreadsheetErrorCode and SpreadsheetGridProps types are exported by name as well.

CSS variables

How it works

• Formulas: start with =. Numbers, cell references ($ absolute markers are accepted and ignored), ranges like A1:B3, + - * /, parentheses and unary minus are supported, plus SUM, AVERAGE, MIN, MAX and COUNT (case-insensitive, comma-separated arguments). Text and blanks inside ranges are skipped; in arithmetic a blank counts as 0 and text returns #VALUE!
• Error codes: a reference outside the grid is #REF!, division by zero is #DIV/0!, an unknown function or name is #NAME?, a circular reference is #CYCLE!, and a syntax error is #ERROR!; errors propagate to dependent cells and render in rose
• Only affected cells recalculate: the component keeps a dependency graph and, on change, recalculates only the edited cells and the formulas that transitively depend on them; the whole sheet is rebuilt only when rows / cols change. Parsed formulas are cached by their raw string
• Keyboard: arrows move, Shift + arrows extend, Ctrl/⌘ + arrows jump to the edge, Home / End go to the start / end of the row; Tab / Shift+Tab move right / left; Enter starts editing, and while editing Enter commits and moves down (Shift+Enter moves up); F2 edits; typing overwrites; Esc cancels; Delete / Backspace clears the selection; Ctrl/⌘+A selects all
• Copy and paste: Ctrl/⌘+C copies the selected range's raw content as TSV (formulas are copied as formula text, without shifting relative references); Ctrl/⌘+V pastes TSV from the top-left of the selection and trims anything beyond the grid. It uses clipboardData on the copy / paste events, so no clipboard permission is needed
• Mouse: click to select, drag or Shift + click to extend, double-click to edit; click a column header to select the column, a row number to select the row, and the top-left corner to select all
• Freezing: the column header and row numbers are always pinned; frozenRows / frozenCols pin the first N data rows / columns as well
• Performance: every cell is rendered directly, so keep rows × cols within about 2,000 cells; paginate larger data outside the component — it does not virtualize
• Syncing columnWidths: dragged widths are kept inside the component; passing a new columnWidths object resets them to the prop, so keep it in state or a constant rather than creating a new object every render

Accessibility

• The grid is role="grid" with aria-rowcount / aria-colcount / aria-multiselectable; each row is role="row", column headers are role="columnheader", row numbers are role="rowheader", and cells are role="gridcell" with aria-rowindex, aria-colindex and aria-selected
• Roving tabindex: only the active cell has tabIndex=0, so tabbing into the grid lands on it; focus is handed to a hidden input inside the active cell whose aria-label reads "Cell B3: value"
• The formula bar input is labelled "Cell B3 content"; Shift+Tab in the first column returns to the formula bar, and Tab in the last column leaves the grid
• Every Enter commit ignores keys pressed during IME composition (including Safari's keyCode 229), so picking a Zhuyin candidate never submits by accident; typing through an IME enters edit mode on compositionstart
• The status bar (range, sum, average, count) is aria-live="polite"
• When the user's system has Reduce Motion turned on, the selection box jumps straight to its new position without the spring, and the post-commit flash is not shown