View source for Template:Calculator/doc

This template is for creating interactive calculators. It requires the [[mediawiki:Gadget-calculator.js|calculator gadget]]. The calculator works by default. You can opt out at: [[Special:Preferences#mw-prefsection-gadgets-gadget-section-template-gadgets|Preferences > Gadgets > Template Gadgets > Enables javascript Calculator template]]. All pages using this system are added to [[:Category:Pages using gadget Calculator]].

You can use this template multiple times on a page to make input widgets, with some of the widgets using also the results of other widgets, like a spreadsheet cell that does a computation  based on results of computations in other cells.

You can use {{tl|Calculator label}} to mark text as a label for a calculator widget.

Statistics for this template are available at [https://grafana.wikimedia.org/d/c3c5b6f3-3e71-49fe-b4e1-9d5d2937eddc/gadget-stats-graphite-history?orgId=1&refresh=1m&var-prefix=gadget_calculator&var-metric=All graphite]

==Examples==
Here is a simple example to multiply two numbers. We invoke two calculator templates with no formula that act as input fields. We then invoke a third instance which has a formula for multiplying the other two cells. Note that formulas only take affect after the user interacts, so all cells need a default to use as initial value before user interaction.
<syntaxhighlight lang="wikitext">
{{calculator|id=a|default=2|size=4}} × {{calculator|id=b|default=2|size=4}} = {{calculator|id=c|formula=a*b|default=4|type=plain}}
</syntaxhighlight>
produces:

{{calculator|id=a|default=2|size=4}} × {{calculator|id=b|default=2|size=4}} = {{calculator|id=c|formula=a*b|default=4|type=plain}}

<syntaxhighlight lang="wikitext">
{{calculator|id= km   |type= number|size= 9|default= 1.609344|formula= miles*1.609344}} km = 
{{calculator|id= miles|type= number|size= 9|default= 1       |formula= km/1.609344   }} miles 
</syntaxhighlight>
produces:

{{calculator|id= km   |type= number|size= 9|default= 1.609344|formula= miles*1.609344}} km = 
{{calculator|id= miles|type= number|size= 9|default= 1       |formula= km/1.609344   }} miles 


===BMI calculator metric===
You can put widgets inside a wikitable.
<syntaxhighlight lang="wikitext">
{| class="wikitable" style = "float: left; margin-left:15px;"
|+ Metric
|-
| {{calculator label|Weight|for=weightkg}} || {{calculator|id=weightkg|size=3|default=80 }} kg
|-
| {{calculator label|Height|for=heightcm}} || {{calculator|id=heightcm|size=3|default=160}} cm
|-
| BMI || '''{{calculator|id=bmimetric|type=plain|formula=round(weightkg/pow(heightcm/100,2))|default=31|style=min-width:3ch;display:inline-block}} kg/m<sup>2</sup>'''
|}
</syntaxhighlight>

{| class="wikitable" style = "float: left; margin-left:15px;"
|+ Metric
|-
| {{calculator label|Weight|for=weightkg}} || {{calculator|id=weightkg|size=3|default=80}} kg
|-
| {{calculator label|Height|for=heightcm}} || {{calculator|id=heightcm|size=3|default=160}} cm
|-
| BMI || '''{{calculator|id=bmimetric|type=plain|formula=round(weightkg/pow(heightcm/100,2))|default=31|style=min-width:3ch;display:inline-block}} kg/m<sup>2</sup>'''
|}
{{-}}

===BMI calculator imperial===
You can also put widgets inside an HTML table.

<syntaxhighlight lang="wikitext">
<table class="wikitable">
<tr><td>Imperial</td></tr>
<tr><td>Weight</td><td>{{calculator|id=weight      |size=3}} lbs</td></tr>
<tr><td>Height</td><td>{{calculator|id=heightFeet  |size=1}} feet {{calculator|id=heightInches|size=2}} inches</td></tr>
<tr><td>BMI</td><td>'''{{calculator|id=bmi         |type=plain|formula=round(100*weight*703/pow(heightFeet*12+heightInches,2))/100}} kg/m<sup>2</sup>'''</td></tr>
</table>
</syntaxhighlight>

<table class="wikitable">
<tr><td>Imperial</td></tr>
<tr><td>Weight</td><td>{{calculator|id=weight|size=3}} lbs</td></tr>
<tr><td>Height</td><td>{{calculator|id=heightFeet|size=1}} feet {{calculator|id=heightInches|size=2}} inches</td></tr>
<tr><td>BMI</td><td>'''{{calculator|id=bmi|type=plain|formula=round(100*weight*703/pow(heightFeet*12+heightInches,2))/100}} kg/m<sup>2</sup>'''</td></tr>
</table>

===Other===
There is an extended gallery of examples at [[Template:Calculator/doc/examples]]. All pages that use this template are included in [[:Category:Pages using gadget Calculator]].
*[[mdwiki:CHA2DS2–VASc score]]
*[[:Category:Pages using gadget Calculator]]

===Buttons===
When pressed, the {{tl|calculator button}} updates a form field.
<pre>
{{calculator button|contents=Click me!|for=buttoncount|formula=buttoncount+1|type=default}} 

The button has been clicked {{calculator|type=plain|default=0|id=buttoncount}} times.
</pre>
{{calculator button|contents=Click me!|for=buttoncount|formula=buttoncount+1|type=default}} 

The button has been clicked {{calculator|id=buttoncount|type=plain|default=0}} times.

===Labels ===
A {{tl|calculator label}}
# adds a text label to a calculator widget, improving its accessibility. Screen readers will use labels when informing the user which text box they have focused on.
# when clicked, give focus to the input widget, especially helpful for small widgets
# selects/deselects a checkbox/radio target.

<pre>
{{calculator|type=checkbox|id=checklabelex}} {{calculator label|label=Please click this label|for=checklabelex}}
</pre>
{{calculator|type=checkbox|id=checklabelex}} {{calculator label|label=Please click this label|for=checklabelex}}

==Formula==
Formulas use normal math syntax, with english words representing other input boxes. e.g. sin(1+foo*2) would multiply the foo box by 2, add 1 and take the sine of the whole thing. All calculations are done using [[w:IEEE 754|IEEE 754 double precision floating point numbers]].

Keep in mind that the formula is recalculated only when the user interacts with the calculator. Prior to any user interaction, the "default" parameter to the calculator template is shown even if it is different from what the formula would give initially. Thus you should set the default parameter to what you expect the result of computing the formula will be.

=== Supported operators ===
Operators supported include: +, -, *, ×, /, ÷, %  (percent is the modulo operator)<ref name="moduhuh">Note that this can return negative values if the operands are negative. To ensure that modulo ''n'' returns a number between 0 and ''n'' that fits with the values above zero, you must wrap it. A good way to do this is add the modulus and then take it again -- for positive numbers this will not change them, but for negative numbers this brings them up into the positive range. For example: <syntaxhighlight lang="wikitext" inline>(a - b)%15</syntaxhighlight> → <syntaxhighlight lang="wikitext" inline>(((a - b)%15)+15)%15</syntaxhighlight> </ref>. Exponentiation must use the pow() function.

=== Math functions ===
Math functions supported include: 'abs', 'acos', 'acosh', 'asin', 'asinh', 'atan', 'atan2', 'atanh',  'cbrt', 'ceil', 'cos', 'cosh', 'exp', 'expm1', 'floor', 'hypot', 'log', 'log10', 'log2', 'log1p', 'max', 'min', 'pow', 'random', 'sign', 'sin', 'sinh', 'sqrt', 'tan', 'tanh', 'trunc', 'clz32'

These have the [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math same definition as in javascript]. In particular, that means that log() is log base-e. The exception is round, for which we use our own definition.

=== Additional functions ===
The following additional functions are supported which are not from javascript Math library:
<!--{|class="wikitable sortable"
!! rowspan=2 | Function
!! colspan=6 | Arguments
!! rowspan=2 | Returns
|-
!! style="max-width: 16%;" | 1
!! style="max-width: 16%;" | 2
!! style="max-width: 16%;" | 3
!! style="max-width: 16%;" | 4
!! style="max-width: 16%;" | 5
!! style="max-width: 16%;" | 6
|-
|-
| '''and'''
| *
| *
| *
| *
| *
| *
| [[Logical and|Logical ''and'']]
|-
| '''bool'''
| *
|
|
|
|
|
| [[Boolean|Boolean]] (0 if value close to 0 or NaN), otherwise 1)
|-
| '''coalesce'''
| *
| *
| *
| *
| *
| *
| Returns first number that is not NaN
|}-->
;and
:Logical ''and'' of all arguments (can take more than 2). This operator short circuits like lua, and returns first false argument. Wrap in bool() if you want a 1 or a 0. See bitand() for bitwise and
;bool
:Return 0 if value is very close to 0 or NaN, otherwise 1
;coalesce
:return the first argument that is not NaN.
;ifbetween
:return either fourth or fifth argument depending on if the first argument is between the second or third argument. Comparison is not fuzzy. The last two arguments are optional and default to 1 and 0 respectively.
;ifequal
:If first and second argument are the same, accounting for floating point error. The last two arguments are optional and default to 1 and 0 respectively.
;iffinite
:if the first argument is finite return second argument, otherwise return third argument. The last two arguments are optional and default to 1 and 0 respectively.
;ifgreater
:return third or fourth argument depending on if first argument is > second argument. Comparison is fuzzy to account for floating point error. Use ifpositive() if you don't want that. The last two arguments are optional and default to 1 and 0 respectively.
;ifgreaterorequal
:return third or fourth argument depending on if first argument is >= second argument. Comparison is fuzzy to account for floating point error. Use ifpositive() if you don't want that. The last two arguments are optional and default to 1 and 0 respectively.
;ifless
:Return third or fourth argument depending on if first argument is < second argument. Comparison is fuzzy to account for floating point error. Use ifpositive() if you don't want that. The last two arguments are optional and default to 1 and 0 respectively.
;iflessorequal
:return third or fourth argument depending on if first argument is <= second argument. Comparison is fuzzy to account for floating point error. Use ifpositive() if you don't want that. The last two arguments are optional and default to 1 and 0 respectively.
;ifnan
:if first argument is not a number (NaN), return second argument, otherwise third argument. The last two arguments are optional and default to 1 and 0 respectively.
;ifpositive
:if first argument is ≥ 0 return second, otherwise return third. Note this does not account for floating point rounding. You can use this if you need precise control over the comparison. The last two arguments are optional and default to 1 and 0 respectively.
;ifzero
:if first argument is epsilon away from zero, return second argument, otherwise third argument. The last two arguments are optional and default to 1 and 0 respectively.
;index
:Allows treating variables like an array with an index evaluated at runtime. <code>index( foo, 2+3 )</code> is the same as <code>foo5</code>. The first argument must be an identifier (Nested index() is not allowed). The second argument must evaluate to an integer greater than or equal to 0. If either of these two arguments are invalid, NaN is returned. The third argument is returned if the arguments are valid but the result references a variable that does not exist. If unspecified the third argument defaults to NaN.
;jsround
:Use javascript round. This does round half towards positive infinity with a precision of 0. See [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round mdn docs]
;not
:Return 1 if value is very close to 0 or NaN, otherwise 0
;or
:Logical or of all arguments (can take more than 2). This operator short circuits like lua, and returns first true argument. Wrap in bool() if you want a 1 or a 0
;round
:A round function. Unlike javascript round(), this implements round half away from zero ("commercial rounding"). It takes an optional second argument to say how many decimal digits to round to. e.g. round( 3.125, 2 ) = 3.13, round( -3.125, 2 ) = -3.13.
;xor
:Logical exclusive or. Can only take 2 arguments, always return 1 or 0.
;switch
:The first argument is compared to the second argument, if it is ≤ the second argument, then return the third. Otherwise compare the first argument with the fourth argument, if ≤ return the fifth argument, and so forth. If it is not ≤ to any of the even arguments, and there are an even number of arguments return the last argument, otherwise return NaN. For example if foo is 5 then <code>switch(foo,2,10,4,20,5,30,7,80,-1)</code> returns 30.
;radiogroup
:Return the value of the radio group specified by the first argument. Unlike most functions, this does not take a field identifier but a radio group name. The value of the radio group is the value of whichever element of the radio group is currently checked (or NaN if none are). The value of a checked radio button is either the value of the formula if it was checked by a formula, or the value parameter if it was checked by a human.
;bitand
:Treat all args as 32 bit 2's complement integer and bitwise AND them together. Equivalent to the & operator in javascript and most programming languages. Can take any number of arguments.
;bitor
:Treat all args as 32 bit 2's complement integer and bitwise OR them together. Equivalent to the | operator in javascript and most programming languages. Can take any number of arguments.
;bitxor
:Treat all args as 32 bit 2's complement integer and bitwise XOR (exclusive or) them together. Equivalent to the ^ operator in javascript and most programming languages. Can take any number of arguments.
;bitnot
:Treat argument as a 32 bit 2's complement integer and bitwise NOT it. Equivalent to the ~ operator in javascript and most programming languages. Can take only 1 argument.
;bitleftshift
:Treat first argument as 32 bit 2's complement integer and shift it left by the amount specified in second argument. Equivalent to << in javascript.
;bitlogicrightshift
:Treat first argument as 32 bit 2's complement integer and shift it right (logically) by the amount specified in second argument. Equivalent to >>> in javascript.
;bitarithrightshift
:Treat first argument as 32 bit 2's complement integer and shift it right (arithmetically) by the amount specified in second argument. Equivalent to >> in javascript.
;if
:Opposite of ifzero(). If the first argument is true then return the second, otherwise the third.
;getclick
:This function only works in buttons. It is designed to allow implementing image maps. If the first argument is x return the x offset in pixels of where in the element the user clicked, and similar for y. If the first argument is percentx then return the x coordinate as a percentage and similar for percenty. Note if the user clicks on a border, the result may be negative or greater than 100%.
;timer
:Determine if a repeating button has been activated. If no arguments will return 1 if any repeating button is active, 0 otherwise. If there is a first argument, then that is the id of the button to check. The second argument is the value to return if the button is active. The third is the value to return if it is not active.
;timeriterations
:How many iterations the button has done so far. If no arguments, then any button, otherwise the first one is which button to check.
;timertime
:How much time has passed between when the button was pressed and the most latest iteration was executed. First optional argument is the id of the button to check.

=== Numbers ===
Numbers can be 
* integers
* decimals
* scientific notation. For example: 1, 2.84543, 3.12E6, -5, 3.45×10⁻⁴⁵

==== Supported constants ====
* [[IEEE_754#Infinities|Infinity]]
* [[IEEE_754#Infinities|-Infinity]]
* [[NaN]]
* pi
* π
* [[Machine epsilon|EPSILON]]
* true (Is equal to 1)
* false (Is equal to 0)

== Scoping ==
	
If the calculator widgets are contained within an element with the class <code>calculator-container</code>, then the ids are scoped to this element. This allows you to use the same ids multiple times on the same page without them interfering with each other. If the scoping element has the attribute <code>data-calculator-refresh-on-load="true"</code>, then the calculator widgets are refreshed on first page load before the user interacts with it. Please note that labels are not affected by scoping and will likely go to whatever the next element in the document is with the correct id.
	
For example:
	
<syntaxhighlight lang="wikitext">
<div class="calculator-container" data-calculator-refresh-on-load="true">
{{calculator label|scopedfield:}} {{calculator|type=text|id=scopedfield|default=3.14}}<br>
This formula is updated before user interaction: {{calculator|type=plain|formula=scopedfield|default=No value}}
</div>
This formula is not updated because it is in a different scope: {{calculator|type=plain|formula=scopedfield|default=No value}}
</syntaxhighlight>
	
Produces the following:
	
<div style="border: 1px dashed blue; padding: 2px;">
<div class="calculator-container" data-calculator-refresh-on-load="true">
{{calculator label|for=scopedfield|scopedfield:}} {{calculator|type=text|id=scopedfield|default=3.14}}<br>
This formula is updated before user interaction: {{calculator|type=plain|formula=scopedfield|default=No value}}
</div>
This formula is not updated even after user interaction because it is in a different scope: {{calculator|type=plain|formula=scopedfield|default=No value}}
</div>

Instead of using the css classes directly, you can also use the {{tl|Calculator ifenabled}} with the scoped parameter.
==Mapping==
Calculator formulas only work with numbers. However you can use mappings to convert numbers into text when they enter or leave the system. This allows for a very limited form of text input and output.

A mapping is a JSON object linking text strings to numbers. If the user inputs a specific (case-sensitive but whitespace trimmed) string on the list, it gets converted to the specified number. If a number is being outputted, it is checked to see if that number is in the mapping.

Mappings only work for text, plain and select. The values in the mapping object must have a JSON number type, except for the special values "default", "NaN", "Infinity" and "-Infinity" which must be strings. Mapping values are plain text - no wikitext formatting is allowed.

For example:
<syntaxhighlight lang="wikitext">{{calculator label|
	label=What is your favourite Encyclopedia?
	|for=encyc
}}
{{calculator
	|id=encyc
	|type=text
	|mapping={
		"Wikipedia": 1,
		"WikiPedia": 1,
		"wikipedia": 1,
		"Encyclopædia Britannica": 2,
		"Encyclopaedia Britannica": 2,
		"Britannica": 2,
		"britannica": 2,
		"Encarta": 3,
		"encarta": 3,
		"Nupedia": 4,
		"nupedia": 4
	}
}}
{{calculator
	|formula=encyc
	|type=plain
	|mapping={
		"I haven&apos;t heard of that": "default",
		"I love Wikipedia too!": 1,
		"I guess it is ok": 2,
		"I wish I kept my CD.": 3,
		"rip": 4
	}
}}
</syntaxhighlight>
Makes:
<div class="calculator-container" style="margin-left: 2em; border: 1px dashed grey; padding: 1em">
{{calculator label|
	label=What is your favourite Encyclopedia?
	|for=encyc
}}
{{calculator
	|id=encyc
	|type=text
	|mapping={
		"Wikipedia": 1,
		"WikiPedia": 1,
		"wikipedia": 1,
		"Encyclopædia Britannica": 2,
		"Encyclopaedia Britannica": 2,
		"Britannica": 2,
		"britannica": 2,
		"Encarta": 3,
		"encarta": 3,
		"Nupedia": 4,
		"nupedia": 4
	}
}}
{{calculator
	|formula=encyc
	|type=plain
	|mapping={
		"I haven&apos;t heard of that": "default",
		"I love Wikipedia too!": 1,
		"I guess it is ok": 2,
		"I wish I kept my CD.": 3,
		"rip": 4
	}
}}
</div>
==CSS==
	
You can use CSS to adjust the display, either via TemplateStyles or inline styles.
	
* For checkboxes and radio buttons, you can use the [https://developer.mozilla.org/en-US/docs/Web/CSS/:checked :checked] pseudo selector. This can be very useful when combined with sibling css selectors (~) or :has()
* You can look for the class names calculator-value-true and calculator-value-false. This is especially useful with the passthru type of field. See {{tl|Calculator-hideifzero}} for an example.
* You can target the <code>data-calculator-field-value</code> attribute. e.g. #calculator-field-fieldidhere[calculator-field-scopedfield^="3."] would select the field if it is >= 3.0 and < 4.0.
* You can use css variables for more complex calculations (Only in inline styles)

Some examples:

<syntaxhighlight lang="wikitext">
<div style="border:dotted thick hsl( var(--calculator-color, 30), 100%, 50%);padding: 1em;">	
{{calculator label|for=color|Adjust color of border}}:&nbsp;&nbsp;{{calculator|id=color|type=range|min=0|max=300|default=30|style=vertical-align: text-bottom}}
</div>
</syntaxhighlight>

<div style="border:dotted thick hsl( var(--calculator-color, 30), 100%, 50%);padding: 1em;">	
{{calculator label|for=color|Adjust color of border}}:&nbsp;&nbsp;{{calculator|id=color|type=range|min=0|max=300|default=30|style=vertical-align: text-bottom}}
</div>

<div class="calculator-container" style="border: solid thin black; padding: 0.5em;margin-top:1em>
Superimpose an image with coordinates based on a calculator widget:
<div class="floatnone noresize" style="position: relative; width: 500px; "><div style="position: absolute; left: calc( var( --calculator-x,385)*1px  ); bottom: calc( var( --calculator-y,141.7)*1px  ); padding: 0;">[[Image:Red pog.svg|10px|link=|alt=|class=|]]</div>[[Image:Body_roundness_index_graph.svg|500px|alt=|class=|]]</div>
{{calculator|id=x|formula=((waist-50)/130)*450+20|type=hidden}}
{{calculator|id=y|formula=((height-140)/60)*208+10|type=hidden}}
{{calculator label|for=height|Height:}} {{calculator|id=height|type=number|size=5|default=178|min=140|max=200}}&thinsp;cm.&nbsp; 
{{calculator label|for=waist|Waist:}} {{calculator|id=waist|type=number|size=5|default=155|min=50|max=180}}&thinsp;cm.
</div>

== Codex ==
It is possible to make widgets be in [[mw:Codex|MediaWiki (Codex)]] style instead of OS style. You can use most codex widgets that have a CSS-only version. See https://doc.wikimedia.org/codex/latest/components/demos/

Many codex style widgets have separate templates. When making a label, the {{tl|Calculator label}} template has a parameter to output a codex style label
	
{| class="wikitable"
! Template !! Example
|-
|| {{tl|Calculator codex text}} || {{Calculator label|codex=true|description=Short description text|label=Label text|for=foo}}
{{calculator codex text|default=42|id=foo}}
|-
|| {{tl|Calculator codex radio}} || <div role="radiogroup" aria-labelledby="mygrouplabel" id="myradiogroup">
{{calculator label|codex=1|label=This is a group of options|id=mygrouplabel}}
{{Calculator codex radio|id=myradio1|name=group2|label=First option|description=Additional text describing the first option}}
{{Calculator codex radio|id=myradio2|name=group2|label=Second option|description=Additional text describing the first option}}
{{Calculator codex radio|id=myradio3|name=group2|label=Third option}}
</div>
|-
|| {{tl|Calculator codex checkbox}} || {{Calculator codex checkbox|id=mycheck|name=group1|label=First option|description=Additional text describing the first option}}
|-
|| {{tl|Calculator codex toggle}} || {{Calculator codex toggle|id=mycheck|label=My toggle|description=Additional text describing the toggle}}
|-
|| <nowiki>{{calculator|type=select|class=cdx-select}}</nowiki> || {{calculator|type=select|class=cdx-select|mapping={"numbers":{"one":1, "two":2}, "Letters": { "a": -1, "b": -2 }, "Other": 500} }}
|-
|| {{tl|Calculator button}} || {{calculator button|type=default|weight=normal|contents=default}} {{calculator button|type=progressive|weight=normal|contents=progressive}} {{calculator button|type=destructive|weight=normal|contents=destructive}}<br>
{{calculator button|type=default|weight=primary|contents=default}} {{calculator button|type=progressive|weight=primary|contents=progressive}} {{calculator button|type=destructive|weight=primary|contents=destructive}}
|}
See the individual template doc pages for all the options.

== Fallback ==

Users who do not have [[Special:Preferences#mw-input-wpgadget-Calculator|the gadget enabled in their preferences]] or have JS disabled, will not see the input boxes. Instead they will just see the ''default'' value for each box. With a good choice of default, this can be sufficient.

For example, if you have <syntaxhighlight lang="wikitext" inline>'''sin({{calculator|id=sine|type=text|default=0.5|size=4}}π)={{calculator|type=plain|default=1.00|decimals=2|formula=sin(sine*π)|id=sineres}}'''</syntaxhighlight> to make '''sin({{calculator|id=sine|type=text|default=0.5|size=4}}π)={{calculator|type=plain|default=1.00|decimals=2|formula=sin(sine*π)|id=sineres}}''', the non-js user will lose the interactivity, but they will still see the equation.

If you want more sophisticated fallbacks, you can use the <code>calculatorgadget-enabled</code> and <code>calculatorgadget-fallback</code> CSS classes.

<syntaxhighlight lang="wikitext">
<div class="calculatorgadget-enabled" style="display:none">This text is only shown if the gadget is enabled. {{calculator|type=text|size=20|default=100|id=xyz}} </div>
<div class="calculatorgadget-fallback">This text is only shown if the gadget is disabled</div>
</syntaxhighlight>

Which produces:
<div class="calculatorgadget-enabled" style="display:none">This text is only shown if the gadget is enabled. {{calculator|type=text|size=20|default=100|id=xyz}} </div>
<div class="calculatorgadget-fallback">This text is only shown if the gadget is disabled</div>

Alternatively, you can use the {{tl|Calculator ifenabled}} template to do this.

When using this template you should always be sure it still looks good even if the gadget is unavailable. You should test what the page looks like under print preview, as well as with [{{fullurl:{{FULLPAGENAME}}|safemode=1}} ?safemode=1] appended to the url (Which is similar to what someone using the mobile app would see). You can use http://bawolff.net/wiki-nojs.htm to test what a page looks like with no javascript at all.
== Best practices ==
Calculator templates have a lot of power, which means the template author has more responsibility to create good templates.

The calculator template cannot be displayed for everyone. People without javascript or people using a screen reader will likely get a very different experience. You should aim to have equivalent content, or failing that, graceful degradation, for such users. You can use {{tl|calculator ifenabled}} to help with this. Generally most calculator fields will show their default value if no javascript is enabled.

* Always check the page rendering in different modes:
** Does the template look ok in dark mode
** Does the template look ok with javascript disabled (Test by adding ?safemode=1 to end of the url). Keep in mind that users of the Wikipedia app will see something very similar to what it looks like with javascript disabled.
** Does the page look ok in print preview.
** Does the page look ok on narrow screens, such as what a mobile phone would have. You can use [[media queries]] with template styles to adjust the display depending on how wide the screen is.
** Does the template read ok if using a screen reader (Many screen readers are free to download if you need to test).
*** One thing that can help with screen readers is to set appropriate values for the <code>role</code> and <code>aria-live</code> parameters. This can tell screen readers whether to read out content that has recently changed. Most calculator templates default to an aria-live value of <code>polite</code> (type=passthru defaults to no aria-live), but you can override this. If you are showing something to the user a little at a time, use role=log to tell the screen reader that new content is expected to come. Be sure to set aria-live=off if you use calculator to display some data that is unimportant and should not be read out automatically on change. See [https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions mdn] for more info <!-- TODO when testing orca, it seemed like it was really important to set aria-live="off" to subelements of a live region, so they wouldn't be read independently of the main region, but not sure if that is best practise or orca just being weird -->
***Every input widget should have a corresponding {{tl|calculator label}}. This is one of the most important thing to do for accessibility. If you cannot do that for some reason, or the label would not make sense when read out, you should use the aria-label option to provide an alternative label for screen readers.
* Substituting form elements may cause page reflows, which are ugly and bad for performance. If possible try setting explicit width/height with css to prevent page reflows, if applicable. This is especially important if the calculator element is near the beginning of the page.

== Template arguments ==
=== For all types ===
;id
:The id for this field, [[English_alphabet|English characters]] only, used in formulas of other fields. It must be unique on the page. Can be omitted if the field is not used as a value in any formulas.
;default
:The starting value
;formula
:The formula to calculate this field. [[#Formula|See above]] for what is supported
;placeholder
:Placeholder text that shows up light grey when there is no input
;readonly
:Make field read only
;size
:how big to make the input box (In terms of number of letters that can fit in the box)
;style
:Custom CSS to use for the element.
;class
:Extra class to add to the element
;class-live
:CSS class to add only if the gadget is active on the page. Added after widgets are processed.
;aria-live
:Controls how screen readers read out this field if it changes when not being focused. Default is "polite" or "off" depending on field type. Can set to "off" if you don't want a screen reader to read the field when it changes.
;{{visible anchor|fieldTypes|text=type}}
:Type of field. Currently supported are number, text, plain, radio, checkbox, range, select hidden, passthru. 
::{|
|-
| class="propmt"| checkbox 
| {{calculator|id=wet|default=1|type=checkbox}} {{calculator label|Wet|for=wet}}
|-
|
|{{calculator|id=big|default=0|type=checkbox}} {{calculator label|Big|for=big}}
|-
| hidden
| colspan=2|{{calculator|default=160|type=hidden}} Not visible, does not take space. Useful for intermediate results in formulas.
|-
| number
| colspan=2|{{calculator|id=waistCm|default=80|type=number|size=5|step=5|min=1|formula=wideness}}
|-
| passthru
| colspan=2|{{calculator|default=Is not visibly changed but the css class changes based on the formula|type=passthru|formula=wet}} This does nothing by itself but can be combined with templatestyles, see {{tl|calculator-hideifzero}} for an example.
|-
| plain 
| colspan=2|{{calculator|id=whtr|formula=heightCm/waistCm|default=2|precision=8|type=plain}}
|-
| radio 
| {{calculator|id=metric|name=unit|default=1|type=radio}} {{calculator label|Metric|for=metric}}
|-
|
| {{calculator|id=imperial|name=unit|default=0|type=radio}} {{calculator label|Imperial|for=imperial}}
See also: [[Template:Calculator_label|Calculator_label]].
|-
| text
| colspan=2|{{calculator|id=heightCm|default=160|type=text|size=5|formula=tallness}}

|-
| range
| {{calculator|default=160|id=tallness|type=range|min=40|max=250|formula=heightCm|style=writing-mode: vertical-lr;height:4em}} {{calculator|default=160|id=wideness|type=range|min=1|max=350|formula=waistCm}}

|-
| select
| {{calculator|value=5|mapping={"one":1, "five": 5}|type=select}}

|}
:Checkbox, hidden, passthru and radio can be useful in combination with TemplateStyles to hide and show fields, see [[Template:Body_roundness_index]], [[Template:Body roundness index/styles.css]] and [[template:Calculator-hideifzero]] for examples. See also the [[#Codex]] section above for how these field types can look different in Codex mode.

=== For number and range type only ===
:;max
::Max number allowed (number type only)
:;min
::Min number allowed (number type only)
:;step
::How big the interval is for type=number and type=range inputs. Can be a number or the value "any"

=== For radio type only ===
:;name
::When using type=radio, the name of the radio group. Only one radio field in a group with the same name may be checked at once. In formulas, you can use this with the <code>radiogroup()</code> function.

=== For radio, checkbox ===
:;value
::What is the value of this control. When checked by a human (but not when checked by a formula), the field will have this value
:;checked
::Mark this field as checked by default. Overrides <code>default</code> parameter.

=== For select ===
:;mapping
::What items to have in the select field. JSON object mapping field names as strings to numbers. Can be up to two layers deep. e.g. <syntaxhighlight lang="json" inline>{ "item1": 1, "item3": 3, "invalid": "NaN", "Group of options": { "suboptiona": 1.1 } }</syntaxhighlight>
:;value
::Which item to have selected initially. Same as default except not outputted for non-javascript users.

=== For plain, text and number type ===
:;decimals
::Format field to this many decimal digits.
:;exponential-precision
::Format field to this many significant digits in scientific notation.
:;precision
::Format field to this many significant digits.
=== For plain and text type ===
:;NaN-text
::Use this text instead of NaN when result is not a number (Only works type=plain and type=text)
:;mapping
::Convert input and output between strings and numbers. Specify conversion as a JSON object. e.g. <syntaxhighlight lang="json" inline>{ "item1": 1, "item3": 3, "invalid": "NaN", "fallback string": "default" }</syntaxhighlight>

<templatedata>
{
	"params": {
		"id": {
			"description": "The id for this input. This is used to reference it in formula of other calculator templates",
			"required": true,
			"type": "string"
		},
		"type": {
			"description": "What type of input box",
			"type": "string",
			"suggestedvalues": [
				"plain",
				"number",
				"text",
				"radio",
				"checkbox",
				"passthru",
				"hidden",
				"range",
				"select"
			],
			"suggested": true,
			"required": true
		},
		"formula": {
			"description": "Formula to calculate this field",
			"suggested": true,
			"example": "3*log(a)",
			"type": "string"
		},
		"class": {
			"description": "CSS classes to add",
			"type": "string"
		},
		"class-live": {
			"description": "CSS class to add only if gadget is active on the page",
			"type": "string"
		},
		"decimals": {
			"description": "Format to a fixed number of decimal digits [Only applies to type=number or type=plain]",
			"example": "2",
			"type": "number"
		},
		"default": {
			"description": "Default value for this field",
			"suggested": true,
			"type": "string"
		},
		"exponential-precision": {
			"description": "Format to this many significant digits, using scientific notation [Only applies to type=number or type=plain]",
			"example": "2",
			"type": "number"
		},
		"max": {
			"description": "max number allowed (type=number inputs only)",
			"type": "number"
		},
		"min": {
			"description": "min number allowed (type=number inputs only)",
			"type": "number"
		},
		"name": {
			"description": "For type=radio what group to assign the radio button to"
		},
		"NaN-text": {
			"description": "Use this text instead of NaN to signify \"not a number\". Only applies to format=plain or format=text. Plaintext only; wikitext is not supported",
			"example": "Invalid calculation",
			"type": "string"
		},
		"placeholder": {
			"description": "Text to put as a placeholder in empty input",
			"type": "string"
		},
		"precision": {
			"description": "Format to this many significant digits, using decimal notation except for really large numbers [Only applies to type=number or type=plain]",
			"example": "2",
			"type": "number"
		},
		"readonly": {
			"description": "Make input box readonly to user input",
			"type": "boolean"
		},
		"size": {
			"description": "Size of input box (How many characters it will fit)",
			"type": "number"
		},
		"step": {
			"description": "How much to increment a type=number input box",
			"example": "2.5",
			"type": "number"
		},
		"style": {
			"description": "CSS to style the input element with",
			"type": "string"
		},
		"aria-describedby": {
			"description": "id of an element that is describing this widget (but is not its label). Used by accessibility software.",
			"type": "string"
		},
		"aria-labelledby": {
			"description": "id of attribute that is the label for this element. Normally you should use the {{calculator label}} template instead.",
			"type": "string"
		},
		"aria-label": {
			"description": "label for this calculator widget for accessibility software. Normally you should use {{calculator label}} instead.",
			"type": "string"
		},
		"enterkeyhint": {
			"description": "What should enter key be labelled as on the virtual keyboard on mobile phones",
			"type": "string",
			"suggestedvalues": [
				"enter",
				"go",
				"done",
				"next"
			]
		},
		"inputmode": {
			"description": "What type of virtual keyboard to use on mobile phones. Recommended values include text (normal keyboard) decimal (positive number) numeric (number). Other supported values include none (Do not show a keyboard), tel, search, email and url",
			"type": "string",
			"suggestedvalues": [
				"text",
				"numeric",
				"decimal"
			]
		},
		"mapping": {
			"description": "A JSON object mapping strings to numbers to alter the display. Only works with type of plain, select or text. The values must be of type number, except for the strings \"Infinity\" \"-Infinity\", \"default\", and \"NaN\". For select type, can be two layers deep.",
			"example": "{ \"one\": 1, \"two\": 2, \"Other\": \"default\" }",
			"type": "string"
		},
		"role": {
			"description": "Aria role. This helps a screen reader understand how to understand the content. For example, role=alert means that it is an urgent alert that should be read out right away. role=marquee means something that changes often and should not be read out by the screen reader. role=log means something where there is new content that gets added to the end which should be told to the user. role=status means it is a status update that should be read out when it changes. Will only be applied if gadget is enabled. If using a role that has an implicit aria-live value (alert, marquee, log, status) you should set aria-live=inherit to prevent the default aria-live from overriding.",
			"type": "string"
		},
		"aria-atomic": {
			"description": "If content changes, screen readers should read out the entire thing, not just the part that changed",
			"suggestedvalues": [
				"true",
				"false"
			]
		},
		"aria-relevant": {
			"description": "What type of content changes should be read out by screen readers"
		},
		"aria-live": {
			"description": "Value for aria-live. This controls if the screen reader should read out changes even when the user is focused elsewhere. Note the default for most calculator widgets is \"polite\". Set to \"inherit\" to set no aria-live attribute.",
			"suggestedvalues": [
				"polite",
				"inherit",
				"off",
				"assertive"
			]
		},
		"value": {
			"description": "For field types of radio, checkbox and select. Allow setting the default value for a form, including in cases where the field isn't checked by default. Unlike default this won't be shown as a fallback for users without javascript. Note: for radiobuttons and checkboxes the value of the form control will be the result of the formula if set by a formula, but this value if checked by a human.",
			"type": "string"
		},
		"checked": {
			"description": "Should the radio button or checkbox start off in checked state. Overrides default. Unlike default this won't affect fallback text for non-js users.",
			"type": "string"
		}
	},
	"description": "Add a calculator widget to the page. Like a spreadsheet you can refer to other widgets in the same page."
}
</templatedata>

=See also=
* {{t|Calculator button}}
* {{t|Calculator codex toggle}}
* {{t|Calculator-hideifzero}}
* {{t|Calculator label}}
* [[User:Bryandamon/Calculator_demos|Curated gallery of examples of calculator templates]]
* [[Wikipedia:Wikipedia Signpost/2025-01-15/Technology report|''The Signpost'' report featuring this template]]
<includeonly>{{Sandbox other||
<!-- Categories below this line -->
[[Category:Calculator_templates]]
}}</includeonly>