Numnote
English (United States)

Numnote calculator on your site

A free embedded calculator for any page. It computes the formula your site hands it: your own, or one copied from a formula page. No sign-up, no key, no third-party requests.

Quick start

Three steps for your own formula. Copying the code from a formula page is shorter still: one snippet.

  1. Load the helper. Once per page, before your code.

    HTML
    <script src="https://numnote.com/embed/v1.js"></script>
  2. Put a container where the calculator should appear.

    HTML
    <div id="calculator"></div>
  3. Call Numnote.embed with a form. The frame appears in the container and sets its own height.

    JavaScript
    Numnote.embed("#calculator", {
        "v": 1,
        "formula": "(morning + evening) / 2",
        "fields": {
          "morning": {
            "name": "Morning",
            "unit": "km",
            "value": "12.5"
          },
          "evening": {
            "name": "Evening",
            "unit": "km",
            "value": "9"
          }
        },
        "result": {
          "name": "Average",
          "unit": "km"
        }
      }, {
      region: "en-us"
    });

Don't want to write the calculator by hand? Compose it in the builder.

Code from a formula page

Every formula page has its code under “Embed on your site”, in two variants. Paste one into your page's HTML and the calculator with its fields and result appears where you put it. The copied code is yours from then on: a fix to the formula on numnote.com does not reach it.

The code of this site's first formula:

Script

The first choice. It gives the result to your own code, its height follows the form, and it tells you when a form is refused. It cannot go where a site allows no script.

HTML
<div id="numnote-percent_of"></div>
<script src="https://numnote.com/embed/v1.js"></script>
<script>
  Numnote.embed("#numnote-percent_of", {
    "v": 1,
    "formula": "p0 * p1",
    "fields": {
      "p0": {
        "name": "number",
        "value": "250"
      },
      "p1": {
        "name": "percent",
        "value": "15",
        "percent": true
      }
    },
    "result": {
      "name": "percent of"
    }
  }, { region: "en-us" });
</script>
<p><a href="https://numnote.com/en-us/calc/percent-of/">Percent of a number calculator · Numnote</a></p>

Link

One frame with the form in its address, for a site that allows only an iframe. It moves nothing on your page. It passes your code no result and no refusal, and its height is fixed in advance, so in a narrower column the frame scrolls inside.

HTML
<iframe src="https://numnote.com/en-us/embed/custom/#%7B%22v%22:1,%22formula%22:%22p0%20*%20p1%22,%22fields%22:%7B%22p0%22:%7B%22name%22:%22number%22,%22value%22:%22250%22%7D,%22p1%22:%7B%22name%22:%22percent%22,%22value%22:%2215%22,%22percent%22:true%7D%7D,%22result%22:%7B%22name%22:%22percent%20of%22%7D%7D" title="percent of" width="100%" height="348" style="border:0" loading="lazy"></iframe>
<p><a href="https://numnote.com/en-us/calc/percent-of/">Percent of a number calculator · Numnote</a></p>

Each variant ends with a visible link to the formula page. It stands outside the frame, on your own page: leave it there, because that is how readers and search engines find the formula.

By embedding the calculator, you accept the embedding terms.

Link attributes

AttributeValueMeaning
srchttps://numnote.com/en-us/embed/custom/#<form>The frame's address: the form comes after the #. The region in it sets the language and the number format.
titletextThe formula's name for screen readers. Keep it or translate it.
width100%The frame takes the container's full width. Limit the width with the container, not the frame.
height348Set from the number of fields: the height the content needs in a 320 px column. In a narrower column the frame scrolls inside.
loadinglazyThe frame loads when the reader scrolls to it.

Your own formula

Load the helper and hand it a form: the formula, its fields and the result's name. The frame draws the fields, calculates as the visitor types and answers your page.

Installation

The helper is one file with no dependencies. It creates the frame, posts the form once the frame has loaded, sets the frame's height and calls your functions. Load it from numnote.com rather than copying it: that way you receive the fixes.

HTML
<script src="https://numnote.com/embed/v1.js"></script>

The call

The container can be a CSS selector or the element itself. The form is described under “Form”, the options in the API reference.

HTML
<div id="calculator"></div>
<script src="https://numnote.com/embed/v1.js"></script>
<script>
  Numnote.embed("#calculator", {
      "v": 1,
      "formula": "(morning + evening) / 2",
      "fields": {
        "morning": {
          "name": "Morning",
          "unit": "km",
          "value": "12.5"
        },
        "evening": {
          "name": "Evening",
          "unit": "km",
          "value": "9"
        }
      },
      "result": {
        "name": "Average",
        "unit": "km"
      }
    }, {
    region: "en-us",
    onResult: function (answer) { console.log(answer.text); },
    onError: function (code, detail) { console.log(code, detail.at); }
  });
