Configuration

ConfigParams + compatibility presets + config-specific pitfalls. Authoritative docs:

Configuration options guide: https://hyperformula.handsontable.com/docs/guide/configuration-options.html
ConfigParams (all options): https://hyperformula.handsontable.com/docs/api/interfaces/configparams.html
Excel compatibility: https://hyperformula.handsontable.com/docs/guide/compatibility-with-microsoft-excel.html
Google Sheets compatibility: https://hyperformula.handsontable.com/docs/guide/compatibility-with-google-sheets.html

ConfigParams highlights

Pass as the second argument to any factory method.

const hf = HyperFormula.buildEmpty({
  licenseKey: 'gpl-v3',           // required — 'gpl-v3' for open source
  precisionRounding: 10,          // decimal rounding precision (default 10; was 14 before v3)
  functionArgSeparator: ',',      // separator between function arguments
  dateFormats: ['DD/MM/YYYY', 'DD-MM-YYYY'],
  nullDate: { year: 1900, month: 1, day: 1 },
  leapYear1900: false,            // Excel bug compat: treat 1900 as leap year
  maxRows: 40000,                 // max rows per sheet (default 40000)
  maxColumns: 18278,              // max columns per sheet (default 18278 = 'ZZZ')
  undoLimit: 20,                  // undo history depth
  maxPendingLazyTransformations: 1000, // v3.3+ — cap accumulated lazy transformations before cleanup
});

Excel compatibility preset

const hf = HyperFormula.buildEmpty({
  licenseKey: 'gpl-v3',
  useArrayArithmetic: true,
  useWildcards: true,
  evaluateNullToZero: true,
  leapYear1900: true,     // Excel's intentional 1900 leap-year bug
  ignoreWhiteSpace: 'any',
  caseSensitive: false,
  accentSensitive: true,
});

Google Sheets compatibility preset

Defaults already match Google Sheets behavior (leapYear1900: false, useArrayArithmetic: false).

const hf = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });

Config-specific pitfalls

Vue 3

Vue 3 requires wrapping the instance with markRaw — see vue3.md for the full integration guide (React / Angular / Svelte need no special handling).

`functionArgSeparator` vs `thousandSeparator` collision

These two options cannot share a character. European locales that use , as thousand separator must change the argument separator:

const hf = HyperFormula.buildEmpty({
  licenseKey: 'gpl-v3',
  thousandSeparator: ',',
  decimalSeparator: '.',
  functionArgSeparator: ';',  // must differ from thousandSeparator
});

Node.js must have full ICU

String comparisons (used in MATCH, VLOOKUP, sorting) can silently produce wrong results on Node.js < 13 or builds without full ICU. Verify at startup:

// Must report 'full' (or a detailed ICU version), not 'small'.
console.log(process.versions.icu);

Tuning `maxPendingLazyTransformations` (v3.3+)

HyperFormula defers some structural transformations (row/column insertions, moves) and applies them lazily. In long-lived instances with heavy mutation throughput — bulk imports, frequent undo/redo, scripted batch edits — the pending queue can grow before cleanup. v3.3 fixed the unbounded-growth leak; this option lets you cap the queue explicitly. Lower values trade memory for more frequent flush work; the default is suitable for typical UI workloads.

`precisionRounding` default changed in v3

Before v3 the default was 14. It is now 10. Calculations relying on the old precision need an explicit override:

const hf = HyperFormula.buildEmpty({
  licenseKey: 'gpl-v3',
  precisionRounding: 14,  // pre-v3 behavior
});

3.6 KiB Raw Blame History