# Excel Compatibility

## Content

SpreadJS supports import and export compatibility for What-If Analysis features that are stored in workbook files.
This topic describes compatibility behavior for:

* Data Table Analysis
* Scenario Analysis

## Data Table Compatibility

SpreadJS converts between Excel What‑If Analysis data tables and `SJS.TABLE` formulas during import and export.

### Import from Excel

When opening an Excel workbook that contains What‑If Analysis data tables, SpreadJS converts each data table into an equivalent `SJS.TABLE` formula.
The resulting formula type depends on the Excel file version and the `allowDynamicArray` setting.

| Excel File Type | allowDynamicArray | Result in SpreadJS |
| --------------- | ----------------- | ------------------ |
| Created with Excel 2019 or earlier | false | Imported as a legacy array formula, enclosed in `{}`. |
| Created with Excel 365 or later | true | Imported as a dynamic array formula that spills automatically. |

In both cases:

* The calculated results from the original Excel file are preserved.
* The formula recalculates normally in SpreadJS.

### Export to Excel

When exporting a SpreadJS workbook, SpreadJS attempts to convert each `SJS.TABLE` formula into a native Excel data table.
If conversion succeeds:

* The generated `.xlsx` file contains a standard Excel data table.
* The file opens and behaves as expected in Excel.

If conversion fails:

* The `SJS.TABLE` formula is preserved in the exported file.
* Excel displays the formula text but does not recognize it as a native data table.

Conversion is performed on a best-effort basis and is subject to Excel's structural limitations.

### Conditions That Prevent Data Table Conversion

Conversion from `SJS.TABLE` to an Excel data table fails when any of the following conditions are true:

* The formula contains cross-sheet references.
* The formula contains more than two `inputs` / `input_cell` pairs.
* Any referenced range cannot be resolved to a valid worksheet address.
* The input value ranges are not structurally aligned with the data table layout required by Excel.
* An `input_cell` falls inside the data table result area, except for the top-left position in a one-variable table.

>type=info
> If round-trip Excel compatibility is required, limit `SJS.TABLE` usage to one or two input pairs and avoid cross-sheet references.

## Scenario Compatibility

SpreadJS converts between Excel scenarios and SpreadJS scenarios during import and export.
SpreadJS scenarios are workbook-scoped. A single scenario can contain changing cells from multiple worksheets.
Excel scenarios are worksheet-scoped. During import and export, SpreadJS converts between these scope models.

### Import from Excel

When importing an Excel workbook that contains scenarios, SpreadJS imports worksheet-scoped Excel scenarios as workbook-level SpreadJS scenarios.
If scenarios with the same name exist on different worksheets in the Excel file, they are merged into a single workbook-level scenario in SpreadJS.

### Export to Excel

When exporting a SpreadJS workbook to Excel, SpreadJS exports workbook-level scenarios back to worksheet-scoped Excel scenarios.
If a SpreadJS scenario contains changing cells from multiple worksheets, it is split across the corresponding worksheets in the exported Excel file.

### Scenario Name Behavior

Scenario names must be unique in a SpreadJS workbook.
SpreadJS scenario names are case-sensitive. For example, `Plan A` and `plan a` are treated as different scenario names in SpreadJS.
When importing duplicate scenario names from Excel, SpreadJS merges them into a single workbook-level scenario.

### Changing Cell Count

Excel traditionally limits the number of changing cells in a scenario. SpreadJS does not impose this limit.
If a scenario contains more changing cells than Excel's traditional limit, the scenario can still be exported. However, compatibility depends on how the target Excel version handles such scenarios.

### Unsupported Excel Scenario Formatting

Excel scenario input cells can include formatting-related payloads. SpreadJS scenarios store cell values for changing cells and do not preserve Excel scenario input-cell formatting payloads such as number format identifiers.
Use worksheet styles and formatting directly on the target cells when formatting must be preserved.

## Functional Limitations

The following limitations apply regardless of Excel compatibility.

### Async Functions in Data Tables

`SJS.TABLE` does not support use with asynchronous functions.
If `result_reference`, or any of its dependent cells, contains an async function that relies on `defaultValue` or `setAsyncResult`, the returned results may be unpredictable.
Use only synchronous formulas within a data table calculation.

### Calc Worker Support

`SJS.TABLE` is fully supported when running inside the SpreadJS Calc Worker. No additional configuration is required.