</script>

Live The frame the code above creates. It runs right on this page: change a number.

The frame always shows the “powered by Numnote” mark, except on a blocked site, and version 1 has no key that removes it. It answers only the page that posted the form, and writes your names and units as plain text, never as markup.

By embedding the calculator, you accept the embedding terms.

API reference

Numnote.embed(target, form, options)

Creates the frame in the container, posts the form and returns a handle to update or remove it.

ParameterTypeMeaning
targettext | ElementA CSS selector or the element the frame goes into. Without an element the helper throws a TypeError.
formobjectA version 1 form, described below.
optionsobject, optionalOptional settings: region, onResult, onError.

options

ParameterTypeMeaning
regiontext, optionalThe frame's region: the language of its own words and the number format. It is the key of a region that has this page, for example uk-ua, en-us, en-gb; a bare language (uk, en) leads to its default region. Without it the helper takes en-us; with the key of a region that does not exist the frame stays empty.
onResultfunction, optionalCalled with the answer object every time a result is calculated: after loading and after every changed number. While a field is empty, figure and text are empty strings, so your page can clear the previous figure.
onErrorfunction, optionalCalled with the error code and the message object when the form is refused or the calculation fails.

Return value

MemberTypeMeaning
frameHTMLIFrameElementThe iframe element, for your own class or style.
update(form)functionPosts a new form to the same frame. The fields are redrawn, the height set again.
destroy()functionRemoves the frame and the message listener.

The onResult answer object

MemberTypeMeaning
typetextAlways “result”.
nametextThe result's name from your form.
figuretextThe figure in the region's format, as the visitor sees it.
unittextThe result's unit or an empty string.
texttextThe figure and the unit in one string.

The onError call

ParameterTypeMeaning
codetextA code from the error table, for example UNKNOWN_SLOT.
detailobjectThe frame's message: type “error”, code and at, where at names the place: a field id, “formula”, “fields”, “result.unit”.

The frame's messages

The helper is a convenience. The frame works with any page through postMessage: you post the form, the frame answers with three kinds of message.

MessageShapeMeaning
the form, from you{ v: 1, formula, fields, result }Your page posts the version 1 form into the frame once it has loaded. Target origin: numnote.com.
result{ type: "result", name, figure, unit, text }A result has been calculated. Its fields are described in the answer object above.
height{ type: "height", height }The content's height in pixels. Set it on the frame so there is no scrollbar.
error{ type: "error", code, at }The form was refused or the calculation failed: code and at.

The frame answers only the window that posted the form, and only its origin. A message with none of the keys v, formula, fields and result is another script's and is left unanswered.

Form

The form is one version 1 JSON object. You write the names and units in your own words: the frame shows them as plain text and never translates them.

FieldTypeMeaning
vnumberAlways 1. Any other value is refused.
formulatextThe calculation written with field ids, the operations and the functions described below.
fieldsobjectThe fields in the order they are drawn. Each key is the field's id, the name the formula calls it by: Latin letters, digits and underscores, but the first character cannot be a digit. Every field must be used in the formula.
fields.<id>.nametextThe label the visitor sees above the field.
fields.<id>.unittext, optionalThe field's unit, written as a stem from the unit list. Any other text is shown as a label and converts nothing.
fields.<id>.valuetext, optionalThe value the field opens with, written with a dot as the decimal separator.
fields.<id>.percenttrue or false, optionaltrue if the field is a percentage: the visitor types 20 for 20 %, and every use of the field in the formula reads it as a percentage, so after an addition or subtraction it is a share of the left side. The field shows a % sign where the unit would stand.
resultobjectThe result the frame shows below the fields.
result.nametextThe result's label.
result.unittext, optionalThe result's unit. It must match the unit the formula gives.
result.percenttrue or false, optionaltrue if the formula gives its result in percent: a result of 25 is shown as 25 %.
keytext, optionalReserved for the future. Version 1 ignores it.

Minimal form

One field without a unit and a result without a unit. Everything else is optional.

JSON
{
  "v": 1,
  "formula": "price + 20 %",
  "fields": {
    "price": {
      "name": "Price"
    }
  },
  "result": {
    "name": "With tax"
  }
}

Full form

Every key version 1 knows: units, starting values, a percentage field and a percentage result.

