Named Ranges

Since v1.4.0 you can assign a defined name to a cell or range and reference it in formulas — =SUM(Sales) instead of =SUM(Sheet1!B2:B13). Names can be workbook-wide or scoped to a single sheet.

Note: Defining names is a Pro feature. Reading names (getName, getNames) and importing them from xlsx work in Lite, so names authored in Pro — or read from a file — resolve in formulas in the free tier.

Defining a name

Names live on the instance (workbook), not a single worksheet. Pass a name and an address; scope and a comment are optional:

import { createReogrid } from '@reogrid/pro'

const grid = createReogrid({ workspace: '#app' })

// Workbook-scoped (default) — visible from every sheet
grid.defineName('Sales', 'Sheet1!B2:B13')
grid.defineName('Tax', 'Sheet1!$F$1', 'workbook', 'Consumption tax rate')

// Sheet-scoped — shadows a workbook name of the same identifier on that sheet
grid.defineName('Region', 'A1:A20', 'Summary')

defineName(name, address, scope?, comment?). The address is a cell/range reference (Sheet1!A1:B10, A1, 'My Sheet'!$C$3). scope is 'workbook' (default) or a sheet name.

Managing names

grid.getName('Sales')            // 'Sheet1!$B$2:$B$13' — absolute address, or undefined
grid.getNames()                  // DefinedNameInfo[] across the workbook
grid.getNames('Summary')         // only the given scope
grid.removeName('Tax')           // returns true when one was removed

A DefinedNameInfo is { name, scope, address, comment? }. When a name’s target has been destroyed, its address reads #REF!.

Workbook vs sheet scope

A sheet-scoped name takes precedence over a workbook name of the same identifier when a formula on that sheet is evaluated.

Using names in formulas

Reference a name anywhere a range or value is expected:

grid.defineName('Sales', 'Sheet1!B2:B13')
grid.defineName('Tax', 'Sheet1!$F$1')

grid.worksheet.cell('E1').value = '=SUM(Sales)'   // range name
grid.worksheet.cell('E2').value = '=E1*Tax'       // single-cell name as a scalar
grid.worksheet.cell('E3').value = '=AVERAGE(Sales)'

#REF! behavior

Defined names track their targets. If the rows/columns a name points to are deleted, the name resolves to #REF! and any formula using it evaluates to #REF! — the same behavior as a direct broken reference. Redefine the name (or restore the target) to fix it:

grid.defineName('Sales', 'Sheet1!B2:B20') // point it at the new range

xlsx round-trip

Names serialize to and load from <definedNames>, so =SUM(Sales) survives a save to Excel and back. They also round-trip through ReoGrid JSON. Importing a workbook brings its defined names along, and they resolve in formulas even in Lite.

Related

• Formula Engine — the full formula language that consumes names.
• Multi-Sheet Workbook — how names interact with cross-sheet references.
• XLSX Import & Export — how defined names travel with the file.