View source for Help:Convert

{{Wikipedia how-to|H:CON}}
Template {{tl|convert}} is used to convert a value from one unit of measurement to another. This page provides an overview of the options available when using the template.

*[[Help:Convert units]] • Simplified list of some commonly used units
*[[Help:Convert messages]] • Error and warning messages

== Asking questions ==
*[[Template talk:Convert]] • Questions on using the convert template, or discussion of any problems encountered, or proposals to add units or change convert
*[[Wikipedia:Help desk]] • General questions
*[[Module talk:Convert]] • Discussion concerning the convert modules (however, discussions relating to units should occur at [[Template talk:Convert]])

== Units ==
*[[Help:Convert units]] • Overview and simplified list of some commonly used units
*[[Module:Convert/documentation/conversion data]] • Full list of units

== Quick start ==
By default, the name of the input unit is shown, while the output is abbreviated using the unit's symbol. If wanted, names or symbols can be used, and the output precision can be specified.
*<code><nowiki>{{convert|123.4|ft|m}}</nowiki></code> → {{convert|123.4|ft|m}}
*<code><nowiki>{{convert|123.4|ft|m|abbr=on}}</nowiki></code> → {{convert|123.4|ft|m|abbr=on}}
*<code><nowiki>{{convert|123.4|ft|m|abbr=off}}</nowiki></code> → {{convert|123.4|ft|m|abbr=off}}
*<code><nowiki>{{convert|123.4|ft|m|abbr=off|sp=us}}</nowiki></code> → {{convert|123.4|ft|m|abbr=off|sp=us}}
*<code><nowiki>{{convert|123.4|ft|m|0}}</nowiki></code> → {{convert|123.4|ft|m|0}}
*<code><nowiki>{{convert|123.4|ft|m|3}}</nowiki></code> → {{convert|123.4|ft|m|3}}

Feet and inches can be converted, optionally with fractions.
*<code><nowiki>{{convert|12.34|m|ft}}</nowiki></code> → {{convert|12.34|m|ft}}
*<code><nowiki>{{convert|12.34|m|ftin}}</nowiki></code> → {{convert|12.34|m|ftin}}
*<code><nowiki>{{convert|12.34|m|ftin|frac=4}}</nowiki></code> → {{convert|12.34|m|ftin|frac=4}}
*<code><nowiki>{{convert|40|ft|6|in|m}}</nowiki></code> → {{convert|40|ft|6|in|m}}
*<code><nowiki>{{convert|5+3/4|in|mm}}</nowiki></code> → {{convert|5+3/4|in|mm}}
*<code><nowiki>{{convert|5+3/4|in|mm|0}}</nowiki></code> → {{convert|5+3/4|in|mm|0}}

To avoid [[WP:OVERLINK|overlinking]], units are not normally linked, but they can be when needed.
*<code><nowiki>{{convert|12300|m2|rood|abbr=off|lk=out}}</nowiki></code> → {{convert|12300|m2|rood|abbr=off|lk=out}}
*<code><nowiki>{{convert|12.2|rood|m2|abbr=off|lk=in}}</nowiki></code> →   {{convert|12.2|rood|m2|abbr=off|lk=in}}
*<code><nowiki>{{convert|12300|m2|rood|abbr=off|lk=on}}</nowiki></code> → {{convert|12300|m2|rood|abbr=off|lk=on}}

A convert can be used in an adjectival phrase, and user-specified text can be inserted.
*<code><nowiki>{{convert|1500|ft|m|adj=on}}</nowiki></code> → {{convert|1500|ft|m|adj=on}}
*<code><nowiki>{{convert|1500|ft|m|adj=mid|-long}}</nowiki></code> → {{convert|1500|ft|m|adj=mid|-long}}

If no output unit is specified, a default is used.
*<code><nowiki>{{convert|123.4|ft}}</nowiki></code> → {{convert|123.4|ft}}
*<code><nowiki>{{convert|123.4|ft|abbr=on}}</nowiki></code> → {{convert|123.4|ft|abbr=on}}
*<code><nowiki>{{convert|1500|ft||adj=mid|-long}}</nowiki></code> → {{convert|1500|ft||adj=mid|-long}}

The last example used <code>||</code> to explicitly show that the output unit has been omitted. If that is not done, the result is an error, and holding the mouse over the error message shows that "<code>-long</code>" is misinterpreted as the output unit.
*<code><nowiki>{{convert|1500|ft|adj=mid|-long}}</nowiki></code> → {{convert|1500|ft|adj=mid|-long|test=nopreview}}

The input and output can be swapped ("flipped").
*<code><nowiki>{{convert|12300|m2|rood|abbr=off|order=flip}}</nowiki></code> → {{convert|12300|m2|rood|abbr=off|order=flip}}<br>
:In a flipped conversion, an option such as {{para|lk|out}} means "link the right-hand side".
:*<code><nowiki>{{convert|12300|m2|rood|abbr=off|lk=out|order=flip}}</nowiki></code> → {{convert|12300|m2|rood|abbr=off|lk=out|order=flip}}
:*<code><nowiki>{{convert|12300|m2|rood|abbr=off|lk=in|order=flip}}</nowiki></code> → {{convert|12300|m2|rood|abbr=off|lk=in|order=flip}}
:*<code><nowiki>{{convert|12300|m2|rood|abbr=off|lk=on|order=flip}}</nowiki></code> → {{convert|12300|m2|rood|abbr=off|lk=on|order=flip}}

The input value can be written out in words.
*<code><nowiki>{{convert|5|mi|km|spell=in|0}}</nowiki></code> → {{convert|5|mi|km|spell=in|0}}
*<code><nowiki>{{convert|5|mi|km|spell=In|0}}</nowiki></code> → {{convert|5|mi|km|spell=In|0}}

