Named Ranges

Names replace repeated coordinates and values with business terms. FormulaPlugin installs or reuses the named-range runtime automatically. Register NamedRangesPlugin explicitly when your application needs its runtime methods, events, or Name Manager.

Names are case-insensitive. A name must start with a letter, underscore, or backslash; it cannot contain spaces, resemble an A1 cell such as B12, or match a FormulaJS function. Formula names must store a value beginning with =.

1. Named constant

import { FormulaPlugin } from '@revolist/revogrid-pro';

grid.plugins = [FormulaPlugin];
grid.columns = [
  { prop: 'subtotal', name: 'Subtotal' }, // A
  { prop: 'total', name: 'With tax' },   // B
];
grid.formulaNames = {
  names: [{ name: 'TaxRate', kind: 'constant', value: 0.2 }],
};
grid.source = [{ subtotal: 100, total: '=A1*(1+TaxRate)' }];

Expected result: B1 displays 120. Changing TaxRate to 0.25 and reassigning grid.formulaNames recalculates B1 to 125.

2. Named range

grid.columns = [
  { prop: 'label', name: 'Period' }, // A
  { prop: 'amount', name: 'Amount' }, // B
];
grid.formulaNames = {
  names: [{ name: 'SalesRevenue', kind: 'range', ref: 'B1:B3' }],
};
grid.source = [
  { label: 'Jan', amount: 100 },
  { label: 'Feb', amount: 200 },
  { label: 'Mar', amount: 300 },
  { label: 'Total', amount: '=SUM(SalesRevenue)' },
];

Expected result: B4 displays 600.

Note

Revenue is a FormulaJS function name, so this guide uses SalesRevenue. Name validation rejects function-name collisions instead of creating an ambiguous expression.

3. Named formula

Build on the preceding range and add a reusable formula:

grid.formulaNames = {
  names: [
    { name: 'TaxRate', kind: 'constant', value: 0.2 },
    { name: 'SalesRevenue', kind: 'range', ref: 'B1:B3' },
    {
      name: 'AfterTaxSales',
      kind: 'formula',
      value: '=SUM(SalesRevenue)-SUM(SalesRevenue)*TaxRate',
    },
  ],
};

grid.source = [
  { label: 'Jan', amount: 100 },
  { label: 'Feb', amount: 200 },
  { label: 'Mar', amount: 300 },
  { label: 'Net', amount: '=AfterTaxSales' },
];

Expected result: B4 displays 480. Circular names, including two formula names that refer to each other, resolve to #ERROR.

4. Workbook and sheet scope

An unqualified name first uses the active sheet’s local definition, then the workbook definition. Qualify a name to bypass that precedence.

grid.formulaNames = {
  activeSheetId: 'Q4',
  names: [
    { name: 'TaxRate', scope: 'workbook', kind: 'constant', value: 0.2 },
    { name: 'TaxRate', scope: 'sheet', sheetId: 'Q4', kind: 'constant', value: 0.25 },
    { name: 'TaxRate', scope: 'sheet', sheetId: 'Q1', kind: 'constant', value: 0.1 },
  ],
};
grid.columns = [
  { prop: 'local', name: 'Local' },
  { prop: 'global', name: 'Workbook' },
  { prop: 'q1', name: 'Q1' },
];
grid.source = [{
  local: '=TaxRate',
  global: '=workbook!TaxRate',
  q1: '=Q1!TaxRate',
}];

Expected result: A1 displays 0.25, B1 displays 0.2, and C1 displays 0.1. Duplicate display names are allowed across distinct scopes, but not twice within the same scope.

Runtime management

Register the runtime explicitly, then retrieve it with a typed guard:

import {
  FormulaPlugin,
  NamedRangesPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [NamedRangesPlugin, FormulaPlugin];

const plugins = await grid.getPlugins();
const namedRanges = plugins.find(plugin => plugin instanceof NamedRangesPlugin);
if (!namedRanges) throw new Error('NamedRangesPlugin is not mounted');

const validation = namedRanges.validateFormulaNameRef({
  name: 'ForecastRange',
  kind: 'range',
  ref: 'D2:D20',
});
if (!validation.valid) throw new Error(validation.errors.join('; '));

namedRanges.upsertFormulaName({
  name: 'ForecastRange',
  kind: 'range',
  ref: 'D2:D20',
});
await namedRanges.jumpToFormulaName('ForecastRange');
namedRanges.deleteFormulaName('ForecastRange', 'workbook');

Listen on the grid for formulanameschange, formulanamevalidationerror, and formulanamejump when application UI needs to react to those operations.

const onNamesChange = (event: CustomEvent) => console.log(event.detail);
grid.addEventListener('formulanameschange', onNamesChange);

// Teardown
grid.removeEventListener('formulanameschange', onNamesChange);

The bundled manager provides create, edit, delete, validation, and range navigation:

import { defineFormulaNameManager } from '@revolist/revogrid-pro';

const panel = document.querySelector<HTMLElement>('#name-manager');
if (panel) defineFormulaNameManager(panel, grid, { pageSize: 50 });

Reference updates and immutable data

With autoUpdateRefs enabled (the default), deterministic row/column insertions and deletions update range refs, named formulas, and raw source formulas. If row 1 is inserted before B1:B3, the name becomes B2:B4; deleting a referenced row shrinks the range. Set autoUpdateRefs: false to preserve authored strings unchanged.

Pinning, sorting, filtering, hiding, and other presentation changes never rewrite refs. Applications that replace every row with immutable clones may set rowIdProp to a stable, present, unique record key so surviving rows retain their authored identity. See A1 References and Autofill for the full structural model.

Putting names into an application

Add only the surface the user needs: Formula Bar for direct editing, Name Manager for registry maintenance, dependency highlighting for inspection, named dropdowns for list choices, and conditional formulas for styling. Each integration has an independent copyable example in Formula UI and Helpers.

Next steps

Previous: A1 References and Autofill · Next: Formula UI and Helpers · Deeper reference: Formula API