# Performance and Calculation

## Content

Large `SJS.TABLE` formulas may significantly increase recalculation time because multiple simulations are evaluated for each input combination.
SpreadJS provides calculation modes and progress events to help manage performance.

## Calculation Modes

By default, SpreadJS recalculates all formulas automatically when dependent data changes.
For workbooks containing large data tables, you can adjust calculation behavior using `CalculationMode`.

```javascript
spread.options.calculationMode = GC.Spread.Sheets.CalculationMode.partial;
```

To trigger recalculation manually:

```javascript
spread.calculate();
```

>type=note
> **Notes:**
>
> * Partial mode is recommended when importing workbooks that contain large data tables. Without it, all `SJS.TABLE` formulas recalculate immediately after load, which may cause noticeable delays.
> * In partial mode, all formulas except `SJS.TABLE` recalculate automatically when dependent data changes. `SJS.TABLE` formulas recalculate only when `spread.calculate()` is called.

## Monitoring Calculation Progress

SpreadJS raises the `CalculationProgress` event to report recalculation progress.

### Enabling Incremental Calculation (General Formulas)

For general formula recalculation, progress reporting is available when incremental calculation is enabled:

```javascript
spread.options.incrementalCalculation = true;
```

When enabled, the `CalculationProgress` event reports:

* `totalCells`
* `pendingCells`
* `iterate` (for iterative calculation)

## Progress Reporting for `SJS.TABLE`

`SJS.TABLE` has specialized progress reporting behavior.

### Event Triggering

During `SJS.TABLE` evaluation, the `CalculationProgress` event is raised:

* Even if `incrementalCalculation` is <span class="font-semibold" data-streamdown="strong" style="border: 0px solid; box-sizing: inherit; margin: 0px; padding: 0px; --tw-font-weight: 600; font-weight: 600; -webkit-font-smoothing: antialiased; font-family: ui-sans-serif, -apple-system, system-ui, Segoe UI, Helvetica, Apple Color Emoji, Arial, sans-serif, Segoe UI Emoji, Segoe UI Symbol; line-height: 1.7; color: rgb(248, 250, 252);">not</span> enabled
* Independently of general formula recalculation progress

When a workbook contains `SJS.TABLE`, the event is triggered as follows:

1. When `SJS.TABLE` is detected for evaluation, the event is raised with `dataTableProgress: 0`
2. During evaluation, the event continues to fire with `dataTableProgress`

representing the progress of the data table calculation.

### Event Payload Behavior

While `SJS.TABLE` is being evaluated:

* The event payload includes `dataTableProgress`.
* Other progress fields such as `totalCells`, `pendingCells`, and `iterate` are not included.

`dataTableProgress` represents the completion ratio of the data table calculation.

### Example

```javascript
spread.bind(
  GC.Spread.Sheets.Events.CalculationProgress,
  function (e, info) {
    if (info.dataTableProgress !== undefined) {
      console.log(
        "Data Table: " +
        (info.dataTableProgress * 100).toFixed(0) + "%"
      );
      return;
    }

    if (info.pendingCells === 0) {
      console.log("Calculation finished");
    }
  }
);
```

This separation ensures that large `SJS.TABLE` simulations do not generate excessive general calculation completion notifications, while still providing clear progress feedback for data table evaluation.

## Status Bar Indicator

During `SJS.TABLE` calculation, the built-in SpreadJS status bar automatically displays:

```auto
Data Table: x%
```

No configuration is required. This provides visual feedback that a data table calculation is in progress.
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260420.5ca791.png?width=300)