Skip to content
v3.3.0
—

Basic usage

If you’ve already installed the library, it’s time to start writing the first simple application.

First, if you used NPM or Yarn to install the package, make sure you have properly imported HyperFormula as shown below:

import { HyperFormula } from 'hyperformula';

If you embed HyperFormula in the <script> tag using CDN, then it will be accessible as global variable HyperFormula and ready to use.

Now you can use the available options to configure the instance of HyperFormula according to your needs, like this:

const options = {
    licenseKey: 'gpl-v3'
};

Then, prepare some data to be used by your app. In this case, the data set will contain numbers and just one formula =SUM(A1,B1). Use the buildFromArray method to create the instance:

// define the data
const data = [['10', '20', '3.14159265359', '=SUM(A1:C1)']];


// build an instance with defined options and data
const hfInstance = HyperFormula.buildFromArray(data, options);

Alright, now it’s time to do some calculations. Let’s use the getCellValue method to retrieve the results of a formula included in the data .

// call getCellValue to get the calculation results
const mySum = hfInstance.getCellValue({ col: 3, row: 0, sheet: 0 });

You can check the output in the console:

// this outputs the result in the browser's console
console.log(mySum);

That’s it! You’ve grasped a basic idea of how the HyperFormula engine works. It’s time to move on to a more advanced example.

Demo

Section titled “Demo”
result:
Source code 
const tableData = [['10', '20', '=SUM(A1,B1)']];
// Create an empty HyperFormula instance.
const hf = HyperFormula.buildEmpty({
  precisionRounding: 9,
  licenseKey: 'gpl-v3',
});


// Add a new sheet and get its id.
const sheetName = hf.addSheet('main');
const sheetId = hf.getSheetId(sheetName);


// Fill the HyperFormula sheet with data.
hf.setCellContents(
  {
    row: 0,
    col: 0,
    sheet: sheetId,
  },
  tableData,
);


/**
 * Fill the HTML table with data.
 */
function renderTable() {
  const theadDOM = document.querySelector('.example thead');
  const tbodyDOM = document.querySelector('.example tbody');
  const { height, width } = hf.getSheetDimensions(sheetId);
  let newTheadHTML = '';
  let newTbodyHTML = '';


  for (let row = -1; row < height; row++) {
    for (let col = 0; col < width; col++) {
      if (row === -1) {
        newTheadHTML += `<th><span></span></th>`;


        continue;
      }


      const cellAddress = { sheet: sheetId, col, row };
      const cellHasFormula = hf.doesCellHaveFormula(cellAddress);
      let cellValue = '';


      if (!hf.isCellEmpty(cellAddress) && !cellHasFormula) {
        cellValue = hf.getCellValue(cellAddress);
      } else {
        cellValue = hf.getCellFormula(cellAddress);
      }


      newTbodyHTML += `<td><span>
      ${cellValue}
      </span></td>`;
    }
  }


  tbodyDOM.innerHTML = `<tr>${newTbodyHTML}</tr>`;
  theadDOM.innerHTML = newTheadHTML;
}


/**
 * Bind the events to the buttons.
 */
function bindEvents() {
  const calculateButton = document.querySelector('.example #calculate');
  const formulaPreview = document.querySelector('.example #address-output');
  const calculationResult = document.querySelector('.example #result-output');
  const cellAddress = { sheet: sheetId, row: 0, col: 2 };


  formulaPreview.innerText = hf.simpleCellAddressToString(cellAddress, sheetId);
  calculateButton.addEventListener('click', () => {
    calculationResult.innerText = hf.getCellValue(cellAddress);
  });
}


// Bind the button events.
bindEvents();
// Render the table.
renderTable();