Skip to content
Handsontable

Installation

The Formulas plugin runs on HyperFormula, a calculation engine that you install separately. This guide shows how to install, license, and import HyperFormula so you can enable the plugin.

Starting with Handsontable 18.0, HyperFormula is not bundled with Handsontable. You add it to your project yourself. In earlier versions, HyperFormula shipped as a Handsontable dependency and required no separate installation.

Prerequisites

  • Handsontable is installed in your project. See Installation.

Install HyperFormula

Install HyperFormula with your package manager:

npm
npm install hyperformula
Yarn
yarn add hyperformula
pnpm
pnpm add hyperformula

Install the HyperFormula version that matches your Handsontable version. For the compatible versions, see HyperFormula version support.

To load HyperFormula from a CDN or as a UMD bundle instead, see the HyperFormula installation docs.

Import HyperFormula

Import the HyperFormula class into the file where you configure the grid:

import { HyperFormula } from 'hyperformula';

License HyperFormula

HyperFormula is licensed separately from Handsontable. For details, see the HyperFormula license key guide or contact our Sales Team.

Handsontable sets a license key on a HyperFormula engine that has none. To use your own key, set the licenseKey option in the HyperFormula configuration. How you do that depends on how you connect the engine:

  • If you pass the HyperFormula class to the formulas.engine option, use the engine configuration object and set licenseKey next to the hyperformula field.
  • If you build the engine yourself with HyperFormula.buildEmpty(), set licenseKey in the configuration you pass to buildEmpty().
const hyperformulaInstance = HyperFormula.buildEmpty({
  // replace with your HyperFormula license key
  licenseKey: 'your-hyperformula-license-key',
});

Enable the Formulas plugin

Pass the HyperFormula class to the formulas.engine option. Handsontable builds the engine for you.

import Handsontable from 'handsontable';
import { HyperFormula } from 'hyperformula';


const container = document.querySelector('#example');


const hot = new Handsontable(container, {
  data: [
    ['Product', 'Price', 'Quantity', 'Total'],
    ['Wireless mouse', 25, 4, '=B2*C2'],
    ['Mechanical keyboard', 89, 2, '=B3*C3'],
    ['USB-C hub', 45, 3, '=B4*C4'],
  ],
  colHeaders: true,
  rowHeaders: true,
  formulas: {
    engine: HyperFormula,
  },
  licenseKey: 'non-commercial-and-evaluation', // for non-commercial use only
});

This example passes the HyperFormula class, which is one of several ways to connect the engine.

Ways to pass HyperFormula

You can connect HyperFormula to Handsontable in more than one way. The formulas.engine option accepts the HyperFormula class, a pre-built HyperFormula instance, or an engine configuration object. Choose the approach that fits your setup.

Pass the HyperFormula class

This is the shortest path, shown above. You import the class and pass it to formulas.engine. Handsontable builds the engine and manages the engine’s lifecycle for you. Use this for a single grid, or for grids that each work on their own data.

import { HyperFormula } from 'hyperformula';


const hot = new Handsontable(container, {
  formulas: {
    engine: HyperFormula,
  },
  licenseKey: 'non-commercial-and-evaluation', // for non-commercial use only
});

Build a HyperFormula instance first, then pass it

Create the engine yourself with HyperFormula.buildEmpty() and pass the instance to formulas.engine. This gives you direct access to the engine’s API. It also lets several Handsontable instances share one engine, so formulas can reference cells across grids with cross-sheet references.

import { HyperFormula } from 'hyperformula';


const hyperformulaInstance = HyperFormula.buildEmpty({
  // replace with your HyperFormula license key
  licenseKey: 'your-hyperformula-license-key',
});


const hot = new Handsontable(container, {
  formulas: {
    engine: hyperformulaInstance,
  },
  licenseKey: 'non-commercial-and-evaluation', // for non-commercial use only
});

Pass an engine configuration object

Instead of the bare class, pass an object with a hyperformula field (the class or an instance) alongside HyperFormula configuration options, such as leapYear1900. Use this to customize how the engine behaves.

import { HyperFormula } from 'hyperformula';


const hot = new Handsontable(container, {
  formulas: {
    engine: {
      hyperformula: HyperFormula, // or a pre-built HyperFormula instance
      leapYear1900: false,
    },
  },
  licenseKey: 'non-commercial-and-evaluation', // for non-commercial use only
});

For complete, framework-specific examples of each approach - including shared and external engines across multiple grids - see Initialization methods.

Result

HyperFormula is installed, licensed, and connected to Handsontable. The Formulas plugin evaluates any cell whose value starts with =, and it recalculates dependent cells as your data changes.