Ranges of values are supported.
*<code><nowiki>{{convert|3|-|6|ft}}</nowiki></code> → {{convert|3|-|6|ft}}
*<code><nowiki>{{convert|3|to|6|ft|abbr=off|sp=us}}</nowiki></code> → {{convert|3|to|6|ft|abbr=off|sp=us}}

A range can use more than two values.
* <code><nowiki>{{convert|100|x|120|x|210|mm|in}}</nowiki></code> → {{convert|100|x|120|x|210|mm|in}}
* <code><nowiki>{{convert|100|x|120|x|210|mm|in|abbr=on}}</nowiki></code> → {{convert|100|x|120|x|210|mm|in|abbr=on}}
* <code><nowiki>{{convert|100|by|120|by|210|mm|in}}</nowiki></code> → {{convert|100|by|120|by|210|mm|in}}

Some input units consist of multiple components.
*<code><nowiki>{{convert|5|ft|8|in}}</nowiki></code> → {{convert|5|ft|8|in}}
*<code><nowiki>{{convert|11|st|3|lb|kg}}</nowiki></code> → {{convert|11|st|3|lb|kg}}

The output can show several different units.
*<code><nowiki>{{convert|123|nmi|km mi}}</nowiki></code> → {{convert|123|nmi|km mi}}
*<code><nowiki>{{convert|123|hPa|psi inHg|abbr=on|lk=on}}</nowiki></code> → {{convert|123|hPa|psi inHg|abbr=on|lk=on}}

