Skip to content
Generate formulas on the fly
JavaScript CSS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


last commit MIT License Size NPM Package Maintenance

Generate formulas on the fly



  • Installation

Simply import formula.min.js & formula.min.css into your HTML by downloading it or using a CDN.

<link rel="stylesheet" href="">
<script src=""></script>	
  • Demo

A demo is available on this JSFiddle

  • Usage

Initialize your Formula by specifying a wrapper and some additional options:

const formula = new Formula('#wrapper');
// OR
const formula = new Formula(wrapperElement);
// OR
const formula = new Formula(wrapperElement, options);

You can change the cursor position by clicking on an existing tag or pressing the left/right arrow keys.

  • Options

The available options and their default values are:

  separators: [' ', 'Enter'], // Characters that will process the inputted String into a new tag
  closers: '+-*/()%^',        // A chain of characters that will always trigger a new separate tag
  lang: {                     // Dictionary holder (The attribute 'field' is the only one needed right now)
    field: 'Custom Field'
  customFields: undefined,    // Custom Fields to display, see below
  onFieldExpand: function(field){ ... } // Callback REQUIRED if you use the 'children: true' Field property. Expects a Field-like object to be returned
  onUpdate: function(value){ ... } // Callback triggered whenever the Formula gets updated. It's first parameter is the String representation of the Formula
  • Custom Fields

If you want to allow the user to pick from some predefined properties, you can use the customFields attribute:

// Basic usage
const customFields = {
  firstField: {
    name: 'Pretty name'
  whatever: {
    name: 'Prettier name'

// Tree-like usage (you can deep-nest)
const customFields = {
  firstField: {
    name: 'Pretty name',
    children: {
      nestedField: {
        name: 'Hey ya'
  whatever: {
    name: 'Prettier name'

// Dynamic tree-like usage
const customFields = {
  firstField: {
    name: 'Pretty name',
	children: true, // When using a Boolean as the children value, you have to use the 'onFieldExpand' callback, see below
	customData: {   // This optional object will be returned as the second argument of the 'onFieldExpand' callback
		whateverIWant: ':D'
  whatever: {
    name: 'Prettier name'
  • Dynamic fields

Using children: true as a Field property forces you to specify the onFieldExpand callback. It will be called every time a new subtree is opened by the user.

  • The first parameter of this callback returns the field Node the user opened:
<li class="formula-js-field" data-field="test" data-name="Hey">Hey<span class="children"></span></li>

The data-field and data-name attribute will allow you to build the subtree accordingly.

  • The second parameter of this callback returns whatever you passed inside the customData attribute of your Field

The onFieldExpand callback expects a Promise that resolves with a Field-like object to be returned, which will be used to build the subtree.

// Example
onFieldExpand: field => {
	path = field.getAttribute('data-field'),
	children = grabChildren(path);

  return Promise.resolve( => ({
    name: prettyName(child),
    children: hasChildren(child)
  • Methods

The full documentation is available on

  • .get()
  • .set(formulaString)
  • .add(formulaString)
  • .addField(fieldPath)
  • .clear()
  • .destroy()


You can’t perform that action at this time.