JSON
{
  "v": 1,
  "formula": "(after - before) / before * 100",
  "fields": {
    "before": {
      "name": "Before",
      "unit": "kg",
      "value": "80"
    },
    "after": {
      "name": "After",
      "unit": "kg",
      "value": "76"
    }
  },
  "result": {
    "name": "Change",
    "percent": true
  },
  "key": ""
}

Examples

Every example runs on this page through the same helper as on yours. The code beside the frame is complete: copy it and put your own words in.

Percentage: tiles with a margin

The margin field has percent: true. After the addition it reads as a share of the area, so 10 means plus 10 % of the area. The result is divided by a pack's area and stays a plain number.

JavaScript
Numnote.embed("#calculator", {
    "v": 1,
    "formula": "(w * l + spare) / pack",
    "fields": {
      "w": {
        "name": "Room width",
        "unit": "m",
        "value": "3.2"
      },
      "l": {
        "name": "Room length",
        "unit": "m",
        "value": "4.5"
      },
      "spare": {
        "name": "Margin for cutting",
        "percent": true,
        "value": "10"
      },
      "pack": {
        "name": "Area per pack",
        "unit": "m²",
        "value": "1.44"
      }
    },
    "result": {
      "name": "Packs"
    }
  }, {
  region: "en-us"
});

Function: a rectangle's diagonal

A function is written with its arguments in brackets. The fields have no units, because version 1 cannot take the root of a unit.

JavaScript
Numnote.embed("#calculator", {
    "v": 1,
    "formula": "sqrt(a ^ 2 + b ^ 2)",
    "fields": {
      "a": {
        "name": "Side a",
        "value": "3"
      },
      "b": {
        "name": "Side b",
        "value": "4"
      }
    },
    "result": {
      "name": "Diagonal"
    }
  }, {
  region: "en-us"
});

Percentage result: a share of spending

result.percent: true shows the result with a % sign. The formula gives its result in percent, so the multiplication by 100 is in the formula itself.

JavaScript
Numnote.embed("#calculator", {
    "v": 1,
    "formula": "part / total * 100",
    "fields": {
      "part": {
        "name": "Spent on food",
        "value": "250"
      },
      "total": {
        "name": "All spending",
        "value": "1000"
      }
    },
    "result": {
      "name": "Share",
      "percent": true
    }
  }, {
  region: "en-us"
});

Region: language and number format

The same form in two regions. The region sets the number separators and the frame's own words, while your names stay yours.

JavaScript
Numnote.embed("#calculator-a", {
    "v": 1,
    "formula": "distance / days",
    "fields": {
      "distance": {
        "name": "Distance",
        "unit": "km",
        "value": "1234.5"
      },
      "days": {
        "name": "Days",
        "value": "4"
      }
    },
    "result": {
      "name": "Per day",
      "unit": "km"
    }
  }, {
  region: "en-us"
});
Numnote.embed("#calculator-b", {
    "v": 1,
    "formula": "distance / days",
    "fields": {
      "distance": {
        "name": "Distance",
        "unit": "km",
        "value": "1234.5"
      },
      "days": {
        "name": "Days",
        "value": "4"
      }
    },
    "result": {
      "name": "Per day",
      "unit": "km"
    }
  }, {
  region: "uk-ua"
});

region: "en-us"

region: "uk-ua"

update() and destroy()

The helper returns a handle. update posts another form to the same frame; destroy removes the frame from the page. Press a button.

JavaScript
var calc = Numnote.embed("#calculator", formA, { region: "en-us" });
calc.update(formB);   // Three fields
calc.destroy();       // Remove

Errors: your message instead of an empty frame

A refused form draws nothing: the frame stays empty. onError receives the code and the place, so your page can tell the visitor what happened or hide the container. Here the formula names a field the form does not declare.

JavaScript
Numnote.embed("#calculator", {
    "v": 1,
    "formula": "area / coverage",
    "fields": {
      "area": {
        "name": "Area",
        "unit": "m²",
        "value": "40"
      }
    },
    "result": {
      "name": "Paint"
    }
  }, {
  region: "en-us",
  onError: function (code, detail) {
    document.getElementById("calculator").hidden = true;
    message.textContent = "The calculator did not load:" + " " + code + " (" + detail.at + ")";
  }
});

Without the helper: postMessage directly

When the helper does not fit, for example in a framework with its own lifecycle, talk to the frame yourself. The same frame, the same messages.