Some outputs give a measurement in multiple units.
*<code><nowiki>{{convert|123.4|m|ydftin}}</nowiki></code> → {{convert|123.4|m|ydftin}}
*<code><nowiki>{{convert|123.4|kg|stlb}}</nowiki></code> → {{convert|123.4|kg|stlb}}
:Only [[Module:Convert/documentation/conversion data#Output multiples|output multiple codes]] such as <code>ydftin</code> can be used:
:*<code><nowiki>{{convert|123.4|m|yd ft in}}</nowiki></code> → {{convert|123.4|m|yd ft in}}
:*<code><nowiki>{{convert|123.4|m|yardfootinch}}</nowiki></code> → 123.4 m '''''<span style="color:red">Error in convert: Unit name "yardfootinch" is not known </span>'''''

== Rounding ==
By default, the output value is rounded to adjust its precision to match that of the input. An input such as 1234 is interpreted as 1234&nbsp;±&nbsp;0.5, while 1200 is interpreted as 1200&nbsp;±&nbsp;50, and the output value is displayed accordingly, taking into account the scale factor used in the conversion.

If the default is not wanted, the precision of output values can be specified using:
*<code>|''N''</code> (where <code>''N''</code> is a number) displays ''N'' digits after the [[decimal mark]] (round output to ''N'' decimal places).
*<code>|''-N''</code> (where <code>''-N''</code> is a negative number) replaces ''N'' digits before the decimal mark with zero (round output to nearest 10<sup>''N''</sup>).
*<code>|sigfig=''N''</code> (where <code>''N''</code> is a positive number) to specify the number of [[significant digits]] (round output to ''N'' significant figures).
*<code>|round=5</code> to round the output to the nearest multiple of 5. The <code>round</code> value can be 0.5, 5, 10, 25 or 50.

Examples:
*<code><nowiki>{{convert|1234|ft|m}}</nowiki></code> → {{convert|1234|ft|m}}
*<code><nowiki>{{convert|1234|ft|m|2}}</nowiki></code> → {{convert|1234|ft|m|2}}
*<code><nowiki>{{convert|1234|ft|m|-1}}</nowiki></code> → {{convert|1234|ft|m|-1}}
*<code><nowiki>{{convert|1234|ft|m|round=5}}</nowiki></code> → {{convert|1234|ft|m|round=5}}
*<code><nowiki>{{convert|1234|ft|m|round=10}}</nowiki></code> → {{convert|1234|ft|m|round=10}}
*<code><nowiki>{{convert|1234|ft|m|round=25}}</nowiki></code> → {{convert|1234|ft|m|round=25}}
*<code><nowiki>{{convert|1234|ft|m|round=50}}</nowiki></code> → {{convert|1234|ft|m|round=50}}
*<code><nowiki>{{convert|1234|ft|m|sigfig=2}}</nowiki></code> → {{convert|1234|ft|m|sigfig=2}}
*<code><nowiki>{{convert|1234|ft|m|sigfig=4}}</nowiki></code> → {{convert|1234|ft|m|sigfig=4}}
*<code><nowiki>{{convert|1230|ft|m}}</nowiki></code> → {{convert|1230|ft|m}}
*<code><nowiki>{{convert|1230|ft|m|0}}</nowiki></code> → {{convert|1230|ft|m|0}}
*<code><nowiki>{{convert|1230|ft|m|1}}</nowiki></code> → {{convert|1230|ft|m|1}}
*<code><nowiki>{{convert|5670|sqft}}</nowiki></code> → {{convert|5670|sqft}}
*<code><nowiki>{{convert|5670|sqft|-2}}</nowiki></code> → {{convert|5670|sqft|-2}}
*<code><nowiki>{{convert|7|x|8|x|12|ft|abbr=on|round=0.5}}</nowiki></code> → {{convert|7|x|8|x|12|ft|abbr=on|round=0.5}}

An input value such as 5000 is assumed to have one significant figure, while 5001 has four. If wanted, "5000." can be used to specify an input number that has four significant figures.
*<code><nowiki>{{convert|5000|m}}</nowiki></code> → {{convert|5000|m}}
*<code><nowiki>{{convert|5000.|m}}</nowiki></code> → {{convert|5000.|m}}

== Spell ==
Use {{para|sp|us}} to specify that unit names should be displayed with US spelling:
*<code><nowiki>{{convert|6|km}}</nowiki></code> → {{convert|6|km}}
*<code><nowiki>{{convert|6|km|sp=us}}</nowiki></code> → {{convert|6|km|sp=us}}

Use {{para|spell|in}} to specify that the input value should be spelled in words, or {{para|spell|In}} (uppercase "<code>I</code>") to start with an uppercase letter:
*<code><nowiki>{{convert|5|mi|km|spell=in}}</nowiki></code> → {{convert|5|mi|km|spell=in}}
*<code><nowiki>{{convert|5|mi|km|spell=in|abbr=off|0}}</nowiki></code> → {{convert|5|mi|km|spell=in|abbr=off|0}}
*<code><nowiki>{{convert|5|mi|km|spell=In|0}}</nowiki></code> → {{convert|5|mi|km|spell=In|0}}
*<code><nowiki>{{convert|5|mi|km|spell=In|abbr=off|0}}</nowiki></code> → {{convert|5|mi|km|spell=In|abbr=off|0}}
*<code><nowiki>{{convert|2+1/4|mi|km|abbr=off|0|spell=In}}</nowiki></code> → {{convert|2+1/4|mi|km|abbr=off|0|spell=In}}
*<code><nowiki>{{convert|2+1/4|mi|km|abbr=off|0|spell=In|sp=us}}</nowiki></code> → {{convert|2+1/4|mi|km|abbr=off|0|spell=In|sp=us}}

The input and output can be "flipped", as shown in these examples. The resulting first number is spelled:
*<code><nowiki>{{convert|5|mi|0|order=flip|spell=in}}</nowiki></code> → {{convert|5|mi|0|order=flip|spell=in}}
*<code><nowiki>{{convert|5|mi|0|order=flip|spell=In|abbr=off}}</nowiki></code> → {{convert|5|mi|0|order=flip|spell=In|abbr=off}}

Both input and output values can be spelled:
*<code><nowiki>{{convert|5|mi|m|-2|spell=on|sp=us|abbr=off}}</nowiki></code> → {{convert|5|mi|m|-2|spell=on|sp=us|abbr=off}}
*<code><nowiki>{{convert|5|mi|m|-2|spell=On|sp=us|abbr=off}}</nowiki></code> → {{convert|5|mi|m|-2|spell=On|sp=us|abbr=off}}

== Thousands separator ==
Commas in input numbers are ignored but spaces are not accepted: <code>1,000</code> is one thousand but <code>1&nbsp;000</code> is an error.

In output, by default, the thousands separator is the comma:
*<code><nowiki>{{convert|1234567|m|ft}}</nowiki></code> → {{convert|1234567|m|ft}}
*<code><nowiki>{{convert|1,234,567|m|ft}}</nowiki></code> → {{convert|1,234,567|m|ft}}
Set {{para|comma|off}} to remove separators from the result:
*<code><nowiki>{{convert|1,234,567|m|ft|comma=off}}</nowiki></code> → {{convert|1,234,567|m|ft|comma=off}}

Setting {{para|comma|5}} adds a separator only when the number of digits is 5 or more:
*<code><nowiki>{{convert|1234|m|ft}}</nowiki></code> → {{convert|1234|m|ft}}
*<code><nowiki>{{convert|1234|m|ft|comma=5}}</nowiki></code> → {{convert|1234|m|ft|comma=5}}
*<code><nowiki>{{convert|12345|m|ft|comma=5}}</nowiki></code> → {{convert|12345|m|ft|comma=5}}

Set {{para|comma|gaps}} to use a small space for thousands grouping. If the resulting number is copied, only the digits are copied (the gaps are omitted).
*<code><nowiki>{{convert|1234567|m|ft}}</nowiki></code> → {{convert|1234567|m|ft}}
*<code><nowiki>{{convert|1234567|m|ft|comma=gaps}}</nowiki></code> → {{convert|1234567|m|ft|comma=gaps}}

Gaps are inserted on both sides of the decimal mark. However, by default, no gap is inserted before a single digit. If a gap is always wanted, {{para|comma|gaps3}} can be used.
*<code><nowiki>{{convert|1234.98765|m|ft|comma=gaps}}</nowiki></code> → {{convert|1234.98765|m|ft|comma=gaps}}
*<code><nowiki>{{convert|1234.98765|m|ft|comma=gaps3}}</nowiki></code> → {{convert|1234.98765|m|ft|comma=gaps3}}
*<code><nowiki>{{convert|1234.9876|m|ft|comma=gaps}}</nowiki></code> → {{convert|1234.9876|m|ft|comma=gaps}}
*<code><nowiki>{{convert|1234.9876|m|ft|comma=gaps3}}</nowiki></code> → {{convert|1234.9876|m|ft|comma=gaps3}}
*<code><nowiki>{{convert|1.2349876|m|ft|comma=gaps}}</nowiki></code> → {{convert|1.2349876|m|ft|comma=gaps}}
*<code><nowiki>{{convert|1.2349876|m|ft|comma=gaps3}}</nowiki></code> → {{convert|1.2349876|m|ft|comma=gaps3}}

== Fractions ==
An input value can be specified as a fraction.
*<code><nowiki>{{convert|1/2|in|mm|1}}</nowiki></code> → {{convert|1/2|in|mm|1}}
*<code><nowiki>{{convert|1/2|in|mm|1|adj=on}}</nowiki></code> → {{convert|1/2|in|mm|1|adj=on}}
*<code><nowiki>{{convert|2+1/2|in|mm|1}}</nowiki></code> → {{convert|2+1/2|in|mm|1}}
*<code><nowiki>{{convert|1|ft|10+5/8|in}}</nowiki></code> → {{convert|1|ft|10+5/8|in}}
*<code><nowiki>{{convert|-2-1/4|in|mm|1}}</nowiki></code> → {{convert|-2-1/4|in|mm|1}}
*<code><nowiki>{{convert|1/2|in|mm|1|spell=in}}</nowiki></code> → {{convert|1/2|in|mm|1|spell=in}}

If two slashes are used, a horizontal fraction bar is used.
*<code><nowiki>{{convert|1//2|in|mm|1}}</nowiki></code> → {{convert|1//2|in|mm|1}}
*<code><nowiki>{{convert|2+1//2|in|mm|1}}</nowiki></code> → {{convert|2+1//2|in|mm|1}}

An output can be expressed with a fraction using <code>|frac=''N''</code> where ''N'' is the denominator. For example, <code>|frac=8</code> rounds the output to the nearest eighth.
*<code><nowiki>{{convert|219|mm|in|abbr=on}}</nowiki></code> → {{convert|219|mm|in|abbr=on}}
*<code><nowiki>{{convert|219|mm|in|abbr=on|frac=2}}</nowiki></code> → {{convert|219|mm|in|abbr=on|frac=2}}
*<code><nowiki>{{convert|219|mm|in|abbr=on|frac=4}}</nowiki></code> → {{convert|219|mm|in|abbr=on|frac=4}}
*<code><nowiki>{{convert|219|mm|in|abbr=on|frac=8}}</nowiki></code> → {{convert|219|mm|in|abbr=on|frac=8}}
*<code><nowiki>{{convert|222|mm|in|abbr=on|frac=8}}</nowiki></code> → {{convert|222|mm|in|abbr=on|frac=8}}

A fraction is applied to the output unit (if there is only one), or to non-SI units (if using a combination), except that if a precision is also specified, the fraction only applies to the [[Hand (unit)|hand]] unit.
*<code><nowiki>{{convert|18.45|in|m|frac=2}}</nowiki></code> → {{convert|18.45|in|m|frac=2}}
*<code><nowiki>{{convert|18.45|in|ft in hand cm|frac=2}}</nowiki></code> → {{convert|18.45|in|ft in hand cm|frac=2}}
*<code><nowiki>{{convert|18.45|in|ft in hand cm|frac=2|1}}</nowiki></code> → {{convert|18.45|in|ft in hand cm|frac=2|1}}

If <code>|frac=''-N''</code> is used (negative ''N''), a horizontal fraction bar is used for the output.
*<code><nowiki>{{convert|12.7|mm|frac=-2}}</nowiki></code> → {{convert|12.7|mm|frac=-2}}
*<code><nowiki>{{convert|222|mm|in|abbr=on|frac=-8}}</nowiki></code> → {{convert|222|mm|in|abbr=on|frac=-8}}

== Joins ==
The {{para|disp}} ("display") option may be used to "join" the input and output, as shown in the following examples.

{| class="wikitable"
! Convert !! Output !! Description
|-
| <code><nowiki>{{convert|2.4|m|ft}}</nowiki></code> || {{convert|2.4|m|ft}} || default
|-
| <code><nowiki>{{convert|2.4|m|ft|disp=sqbr}}</nowiki></code> || {{convert|2.4|m|ft|disp=sqbr}} || square brackets
|-
| <code><nowiki>{{convert|2.4|m|ft|disp=or}}</nowiki></code> || {{convert|2.4|m|ft|disp=or}} || or
|-
| <code><nowiki>{{convert|2.4|m|ft|disp=comma}}</nowiki></code> || {{convert|2.4|m|ft|disp=comma}} || comma
|-
| <code><nowiki>{{convert|2.4|m|ft|disp=br}}</nowiki></code> || {{convert|2.4|m|ft|disp=br}} || "&lt;br&nbsp;/>", line break
|-
| <code><nowiki>{{convert|2.4|m|ft|disp=br()}}</nowiki></code> || {{convert|2.4|m|ft|disp=br()}} || line break and brackets
|}

== Ranges ==
A range of values can be specified, as shown in the following examples.
{| class="wikitable"
|-
! Separator
! Convert
! Result
! Notes
|-
| <code>-</code>
| <code><nowiki>{{convert|3|-|6|ft}}</nowiki></code>
| {{convert|3|-|6|ft}}
| rowspan=2 | Input can be hyphen (-) or [[Dash#En dash|en&nbsp;dash]] (–), output uses en&nbsp;dash
|-
| <code>and</code>
| <code><nowiki>{{convert|3|and|6|ft}}</nowiki></code>
| {{convert|3|and|6|ft}}
|-
| <code>and(-)</code>
| <code><nowiki>{{convert|3|and(-)|6|ft}}</nowiki></code>
| {{convert|3|and(-)|6|ft}}
| rowspan=2 | ''and'' on left; en dash on right
|-
| <code>and(-)&#x7c;order=flip</code>
| <code><nowiki>{{convert|3|and(-)|6|ft|order=flip}}</nowiki></code>
| {{convert|3|and(-)|6|ft|order=flip}}
|-
| <code>or</code>
| <code><nowiki>{{convert|3|or|6|ft}}</nowiki></code>
| {{convert|3|or|6|ft}}
|
|-
| <code>to</code>
| <code><nowiki>{{convert|3|to|6|ft}}</nowiki></code>
| {{convert|3|to|6|ft}}
|
|-
| <code>to(-)</code>
| <code><nowiki>{{convert|3|to(-)|6|ft}}</nowiki></code>
| {{convert|3|to(-)|6|ft}}
| rowspan=2 | ''to'' on left; en dash on right
|-
| <code>to(-)&#x7c;order=flip</code>
| <code><nowiki>{{convert|3|to(-)|6|ft|order=flip}}</nowiki></code>
| {{convert|3|to(-)|6|ft|order=flip}}
|-
| <code>to about</code>
| <code><nowiki>{{convert|3|to&nbsp;about|6|ft}}</nowiki></code>
| {{nowrap|{{convert|3|to about|6|ft}}}}
|
|-
| <code>+/-</code>
| <code><nowiki>{{convert|3|+/-|6|ft}}</nowiki></code>
| {{convert|3|+/-|6|ft}}
|
|-
| {{hidden sort key|1=+/-}}<code>±</code>&nbsp;<code>&amp;plusmn;</code>
| <code><nowiki>{{convert|3|±|6|ft}}</nowiki></code>
| {{convert|3|±|6|ft}}
|
|-
| <code>+</code>
| <code><nowiki>{{convert|3|+|6|ft}}</nowiki></code>
| {{convert|3|+|6|ft}}
|
|-
| <code>,</code>
| <code><nowiki>{{convert|3|,|6|ft}}</nowiki></code>
| {{convert|3|,|6|ft}}
|
|-
| <code>, and</code>
| <code><nowiki>{{convert|3|, and|6|ft}}</nowiki></code>
| {{nowrap|{{convert|3|, and|6|ft}}}}
|
|-
| <code>, or</code>
| <code><nowiki>{{convert|3|, or|6|ft}}</nowiki></code>
| {{convert|3|, or|6|ft}}
|
|-
| <code>/</code>
| <code><nowiki>{{convert|83|/|63|F|disp=br()|abbr=values}}</nowiki></code>
| {{convert|83|/|63|F|disp=br()|abbr=values}}
| Slash with thin spaces for a table of high/low temperatures.
|-
| <code>by</code>
| <code><nowiki>{{convert|3|by|6|ft}}</nowiki></code>
| {{convert|3|by|6|ft}}
|
|-
| <code>by(x)</code>
| <code><nowiki>{{convert|3|by(x)|6|ft}}</nowiki></code>
| {{convert|3|by(x)|6|ft}}
| rowspan=2 | ''by'' on left; multiply (×) on right
|-
| <code>by(x)&#x7c;order=flip</code>
| <code><nowiki>{{convert|3|by(x)|6|ft|order=flip}}</nowiki></code>
| {{convert|3|by(x)|6|ft|order=flip}}
|-
| <code>x</code>
| <code><nowiki>{{convert|3|x|6|ft}}</nowiki></code>
| {{convert|3|x|6|ft}}
| rowspan=2 | Scientific notation.<br/>{{para|abbr|on}} alters the punctuation
|-
| <code>x&#x7c;abbr=on</code>
| <code><nowiki>{{convert|3|x|6|ft|abbr=on}}</nowiki></code>
| {{convert|3|x|6|ft|abbr=on}}
|- class="sortbottom"<!--deprecated-->
| <code>xx</code>
| colspan=3 | {{!xt|1=&#x7c;xx&#x7c;}} is '''deprecated'''. Use {{xt|1=&#x7c;x&#x7c;}} instead
|- class="sortbottom"<!--deprecated-->
| <code>*</code>
| colspan=3 | {{!xt|1=&#x7c;*&#x7c;}} is '''deprecated'''. Use {{xt|1=&#x7c;x&#x7c;}} instead
|}

Ranges can use more than two values.

{| class="wikitable"
! Convert !! Output
|-
| <code><nowiki>{{convert|3|x|4|x|24|in}}</nowiki></code> || {{convert|3|x|4|x|24|in}}
|-
| <code><nowiki>{{convert|3|x|4|to|6+1/2|x|8+3/4|in}}</nowiki></code> || {{convert|3|x|4|to|6+1/2|x|8+3/4|in}}
|}

Ranges can be specified in the first parameter although writing <code><nowiki>{{convert|3.2|-|7.5|ha}}</nowiki></code> would be clearer.

{| class="wikitable"
! Convert !! Output
|-
| <code><nowiki>{{convert|3.2-7.5|ha}}</nowiki></code> || {{convert|3.2-7.5|ha}}
|-
| <code><nowiki>{{convert|3x4x24|in}}</nowiki></code> || {{convert|3x4x24|in}}
|}

== Extra words ==
Some options provide text that is included in the output, as shown in the following examples.

{| class="wikitable"
! Convert !! Output !! Description
|-
| <code><nowiki>{{convert|4|ft||adj=mid|-long}}</nowiki></code> || {{convert|4|ft||adj=mid|-long}}
| Adjectival with mid-text between input and output {{nowrap|(sets {{para|adj|on}})}}
|-
| <code><nowiki>{{convert|40|acre||adj=pre|planted}}</nowiki></code> || {{convert|40|acre||adj=pre|planted}}
| Text before the input unit
|-
| <code><nowiki>{{convert|4|m||disp=preunit|+ }}</nowiki></code> || {{convert|4|m||disp=preunit|+ }}
| Same text before the input and output units
|-
| <code><nowiki>{{convert|4|m||disp=preunit|+ |or more }}</nowiki></code> || {{convert|4|m||disp=preunit|+ |or more }}
| Different text before the input and output units
|-
| <code><nowiki>{{convert|20|impfloz||disp=x|, approximately }}</nowiki></code> || {{convert|20|impfloz||disp=x|, approximately }}
| Text before the output (replaces the join)
|-
| <code><nowiki>{{convert|100|m||disp=x|/day (|/day)}}</nowiki></code> || {{convert|100|m||disp=x|/day (|/day)}}
| Text before and after the output (replaces the join)
|}

In each of the above examples, "<code>||</code>" provides an empty output unit which causes the default output to be used. An output unit, possibly empty, must be specified to avoid the template interpreting the extra text as the output unit. For example, using <code><nowiki>{{convert|4|ft|adj=mid|-long}}</nowiki></code> has the same effect as using <code><nowiki>{{convert|4|ft|-long|adj=mid}}</nowiki></code>, namely that an error would occur because "<code>-long</code>" would be used as the output unit. The following illustrates the error (hover the mouse over the error text to see that the problem is due to "<code>-long</code>" ) and how it may be avoided.
*<code><nowiki>{{convert|4|ft|adj=mid|-long}}</nowiki></code> → {{convert|4|ft|adj=mid|-long|test=nopreview}}
*<code><nowiki>{{convert|4|ft||adj=mid|-long}}</nowiki></code> → {{convert|4|ft||adj=mid|-long}}
*<code><nowiki>{{convert|4|ft| |adj=mid|-long}}</nowiki></code> → {{convert|4|ft| |adj=mid|-long}}
*<code><nowiki>{{convert|4|ft|m|adj=mid|-long}}</nowiki></code> → {{convert|4|ft|m|adj=mid|-long}}

== Displaying parts of a conversion ==
The following examples show how to display only a part of the result.

{| class="wikitable"
! Convert !! Output !! Description
|-
| <code><nowiki>{{convert|2|cuyd|m3}}</nowiki></code> || {{convert|2|cuyd|m3}} || normal convert
|-
| <code><nowiki>{{convert|2|cuyd|m3|abbr=values}}</nowiki></code> || {{convert|2|cuyd|m3|abbr=values}} || input and output values
|-
| <code><nowiki>{{convert|2|cuyd|m3|disp=unit}}</nowiki></code> || {{convert|2|cuyd|m3|disp=unit}} || input unit
|-
| <code><nowiki>{{convert|2|cuyd|m3|disp=unit|adj=on}}</nowiki></code> || {{convert|2|cuyd|m3|disp=unit|adj=on}} || input unit, adjectival (hyphenated)
|-
| <code><nowiki>{{convert|2|cuyd|cuyd|disp=out}}</nowiki></code> || {{convert|2|cuyd|cuyd|disp=out}} || input (workaround: repeat unit)
|-
| <code><nowiki>{{convert|2|cuyd|m3|disp=unit2}}</nowiki></code> || {{convert|2|cuyd|m3|disp=unit2}} || output unit (symbol)
|-
| <code><nowiki>{{convert|2|cuyd|m3|disp=unit2|abbr=off}}</nowiki></code> || {{convert|2|cuyd|m3|disp=unit2|abbr=off}} || output unit (name)
|-
| <code><nowiki>{{convert|2|cuyd|m3|disp=number}}</nowiki></code> || {{convert|2|cuyd|m3|disp=number}} || output value
|-
| <code><nowiki>{{convert|2|cuyd|m3|disp=out}}</nowiki></code> || {{convert|2|cuyd|m3|disp=out}} || output value and unit
|-
| <code><nowiki>{{convert|2|cuyd|m3|abbr=off|disp=out}}</nowiki></code> || {{convert|2|cuyd|m3|abbr=off|disp=out}} || output value and unit
|}

== Flipping the order of output ==
To invert the order of measurements, use {{para|order|flip}}
* <code><nowiki>{{convert|10|km|mi}}</nowiki></code> &rarr; {{convert|10|km|mi}}
* <code><nowiki>{{convert|10|km|mi|order=flip}}</nowiki></code> &rarr; {{convert|10|km|mi|order=flip}}

== Wrapping and line breaking ==
Convert uses the regular '''space''' ("&nbsp;") and '''non-breaking space''' (<code>&amp;nbsp;</code> which displays as "&nbsp;") to control line-breaking (also called wrapping/nowrapping).

:''In all examples below, an ''<code>&amp;nbsp;</code>'' is shown as "{{red|_}}" (red underscore): ''"<code>3{{red|_}}ft</code>"''.''

Wrapping is possible where a regular space ("&nbsp;") is used. Prevent wrapping is enforced in the template using the ''non-breaking space'', that ties and keeps text elements together.
::<code>3&nbsp;feet</code> ''may'' break after "3"
::<code>3&amp;nbsp;ft</code>, or {{replace|3&nbsp;ft|&nbsp;|{{red|_}}}}, ''will not'' break after "3"
::A line break ({{purple|&lt;br/&gt;}}) ''forces'' a newline (line break), and so overrules any nowrap setting at that point.

Word meaning:
:''In measurements, [[SI]] uses wording that says that ''value&nbsp;=&nbsp;number&nbsp;&times;&nbsp;unit'', for example ''length&nbsp;=&nbsp;number&nbsp;&times;&nbsp;meter''.''
:''In {{tlf|Convert}} documentation, sometimes 'value' is used to mean the number; and ''abbr'' is used to mean ''unit symbol(s)''.''

;Within a single measured value (number and unit)
The separator between the number and the unit can be a space or a nonbreaking space (<code>&amp;nbsp;</code>):
*When a unit is abbreviated (symbol is shown), the separator is <code>&amp;nbsp;</code>.
::<code><nowiki>{{convert|12|m|ft|abbr=on}}</nowiki></code> → {{replace|{{convert|12|m|ft|abbr=on}}|&nbsp;|{{red|_}}}}

*When a unit is not abbreviated (name is shown), the separator is a space.
::<code><nowiki>{{convert|12|m|ft}}</nowiki></code> → {{replace|{{convert|12|m|ft}}|&nbsp;|{{red|_}}}}

*Some units do not have a symbol and always use a space ([[Module:Convert/documentation/conversion data#Use name|such as acre]]).
::<code><nowiki>{{convert|3|acre|m2|abbr=on}}</nowiki></code> → {{replace|{{convert|3|acre|m2|abbr=on}}|&nbsp;|{{red|_}}}}

*Except, <code>&amp;nbsp;</code> is always used when a measurement is in multiple units.
::<code><nowiki>{{convert|1|ft|6|in|cm}}</nowiki></code> → {{replace|{{convert|1|ft|6|in|cm}}|&nbsp;|{{red|_}}}}
::<code><nowiki>{{convert|2|m|ftin}}</nowiki></code> → {{replace|{{convert|2|m|ftin}}|&nbsp;|{{red|_}}}}

*Except, if option <code>|adj=on</code> is used and the unit is not abbreviated, the separator is a hyphen ("-").
::<code><nowiki>{{convert|2|m|ftin|adj=on}}</nowiki></code> → {{replace|{{convert|2|m|ftin|adj=on}}|&nbsp;|{{red|_}}}}

* When the name of a number is used, <code>&amp;nbsp;</code> is used as the separator between the number and the name. For example, a measurement spelled as "12&nbsp;million metres" has <code>&amp;nbsp;</code> before "million" and a space afterwards.
::<code><nowiki>{{convert|12|e6m}}</nowiki></code> → {{replace|{{convert|12|e6m}}|&nbsp;|{{red|_}}}}

;Between measurements
* A space is used as the separator in a join between the first and second measurement.
::<code><nowiki>{{convert|3|ft|m}}</nowiki></code> → {{replace|{{convert|3|ft|m}}|&nbsp;|{{red|_}}}}

* Except for the special case ''before "["''&thinsp;:
::<code><nowiki>{{convert|12|in|cm|disp=sqbr|abbr=on}}</nowiki></code> → {{replace|{{convert|12|in|cm|disp=sqbr|abbr=on}}|&nbsp;|{{red|_}}}} (<code>&amp;nbsp;</code> before "[")

* Multiple output measurements (by listing units) always use a space between measurements (";&nbsp;" has a space after ";").
::<code><nowiki>{{convert|2|acre|m2 sqft ha}}</nowiki></code> → {{replace|{{convert|2|acre|m2 sqft ha}}|&nbsp;|{{red|_}}}}

;Between components of a measurement (e.g., in a range; between foot–inch)
* A measurement in multiple units always uses a space between components ("1&nbsp;foot 6&nbsp;inches" has <code>&amp;nbsp;</code> before the unit names, but a space after "foot").
::<code><nowiki>{{convert|1|ft|6|in|cm}}</nowiki></code> → {{replace|{{convert|1|ft|6|in|cm}}|&nbsp;|{{red|_}}}}

* In a range, spaces are generally used to separate items. For example, "to" and "or" have a space before and after in the following.
::<code><nowiki>{{convert|12|to|20|in|cm}}</nowiki></code> → {{replace|{{convert|12|to|20|in|cm}}|&nbsp;|{{red|_}}}}
::<code><nowiki>{{convert|12|or|20|in|cm}}</nowiki></code> → {{replace|{{convert|12|or|20|in|cm}}|&nbsp;|{{red|_}}}}

* The ranges <code>+/-</code> and <code>,</code> always use <code>&amp;nbsp;</code>:
::<code><nowiki>{{convert|12|+/-|2|in|cm}}</nowiki></code> → {{replace|{{convert|12|+/-|2|in|cm}}|&nbsp;|{{red|_}}}}
::<code><nowiki>{{convert|12|,|20|in|cm}}</nowiki></code> → {{replace|{{convert|12|,|20|in|cm}}|&nbsp;|{{red|_}}}}

* The "to(-)" range is an exception. When a unit is not abbreviated, "to" has <code>&amp;nbsp;</code> before and a space after.
::<code><nowiki>{{convert|12|to(-)|20|in|cm}}</nowiki></code> → {{replace|{{convert|12|to(-)|20|in|cm}}|&nbsp;|{{red|_}}}}

* The "x" range is an exception. When a unit is abbreviated, "×" has a space before and <code>&amp;nbsp;</code> after.
::<code><nowiki>{{convert|12|x|20|in|cm}}</nowiki></code> → {{replace|{{convert|12|x|20|in|cm}}|&nbsp;|{{red|_}}}}

;Overrule by setting a line break
* Parameter {{para|disp|br}} adds a forced line break (<code>&lt;br/&gt;</code>) between measurements; brackets are omitted. Use {{para|disp|br()}} to add the line break and keep the brackets.
::<code><nowiki>{{convert|12|m|ft|disp=br}}</nowiki></code> → {{nowrap|1=12 metres{{purple|&lt;br/&gt;}}39 feet}} ''shows'':
:::{{replace|{{convert|12|m|ft|disp=br}}|&nbsp;|{{red|_}}}}
::<code><nowiki>{{convert|12|m|ft|disp=br()}}</nowiki></code> → {{nowrap|1=12 metres{{purple|&lt;br/&gt;}}(39 feet)}} ''shows'':
:::{{replace|{{convert|12|m|ft|disp=br()}}|&nbsp;|{{red|_}}}}

;Preview wikicode
To see the wikicode result of the convert template: put your <code><nowiki>{{convert|...}}</nowiki></code> code into [[Special:ExpandTemplates]] and then preview by clicking {{key press|OK}}.

== Tables ==
The following parameters are intended for use in [[Help:Tables|tables]].
{| class="wikitable"
! Parameter !! Description
|-
| <code>&#124;disp=table</code> || for a table cell with <code>align="right"</code>
|-
| <code>&#124;disp=tablecen</code> || for a table cell with <code>align="center"</code>
|-
| <code>&#124;sortable=on</code> || output a numeric hidden sort field for a sortable table
|}

The following shows the wikitext output by some example converts.
{| class="wikitable"
! Convert !! Resulting wikitext
|-
| <code><nowiki>{{convert|47.5|kg|lb}}</nowiki></code> || 47.5 kilograms (105&nbsp;lb)
|-
| <code><nowiki>{{convert|47.5|kg|lb|disp=table}}</nowiki></code> || align="right"&#124;47.5<br />&#124;align="right"&#124;105
|-
| <code><nowiki>{{convert|47.5|kg|lb|disp=tablecen}}</nowiki></code> || align="center"&#124;47.5<br />&#124;align="center"&#124;105
|-
| <code><nowiki>{{convert|47.5|kg|lb|sortable=on}}</nowiki></code> || &lt;span style="display:none">7001475000000000000&lt;/span>47.5 kilograms (105&nbsp;lb)
|}

=== Fixed table ===
This wikitext:
<pre>
{|class="wikitable"
! align=right, rowspan="2" |
!colspan="2"| Length
!colspan="2"| Weight
|- style="vertical-align:bottom;"
!metres !!ft in !!kg !!lb
|-
! Lorem ipsum
| {{convert|28.1|m|ftin|disp=table}}
| {{convert|47.5|kg|lb|disp=table}}
|-
! Dolor sit amet
| {{convert|9.9|m|ftin|disp=table}}
| {{convert|74.1|kg|lb|disp=table}}
|-
! Consectetur
| {{convert|38.2|m|ftin|disp=table}}
| {{convert|31.5|kg|lb|disp=table}}
|-
! Adipisicing elit
| {{convert|18.7|m|ftin|disp=table}}
| {{convert|52.7|kg|lb|disp=table}}
|}
</pre>

produces this table:
{|class="wikitable"
! align=right, rowspan="2" |
!colspan="2"| Length
!colspan="2"| Weight
|- style="vertical-align:bottom;"
!metres !!ft in !!kg !!lb
|-
! Lorem ipsum
| {{convert|28.1|m|ftin|disp=table}}
| {{convert|47.5|kg|lb|disp=table}}
|-
! Dolor sit amet
| {{convert|9.9|m|ftin|disp=table}}
| {{convert|74.1|kg|lb|disp=table}}
|-
! Consectetur
| {{convert|38.2|m|ftin|disp=table}}
| {{convert|31.5|kg|lb|disp=table}}
|-
! Adipisicing elit
| {{convert|18.7|m|ftin|disp=table}}
| {{convert|52.7|kg|lb|disp=table}}
|}

=== Sortable table ===
This wikitext:
<pre>
{|class="wikitable sortable"
! align=right, rowspan="2" |
!colspan="2"| Length
!colspan="2"| Weight
|- style="vertical-align:bottom;"
!metres !!ft in !!kg !!lb
|-
! Lorem ipsum
| {{convert|28.1|m|ftin|disp=table|sortable=on}}
| {{convert|47.5|kg|lb|disp=table|sortable=on}}
|-
! Dolor sit amet
| {{convert|9.9|m|ftin|disp=table|sortable=on}}
| {{convert|74.1|kg|lb|disp=table|sortable=on}}
|-
! Consectetur
| {{convert|38.2|m|ftin|disp=table|sortable=on}}
| {{convert|31.5|kg|lb|disp=table|sortable=on}}
|-
! Adipisicing elit
| {{convert|18.7|m|ftin|disp=table|sortable=on}}
| {{convert|52.7|kg|lb|disp=table|sortable=on}}
|}
</pre>

produces this table:
{|class="wikitable sortable"
! align=right, rowspan="2" |
!colspan="2"| Length
!colspan="2"| Weight
|- style="vertical-align:bottom;"
!metres !!ft in !!kg !!lb
|-
! Lorem ipsum
| {{convert|28.1|m|ftin|disp=table|sortable=on}}
| {{convert|47.5|kg|lb|disp=table|sortable=on}}
|-
! Dolor sit amet
| {{convert|9.9|m|ftin|disp=table|sortable=on}}
| {{convert|74.1|kg|lb|disp=table|sortable=on}}
|-
! Consectetur
| {{convert|38.2|m|ftin|disp=table|sortable=on}}
| {{convert|31.5|kg|lb|disp=table|sortable=on}}
|-
! Adipisicing elit
| {{convert|18.7|m|ftin|disp=table|sortable=on}}
| {{convert|52.7|kg|lb|disp=table|sortable=on}}
|}

== Units in singular or plural ==
Unit ''symbols'' are always singular. Unit ''names'' can be singular or plural. A unit is singular when the number is exactly +1:
* <code><nowiki>{{convert|0.5|ft|m|abbr=off}}</nowiki></code> &rarr; {{convert|0.5|ft|m|abbr=off}}
* <code><nowiki>{{convert|1|ft|m|abbr=off}}</nowiki></code>  &rarr; {{convert|1|ft|m|abbr=off}}
* <code><nowiki>{{convert|2|ft|m|abbr=off}}</nowiki></code> &rarr; {{convert|2|ft|m|abbr=off}}

== Parameter list ==
{{convert/doc/parameter list}}

== Complicated grammar ==
This example is from article [[Fort McHenry#19th Century|Fort McHenry]]:
::The American defenders had 18-, 24- and 32-pounder (8,&nbsp;11&nbsp;and 15&nbsp;kg) cannons.
This result cannot reasonably be produced by {{tlf|convert}}. However, convert can be used to construct the required text.

*Use {{tlf|convert}} with [[WP:Substitution|subst]] to insert the required wikitext into the article or [[Special:MyPage/sandbox|your sandbox]].
*:<code><nowiki>had {{subst:convert|18|,|24|,|32|lb|kg|0}} cannons</nowiki></code>
*:→ had {{convert|18|,|24|,|32|lb|kg|0}} cannons
*When the edit is saved, the convert template is replaced with the result.
*Edit the result to produce the final text.
*:→ had 18-, 24- and 32-pounder (8,&nbsp;11&nbsp;and 15&nbsp;kg) cannons

An alternative to subst would be to enter <code><nowiki>{{convert|18|,|24|,|32|lb|kg|0}}</nowiki></code> into [[Special:ExpandTemplates]], then copy and edit its result into the article.

== Deprecated ==
{{Convert/doc/deprecations list}}

== Limitations ==
This is a list of features that the module may be expected to support, but which will not work.

Composite units cannot be used in a range:
*<code><nowiki>{{convert|2|ft|6|in|to|3|ft|9|in}}</nowiki></code> → {{convert|2|ft|6|in|to|3|ft|9|in|test=nopreview}}

If an expression is wanted, it has to use <code><nowiki>{{#expr:...}}</nowiki></code>:
*<code><nowiki>{{convert|3*12|ft|mm}}</nowiki></code> → {{convert|3*12|ft|mm}}
*<code><nowiki>{{convert|{{#expr:3*12}}|ft|mm}}</nowiki></code> → {{convert|{{#expr:3*12}}|ft|mm}}

{{Convert/documentation navbox}}
{{Wikipedia help pages}}