# Formula calculation

Formulas evaluate strings beginning with = and display the result in a cell. For example, =SUM(A1:A3) references the first column in the original column definitions and the first three source rows.

Canonical: https://grid.syidax.com/docs/features/formulas/

<a id="understand"></a>

## How it works and when to use it

A1 coordinates do not follow the sorted display order. Formulas use the original data order and columnDefs order even after users sort rows or move columns.

Using this feature in a product requires the Pro package and a valid license. Matching setting names do not enable Pro features in Community.

In the code, grid is the Grid element prepared in the installation chapter. Check each example's data and settings, and implement the app functions and server endpoints for your project.

- [Installation and integration · Shared sample data](https://grid.syidax.com/docs/guides/getting-started.md)

<a id="example-1"></a>

## Example 1. Calculate an amount from price and quantity

Start with three columns that make formula coordinates easy to follow.

```javascript
grid.columnDefs = [
  { field: 'quantity', headerName: 'Quantity', editable: true, editor: 'number' },
  { field: 'price', headerName: 'Unit price', editable: true, editor: 'number' },
  { field: 'amount', headerName: 'Amount' },
];
grid.rowData = [{ id: 'a', quantity: 3, price: 100, amount: '=A1*B1' }];
grid.formulas = true;
```

Verify the result: The amount displays 300. Editing the quantity recalculates the dependent amount.

<a id="example-2"></a>

## Example 2. Compare results with formula text

Show the formula text and formula bar when calculations differ from your expectations.

```javascript
grid.showFormulas = true;
grid.formulaBar = true;
```

Verify the result: The formula cell displays =A1*B1. Set showFormulas back to false after reviewing it to display the result.

<a id="example-3"></a>

## Example 3. Review multiple sheets and dynamic arrays

When connecting multiple Grids as a workbook, use getWorkbookPropagationState() and getWorkbookSnapshotReport() to inspect connections and propagation. Before using dynamic arrays, review the dedicated applySpillFormula() input contract and conflict results.

Verify the result: If existing values occupy the spill area, do not force the array result over them. Distinguish rejected operations, conflicts, and unrendered cells when explaining the result to users.

<a id="pitfalls"></a>

## Combining features and troubleshooting

Formula text and calculated results are separate. Decide which you need for saving, copying, and exporting, then verify the output.

Do not assume every Excel function is supported. Test the function names and error results in the formulas you use, and avoid circular references.

<a id="related-api"></a>

## APIs used by this feature

- [formulas](https://grid.syidax.com/docs/options/formulas.md) — Evaluates cell strings beginning with = as formulas. A1 references use original column and row order, not display sorting.
- [showFormulas](https://grid.syidax.com/docs/options/showFormulas.md) — Displays formula text instead of calculated results for review in a table with formulas enabled.
- [formulaBar](https://grid.syidax.com/docs/options/formulaBar.md) — Shows a formula bar for inspecting and editing the active cell's source value or formula. Enter commits; Escape cancels.
- [workbookId](https://grid.syidax.com/docs/options/workbookId.md) — Identifies the workbook connecting multiple Grid sheets. Set it together with sheetName for cross-sheet references.
- [sheetName](https://grid.syidax.com/docs/options/sheetName.md) — Identifies this Grid sheet within a workbook. Review the effect of renaming it on formulas in other sheets.
- [formula](https://grid.syidax.com/docs/columns/formula.md) — Formula string applied to this column. Review formula support and original-coordinate rules.
- [getWorkbookBinding](https://grid.syidax.com/docs/methods/getWorkbookBinding.md) — Reads current workbook and sheet connection information, or null when disconnected.
- [reconnectWorkbook](https://grid.syidax.com/docs/methods/reconnectWorkbook.md) — Rebuilds the connection from current workbook settings and returns the result.
- [disconnectWorkbook](https://grid.syidax.com/docs/methods/disconnectWorkbook.md) — Disconnects the workbook. Review the effect on cross-sheet formula propagation.
- [getWorkbookPropagationState](https://grid.syidax.com/docs/methods/getWorkbookPropagationState.md) — Reads cross-sheet formula propagation connections, registrations, rejections, and latest publication information.
- [flushWorkbookPropagation](https://grid.syidax.com/docs/methods/flushWorkbookPropagation.md) — Processes pending workbook value propagation and returns the result.
- [getWorkbookSnapshotReport](https://grid.syidax.com/docs/methods/getWorkbookSnapshotReport.md) — Reads the last published workbook cells, hashes, and generations. Do not assume all Grid data was published.
- [getWorkbookIntegrityReport](https://grid.syidax.com/docs/methods/getWorkbookIntegrityReport.md) — Reads consistency checks for workbook connections and value propagation.
- [applySpillFormula](https://grid.syidax.com/docs/methods/applySpillFormula.md) — Atomically applies a dynamic array formula under the conflict policy. Inspect conflicts, rejections, and unrendered areas in the report.
- [clearSpillFormula](https://grid.syidax.com/docs/methods/clearSpillFormula.md) — Clears a dynamic array formula's anchor cell and releases its occupied range.
- [undoSpillTransaction](https://grid.syidax.com/docs/methods/undoSpillTransaction.md) — Undoes a dynamic array formula transaction and returns the result.
- [getSpillReport](https://grid.syidax.com/docs/methods/getSpillReport.md) — Inspects current dynamic array formulas and their occupied ranges.
- [formulaEvaluated](https://grid.syidax.com/docs/events/formulaEvaluated.md) — Emitted when a formula result is calculated. Distinguish formula text from its result.
- [formulaError](https://grid.syidax.com/docs/events/formulaError.md) — Emitted when formula evaluation fails. Connect target and error information to a review UI.
- [workbookBindingChanged](https://grid.syidax.com/docs/events/workbookBindingChanged.md) — Emitted when the Grid's workbook/sheet connection changes.
- [workbookBindingError](https://grid.syidax.com/docs/events/workbookBindingError.md) — Emitted when a workbook connection cannot be configured. Inspect identifiers and connection errors.
- [workbookValuesPropagated](https://grid.syidax.com/docs/events/workbookValuesPropagated.md) — Emitted after cross-sheet value propagation. Inspect results and generation information.

<a id="next"></a>

## Related reading

- [How rows, columns, and IDs relate](https://grid.syidax.com/docs/guides/concepts.md)
- [Connect results and events](https://grid.syidax.com/docs/guides/data-event-access.md)
- [Explore in Features](https://grid.syidax.com/grid/formulas) — The guide describes which interactions are available to try.