Named ranges

Name ranges and use them in formulas

Named ranges let you give a friendly name to a cell range, scalar value, formula, or LAMBDA — and reference it from any formula. Spreadsheet supports four shapes that all interop with Excel:

Shape	Example	Use it as
Range-typed	MyRange = A1:B10	=SUM(MyRange)
Static value	MyVal = 42	=MyVal*2 — scalar returned directly
Formula-typed	MyVar = =SUM(A1:A10)	=MyVar — virtual cell, recomputes when precedents change
Named LAMBDA	MyFunc = =LAMBDA(x, x*2)	=MyFunc(5) returns 10

Basic usage

Pass namedRanges to useSpreadsheetState + CanvasGrid. The hook returns CRUD callbacks the UI can wire to:

import {
  SpreadsheetProvider,
  CanvasGrid,
  NamedRange,
} from "@rowsncolumns/spreadsheet";
import { useState } from "react";
import {
  useSpreadsheetState,
  NamedRangeEditor,
} from "@rowsncolumns/spreadsheet-state";

const MySpreadsheet = () => {
  const [namedRanges, onChangeNamedRanges] = useState<NamedRange[]>([]);
  const {
    onCreateNamedRange,
    onUpdateNamedRange,
    onDeleteNamedRange,
    onRequestDefineNamedRange,
    onRequestUpdateNamedRange,
  } = useSpreadsheetState({
    namedRanges,
    onChangeNamedRanges,
  });

  return (
    <>
      <CanvasGrid namedRanges={namedRanges} />
      <NamedRangeEditor
        namedRanges={namedRanges}
        onCreateNamedRange={onCreateNamedRange}
        onUpdateNamedRange={onUpdateNamedRange}
        onDeleteNamedRange={onDeleteNamedRange}
      />
    </>
  );
};

const App = () => (
  <SpreadsheetProvider>
    <MySpreadsheet />
  </SpreadsheetProvider>
);

The NamedRangeEditor component handles all four shapes — the user picks "Text or Formula" in the editor, and the engine resolves the type at evaluation time.

Scoping — workbook vs sheet

Each name is either workbook-scoped (visible everywhere) or sheet-scoped (visible only on that sheet). When a sheet-scoped name shadows a workbook-scoped one with the same display name, Excel's lookup rules apply: sheet-scope wins first, then falls back to workbook scope.

const namedRanges: NamedRange[] = [
  // Workbook-scoped — visible everywhere
  { namedRangeId: "1", name: "Tax", value: "=0.08" },
  // Sheet-scoped — only on sheetId 1; overrides Tax on that sheet
  { namedRangeId: "2", name: "Tax", value: "=0.20", sheetId: 1 },
];

// On sheet 1: `=Tax` → 0.20
// On any other sheet: `=Tax` → 0.08

Formula-typed names — the virtual-cell model

When value is a formula (=SUM(A1:A10), =price * 1.08, etc.), the name becomes a first-class node in the calculation DAG. Cell formulas that reference the name get a real DAG input edge to that node, so the unified topological sort recomputes them whenever the named range's value changes.

const namedRanges: NamedRange[] = [
  { namedRangeId: "1", name: "price", value: "=A1" },
  { namedRangeId: "2", name: "fullPrice", value: "=price * 1.08" },
];

// Cell B1: =fullPrice
// When A1 changes → price recomputes → fullPrice recomputes → B1 recomputes

Order of registration doesn't matter — the engine does a two-pass batch register so fullPrice can reference price even if it's listed first.

Named LAMBDAs — callable names

Set value to a LAMBDA expression and the engine treats the name as a callable function:

const namedRanges: NamedRange[] = [
  {
    namedRangeId: "1",
    name: "Commission",
    value: "=LAMBDA(sales, IF(sales > 1000, sales*0.1, sales*0.05))",
  },
];

// =Commission(500)  → 25
// =Commission(5000) → 500

Three resolution shapes are accepted on onVariable: a pre-built lambda value, a {ref, value} wrapper, or the raw "=LAMBDA(...)" source string (parsed + applied at call time). The fast-formula-parser engine handles all three identically.

JSON round-trip

The DAG including all name → dependent edges is serializable. Dag.toJSON and Dag.fromJSON round-trip both directions of the cell ↔ named-range edges, so a rehydrated calculator matches the in-memory model exactly.