HTML
<iframe id="calculator" src="https://numnote.com/en-us/embed/custom/" style="border:0;width:100%"></iframe>
<script>
  var frame = document.getElementById("calculator");
  var origin = "https://numnote.com";
  frame.addEventListener("load", function () {
    frame.contentWindow.postMessage({
      "v": 1,
      "formula": "a + b",
      "fields": {
        "a": {
          "name": "First",
          "value": "1"
        },
        "b": {
          "name": "Second",
          "value": "2"
        }
      },
      "result": {
        "name": "Sum"
      }
    }, origin);
  });
  window.addEventListener("message", function (e) {
    if (e.origin !== origin || e.source !== frame.contentWindow) return;
    if (e.data.type === "height") frame.style.height = e.data.height + "px";
    if (e.data.type === "result") console.log(e.data.text);
    if (e.data.type === "error") console.warn(e.data.code, e.data.at);
  });
</script>

Formula

The browser reads the formula. It accepts numbers with a dot, field ids, brackets and the usual operations.

After an addition or subtraction a percentage means a share of the left side, as in Numnote itself. A product is always written with its sign: 2a is refused.

A unit is never written in the formula, because it belongs to the field.

Operations

NotationMeaningExample
12.5A number. The decimal separator in the formula is always a dot.price * 1.2
a_1A field id: Latin letters, digits, underscores; it does not start with a digit.width * height
+ -Addition and subtraction.a + b - c
* /Multiplication and division. A product always has its sign.2 * a / b
modRemainder of a division.n mod 7
^Power.a ^ 2
!Factorial.n!
%Percent: after + or − a share of the left side, otherwise a hundredth.price + 20 %
( )Brackets set the order.(a + b) / 2
f(x, y)A function with its arguments separated by commas.root(x, 3)

Functions

A function is written with its arguments in brackets, separated by commas. The list is generated from Numnote's function registry:

  • sin (one argument)
  • cos (one argument)
  • tg, tan (one argument)
  • ctg, cot (one argument)
  • arcsin, asin (one argument)
  • arccos, acos (one argument)
  • arctg, arctan, atan (one argument)
  • arcctg, arccot, acot (one argument)
  • sh, sinh (one argument)
  • ch, cosh (one argument)
  • th, tanh (one argument)
  • cth, coth (one argument)
  • arsh, arsinh, asinh (one argument)
  • arch, arcosh, acosh (one argument)
  • arth, artanh, atanh (one argument)
  • arcth, arcoth, acoth (one argument)
  • ln (one argument)
  • sqrt (one argument)
  • abs (one argument)
  • ceil (one argument)
  • floor (one argument)
  • round (one argument)
  • log (one or two arguments)
  • root (two arguments)

Numnote knows these names too, but the frame does not run them yet, so a formula with them is refused with UNSUPPORTED_FUNCTION:

Units

The unit of a field or of the result is written as a stem from this list. The list is generated from Numnote's unit registry. Text outside the list is shown as a label and converts nothing.

  • m
  • cm
  • mm
  • km
  • in
  • ft
  • yd
  • mi
  • m²
  • cm²
  • mm²
  • km²
  • a
  • ha
  • ft²
  • yd²
  • ac
  • m³
  • L
  • mL
  • cm³
  • dm³
  • USgal
  • kg
  • g
  • t
  • lb
  • oz
  • s
  • min
  • h
  • d
  • mo
  • wk
  • yr
  • J
  • Wh
  • kWh
  • MWh
  • cal
  • kcal
  • W
  • kW
  • Pa
  • bar
  • atm
  • mmHg
  • psi
  • N
  • V
  • A
  • Ohm
  • Hz
  • K
  • °C
  • °F
  • rad
  • °
  • mol
  • pc
  • pk
  • ARS
  • AUD
  • BRL
  • CAD
  • CHF
  • CLP
  • CNY
  • COP
  • CZK
  • DKK
  • EUR
  • GBP
  • HKD
  • HUF
  • IDR
  • ILS
  • INR
  • ISK
  • JPY
  • KRW
  • MXN
  • MYR
  • NOK
  • NZD
  • PHP
  • PLN
  • RON
  • SEK
  • SGD
  • THB
  • TRY
  • UAH
  • USD
  • ZAR

When a field's unit has other units of the same quantity, the visitor picks one in the field itself: the number stays and the result is recalculated. A label from outside the list stays text, with no choice. When fields carry different units of one quantity, for example centimeters and meters, the frame converts them itself and the formula sees one quantity.

In version 1 a unit meets only itself or a plain number. A sum of different units, a product of two units, a power or a root of a unit is refused with UNITS_DO_NOT_MEET.

AcceptedMeaning
km + kmone unit with itself
km * 2a unit with a plain number
km / kma ratio of the same units, a plain number
km + 10 %a percentage of a unit, the same unit
RefusedMeaning
km + kga sum of different units
m * ma product of two units
sqrt(m)a power or a root of a unit
km / ha ratio of different units

