Formula UI and Helpers

FormulaPlugin owns calculation. The integrations below are optional and independently configurable.

1. Formula Bar

<div id="formula-bar"></div>
<revo-grid id="orders"></revo-grid>

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

const grid = document.querySelector<HTMLRevoGridElement>('#orders');
const host = document.querySelector<HTMLElement>('#formula-bar');
if (!grid || !host) throw new Error('Formula UI hosts are missing');

grid.plugins = [FormulaBarPlugin, FormulaPlugin];
grid.columns = [
  { prop: 'qty', name: 'Quantity' },
  { prop: 'price', name: 'Price' },
  { prop: 'total', name: 'Total' },
];
grid.formulaBar = { host };
grid.source = [{ qty: 3, price: 10, total: '=A1*B1' }];

// Remove the external editor without removing Formula.
grid.formulaBar = null;

Expected result: focusing C1 shows raw =A1*B1 in the Formula Bar while C1 renders 30. Text and number drafts commit on Enter; dropdown, boolean, and date/time choices commit when selected.

The adaptive host selects a formula/text, number, percent, dropdown, boolean, date/time, or fallback cell editor. Existing text-only integrations may pass { el: input } instead. See the Formula API for custom adapters and the typed getFormulaBarState() / setFormulaBarValue() runtime.

2. Dependency highlighting

Formula installs or reuses FormulaDependencyHighlightPlugin. By default it highlights references only while a formula is being edited. Set highlightOnFocus: true to also highlight when a formula cell is merely focused.

grid.plugins = [FormulaPlugin];
grid.formulaDependencyHighlight = {
  highlightOnFocus: true,
  includeNamedRanges: true,
  dependencyClass: 'formula-source-cell',
  formulaCellClass: 'formula-active-cell',
  dependencyColors: ['#2563eb', '#dc2626', '#16a34a'],
};

Expected result: focusing C1 with raw =A1*B1 marks A1 and B1 as dependencies and C1 as the active formula cell. Set grid.formulaDependencyHighlight = false to disable the behavior.

Highlights cover direct A1 cells/ranges and named ranges. They do not expand named formulas or a complete transitive dependency graph.

3. Named dropdown

createNamedRangeDropdown deduplicates a range into dropdown options. Register ColumnDropdown as the column type.

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

const source = [
  { allowed: 'Open', selected: 'Open' },
  { allowed: 'Open', selected: 'Closed' },
  { allowed: 'Closed', selected: null },
];
const names = [{ name: 'AllowedStatuses', kind: 'range' as const, ref: 'A1:A3' }];
const columns = [
  { prop: 'allowed', name: 'Allowed status' }, // A
  {
    prop: 'selected',
    name: 'Selected status',
    columnType: 'statusDropdown',
    dropdown: createNamedRangeDropdown('AllowedStatuses', {
      allSources: source,
      columns: [
        { prop: 'allowed', name: 'Allowed status' },
        { prop: 'selected', name: 'Selected status' },
      ],
      names,
    }),
  },
];

grid.plugins = [FormulaPlugin];
grid.columnTypes = { statusDropdown: ColumnDropdown };
grid.formulaNames = { names };
grid.columns = columns;
grid.source = source;

Expected result: the Selected status editor offers Open and Closed once each, even though Open appears twice in the named range.

4. Conditional formatting

The helper receives the current cell through cellvalue and 1-based row / column tokens.

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

const source = [
  { status: 'Open' },
  { status: 'Closed' },
];
const columns = [{ prop: 'status', name: 'Status' }];

columns[0].cellProperties = createFormulaConditionalCellProperties(
  '=cellvalue="Closed"',
  { class: 'is-closed' },
  { allSources: source, columns },
);
grid.columns = columns;
grid.source = source;

revo-grid .is-closed {
  color: #166534;
  background: #dcfce7;
  font-weight: 600;
}

Expected result: only row 2 receives is-closed. =row=2 matches the same row; =column=1 matches cells in the first authored column. Comparisons support >, >=, <, <=, =, and <> for numeric and string values.

Composition checklist

• Configure FormulaPlugin once.
• Add a Formula Bar only when users need an editor outside the cell.
• Use highlightOnFocus: true only when passive focus should reveal dependencies.
• Register ColumnDropdown before assigning a named-range dropdown column.
• Supply the same source, columns, and names to helper factories that the grid uses.
• Tear down external listeners and set grid.formulaBar = null when removing their hosts.

Next steps

Previous: Named Ranges · Next: Cross-sheet Formulas · Deeper reference: Formula API