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.
Load the helper. Once per page, before your code.
HTML <script src="https://numnote.com/embed/v1.js"></script>Put a container where the calculator should appear.
HTML <div id="calculator"></div>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-au" });
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.
<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": "260"
},
"p1": {
"name": "percent",
"value": "16",
"percent": true
}
},
"result": {
"name": "percent of"
}
}, { region: "en-au" });
</script>
<p><a href="https://numnote.com/en-au/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.
<iframe src="https://numnote.com/en-au/embed/custom/#%7B%22v%22:1,%22formula%22:%22p0%20*%20p1%22,%22fields%22:%7B%22p0%22:%7B%22name%22:%22number%22,%22value%22:%22260%22%7D,%22p1%22:%7B%22name%22:%22percent%22,%22value%22:%2216%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-au/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
| Attribute | Value | Meaning |
|---|---|---|
src | https://numnote.com/en-au/embed/custom/#<form> | The frame's address: the form comes after the #. The region in it sets the language and the number format. |
title | text | The formula's name for screen readers. Keep it or translate it. |
width | 100% | The frame takes the container's full width. Limit the width with the container, not the frame. |
height | 348 | Set from the number of fields: the height the content needs in a 320 px column. In a narrower column the frame scrolls inside. |
loading | lazy | The 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.
<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.
<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-au",
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.
| Parameter | Type | Meaning |
|---|---|---|
target | text | Element | A CSS selector or the element the frame goes into. Without an element the helper throws a TypeError. |
form | object | A version 1 form, described below. |
options | object, optional | Optional settings: region, onResult, onError. |
options
| Parameter | Type | Meaning |
|---|---|---|
region | text, optional | The 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. |
onResult | function, optional | Called 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. |
onError | function, optional | Called with the error code and the message object when the form is refused or the calculation fails. |
Return value
| Member | Type | Meaning |
|---|---|---|
frame | HTMLIFrameElement | The iframe element, for your own class or style. |
update(form) | function | Posts a new form to the same frame. The fields are redrawn, the height set again. |
destroy() | function | Removes the frame and the message listener. |
The onResult answer object
| Member | Type | Meaning |
|---|---|---|
type | text | Always “result”. |
name | text | The result's name from your form. |
figure | text | The figure in the region's format, as the visitor sees it. |
unit | text | The result's unit or an empty string. |
text | text | The figure and the unit in one string. |
The onError call
| Parameter | Type | Meaning |
|---|---|---|
code | text | A code from the error table, for example UNKNOWN_SLOT. |
detail | object | The 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.
| Message | Shape | Meaning |
|---|---|---|
| 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.
| Field | Type | Meaning |
|---|---|---|
v | number | Always 1. Any other value is refused. |
formula | text | The calculation written with field ids, the operations and the functions described below. |
fields | object | The 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>.name | text | The label the visitor sees above the field. |
fields.<id>.unit | text, optional | The field's unit, written as a stem from the unit list. Any other text is shown as a label and converts nothing. |
fields.<id>.value | text, optional | The value the field opens with, written with a dot as the decimal separator. |
fields.<id>.percent | true or false, optional | true 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. |
result | object | The result the frame shows below the fields. |
result.name | text | The result's label. |
result.unit | text, optional | The result's unit. It must match the unit the formula gives. |
result.percent | true or false, optional | true if the formula gives its result in percent: a result of 25 is shown as 25 %. |
key | text, optional | Reserved for the future. Version 1 ignores it. |
Minimal form
One field without a unit and a result without a unit. Everything else is optional.
{
"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.
{
"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.
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-au"
});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.
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-au"
});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.
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-au"
});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.
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-au"
});
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-au"
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.
var calc = Numnote.embed("#calculator", formA, { region: "en-au" });
calc.update(formB); // Three fields
calc.destroy(); // RemoveErrors: 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.
Numnote.embed("#calculator", {
"v": 1,
"formula": "area / coverage",
"fields": {
"area": {
"name": "Area",
"unit": "m²",
"value": "40"
}
},
"result": {
"name": "Paint"
}
}, {
region: "en-au",
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.
<iframe id="calculator" src="https://numnote.com/en-au/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
| Notation | Meaning | Example |
|---|---|---|
12.5 | A number. The decimal separator in the formula is always a dot. | price * 1.2 |
a_1 | A 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 |
mod | Remainder 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.
mcmmmkminftydmim²cm²mm²km²ahaft²yd²acm³LmLcm³dm³USgalkggtlbozsminhdmowkyrJWhkWhMWhcalkcalWkWPabaratmmmHgpsiNVAOhmHzK°C°Frad°molpcpkARSAUDBRLCADCHFCLPCNYCOPCZKDKKEURGBPHKDHUFIDRILSINRISKJPYKRWMXNMYRNOKNZDPHPPLNRONSEKSGDTHBTRYUAHUSDZAR
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.
| Accepted | Meaning |
|---|---|
km + km | one unit with itself |
km * 2 | a unit with a plain number |
km / km | a ratio of the same units, a plain number |
km + 10 % | a percentage of a unit, the same unit |
| Refused | Meaning |
|---|---|
km + kg | a sum of different units |
m * m | a product of two units |
sqrt(m) | a power or a root of a unit |
km / h | a 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
| Code | Meaning |
|---|---|
NOT_JSON | The message is not valid JSON. |
NOT_AN_OBJECT | The message, a field or the result is not an object. |
VERSION | The version is missing or is not 1. |
MISSING | A required key is missing. |
WRONG_TYPE | A value has the wrong type. |
UNKNOWN_KEY | The form has a key that version 1 does not know. |
TOO_LONG | The formula is longer than the limit. |
TOO_MANY_FIELDS | The form has more fields than allowed. |
BAD_SLOT_ID | A field id does not follow the rule for ids, or it is the word mod or the name of a function. |
EMPTY_NAME | A name is empty. |
BAD_VALUE | A field's value is not a decimal number written with a point. |
UNUSED_FIELD | A field is declared but the formula never uses it. |
EMPTY_FORMULA | The formula is empty. |
BAD_CHARACTER | The formula has a character that it may not contain. |
UNEXPECTED | A character stands where the formula does not allow it. |
UNCLOSED | A bracket is not closed. |
TOO_DEEP | The formula is nested too deeply. |
UNKNOWN_SLOT | The formula names a field that the form does not declare. |
UNKNOWN_FUNCTION | The formula calls a function that does not exist. |
UNSUPPORTED_FUNCTION | The function exists in Numnote but the frame does not run it yet. |
WRONG_ARGUMENTS | A function is called with the wrong number of arguments. |
UNIT_IN_FORMULA | A unit is written in the formula. Give it to a field instead. |
UNITS_DO_NOT_MEET | The units of an operation cannot be combined. |
RESULT_UNIT | The formula gives a unit other than the one declared for the result. |
BLOCKED | The 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
| Code | Meaning |
|---|---|
UNKNOWN_UNIT | A value was typed in a unit that its field does not accept. |
DIVISION_BY_ZERO | A division by zero. |
ROOT_OF_NEGATIVE | An even root of a negative number. |
ROOT_DEGREE_INVALID | The degree of a root is not a positive whole number. |
LOG_BASE_INVALID | The base of a logarithm is not valid. |
LOG_ARGUMENT_NOT_POSITIVE | The argument of a logarithm is not positive. |
OVERFLOW | The result is too large to be written. |
TAN_UNDEFINED | The tangent is not defined there. |
COT_UNDEFINED | The cotangent is not defined there. |
ASIN_OUT_OF_DOMAIN | The argument of the arcsine is outside its domain. |
ACOS_OUT_OF_DOMAIN | The argument of the arccosine is outside its domain. |
COTH_OUT_OF_DOMAIN | The hyperbolic cotangent can't be computed for zero. |
ACOSH_OUT_OF_DOMAIN | The inverse hyperbolic cosine (area cosine) can't be computed for a number less than 1. |
ATANH_OUT_OF_DOMAIN | The inverse hyperbolic tangent (area tangent) can't be computed unless the number is strictly between −1 and 1. |
ACOTH_OUT_OF_DOMAIN | The inverse hyperbolic cotangent (area cotangent) can't be computed unless the absolute value of the number is greater than 1. |
FACTORIAL_DOMAIN | The factorial needs a whole number that is not negative. |
NOT_A_NUMBER | A field holds text that is not a number. |
BAD_PROGRAM | The 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.