Limits

  • A form has at most 8 fields.
  • The formula has at most 500 characters.

A form beyond the limits is refused and nothing is drawn. The frame takes its container's full width, and its height follows the content.

Errors

The frame reports an error as an object with type “error”, a code and the key at, which names where it was found: a field id, “formula”, “fields”, “result.name” and so on. The helper passes the code to onError.

A form that could not be read

CodeMeaning
NOT_JSONThe message is not valid JSON.
NOT_AN_OBJECTThe message, a field or the result is not an object.
VERSIONThe version is missing or is not 1.
MISSINGA required key is missing.
WRONG_TYPEA value has the wrong type.
UNKNOWN_KEYThe form has a key that version 1 does not know.
TOO_LONGThe formula is longer than the limit.
TOO_MANY_FIELDSThe form has more fields than allowed.
BAD_SLOT_IDA field id does not follow the rule for ids, or it is the word mod or the name of a function.
EMPTY_NAMEA name is empty.
BAD_VALUEA field's value is not a decimal number written with a point.
UNUSED_FIELDA field is declared but the formula never uses it.
EMPTY_FORMULAThe formula is empty.
BAD_CHARACTERThe formula has a character that it may not contain.
UNEXPECTEDA character stands where the formula does not allow it.
UNCLOSEDA bracket is not closed.
TOO_DEEPThe formula is nested too deeply.
UNKNOWN_SLOTThe formula names a field that the form does not declare.
UNKNOWN_FUNCTIONThe formula calls a function that does not exist.
UNSUPPORTED_FUNCTIONThe function exists in Numnote but the frame does not run it yet.
WRONG_ARGUMENTSA function is called with the wrong number of arguments.
UNIT_IN_FORMULAA unit is written in the formula. Give it to a field instead.
UNITS_DO_NOT_MEETThe units of an operation cannot be combined.
RESULT_UNITThe formula gives a unit other than the one declared for the result.
BLOCKEDThe site or a page holding the frame is on the block list, or a page in the chain hides its address. The frame does not calculate and shows a line about the block in place of the “powered by Numnote” mark.

A calculation that could not run

CodeMeaning
UNKNOWN_UNITA value was typed in a unit that its field does not accept.
DIVISION_BY_ZEROA division by zero.
ROOT_OF_NEGATIVEAn even root of a negative number.
ROOT_DEGREE_INVALIDThe degree of a root is not a positive whole number.
LOG_BASE_INVALIDThe base of a logarithm is not valid.
LOG_ARGUMENT_NOT_POSITIVEThe argument of a logarithm is not positive.
OVERFLOWThe result is too large to be written.
TAN_UNDEFINEDThe tangent is not defined there.
COT_UNDEFINEDThe cotangent is not defined there.
ASIN_OUT_OF_DOMAINThe argument of the arcsine is outside its domain.
ACOS_OUT_OF_DOMAINThe argument of the arccosine is outside its domain.
COTH_OUT_OF_DOMAINThe hyperbolic cotangent can't be computed for zero.
ACOSH_OUT_OF_DOMAINThe inverse hyperbolic cosine (area cosine) can't be computed for a number less than 1.
ATANH_OUT_OF_DOMAINThe inverse hyperbolic tangent (area tangent) can't be computed unless the number is strictly between −1 and 1.
ACOTH_OUT_OF_DOMAINThe inverse hyperbolic cotangent (area cotangent) can't be computed unless the absolute value of the number is greater than 1.
FACTORIAL_DOMAINThe factorial needs a whole number that is not negative.
NOT_A_NUMBERA field holds text that is not a number.
BAD_PROGRAMThe formula could not be run. The fault is ours, so write to us.

Security and privacy

  • The frame answers only the window that posted the form, and only at that window’s origin. Another page cannot read the answers.
  • Your names and units become text nodes, never markup. Tags in a name are shown as text.
  • The frame and the helper load only from numnote.com. No third-party scripts, no cookies, no trackers. The typed numbers never leave the visitor's browser.
  • The frame always shows the “powered by Numnote” mark and the link to the legal pages. That is its condition of use. On a blocked site the frame does not calculate and shows a line saying so instead of the mark.

Versioning

  • The form has the key v: 1. Every later version of the frame reads a version 1 form the same way, so an embedded calculator does not break.
  • The function and unit lists grow without a version change: a function from the “not run yet” list will work one day, and the forms that waited for it will start calculating.
  • The key named key is reserved for a later version. Version 1 ignores it, so a form with it is accepted.

Questions or bugs: support@numnote.com.