Template ((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. See the documentation at Template:Convert for further details.

Asking questions[edit]

Units[edit]

Quick start[edit]

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.

Feet and inches can be converted, optionally with fractions.

To avoid overlinking, units are not normally linked, but they can be when needed.

A convert can be used in an adjectival phrase, and user-specified text can be inserted (e.g. -tall, -long, -high, -wide).

If no output unit is specified, a default is used.

The last example used || 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 "-long" is misinterpreted as the output unit.

The input and output can be swapped ("flipped").

In a flipped conversion, an option such as |lk=out means "link the right-hand side".
  • ((convert|12300|m2|rood|abbr=off|lk=out|order=flip)) → 12.2 roods (12,300 square metres)
  • ((convert|12300|m2|rood|abbr=off|lk=in|order=flip)) → 12.2 roods (12,300 square metres)
  • ((convert|12300|m2|rood|abbr=off|lk=on|order=flip)) → 12.2 roods (12,300 square metres)

The input value can be written out in words.

Ranges of values are supported.

A range can use more than two values.

Some input units consist of multiple components.

The output can show several different units.

Some outputs give a measurement in multiple units.

Only output multiple codes such as ydftin can be used:
  • ((convert|123.4|m|yd ft in)) → 123.4 metres (135.0 yd; 405 ft; 4,860 in)
  • ((convert|123.4|m|yardfootinch)) → 123.4 m Error in convert: Unit name "yardfootinch" is not known

Rounding[edit]

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 ± 0.5, while 1200 is interpreted as 1200 ± 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:

Examples:

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.

Spell[edit]

Use |sp=us to specify that unit names should be displayed with US spelling:

Use |spell=in to specify that the input value should be spelled in words, or |spell=In (uppercase "I") to start with an uppercase letter:

The input and output can be "flipped", as shown in these examples. The resulting first number is spelled:

Both input and output values can be spelled:

Thousands separator[edit]

Commas in input numbers are ignored but spaces are not accepted: 1,000 is one thousand but 1 000 is an error.

In output, by default, the thousands separator is the comma:

Set |comma=off to remove separators from the result:

Setting |comma=5 adds a separator only when the number of digits is 5 or more:

Set |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).

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, |comma=gaps3 can be used.

Fractions[edit]

An input value can be specified as a fraction.

If two slashes are used, a horizontal fraction bar is used.

An output can be expressed with a fraction using |frac=N where N is the denominator. For example, |frac=8 rounds the output to the nearest eighth.

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.

If |frac=-N is used (negative N), a horizontal fraction bar is used for the output.

Joins[edit]

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

Convert Output Description
((convert|2.4|m|ft)) 2.4 metres (7.9 ft) default
((convert|2.4|m|ft|disp=sqbr)) 2.4 metres [7.9 ft] square brackets
((convert|2.4|m|ft|disp=or)) 2.4 metres or 7.9 feet or
((convert|2.4|m|ft|disp=comma)) 2.4 metres, 7.9 ft comma
((convert|2.4|m|ft|disp=semicolon)) 2.4 metres; 7.9 ft semicolon
((convert|2.4|m|ft|disp=br)) 2.4 metres
7.9 feet		 "<br />", line break
((convert|2.4|m|ft|disp=br())) 2.4 metres
(7.9 feet)		 line break and brackets

Ranges[edit]

A range of values can be specified, as shown in the following examples.

Separator Convert Result Notes
- ((convert|3|-|6|ft)) 3–6 feet (0.91–1.83 m) Input can be hyphen (-) or en dash (–), output uses en dash
and ((convert|3|and|6|ft)) 3 and 6 feet (0.91 and 1.83 m)
and(-) ((convert|3|and(-)|6|ft)) 3 and 6 feet (0.91–1.83 m) and on left; en dash on right
and(-)|order=flip ((convert|3|and(-)|6|ft|order=flip)) 0.91 and 1.83 metres (3–6 ft)
or ((convert|3|or|6|ft)) 3 or 6 feet (0.91 or 1.83 m)
to ((convert|3|to|6|ft)) 3 to 6 feet (0.91 to 1.83 m)
to(-) ((convert|3|to(-)|6|ft)) 3 to 6 feet (0.91–1.83 m) to on left; en dash on right
to(-)|order=flip ((convert|3|to(-)|6|ft|order=flip)) 0.91 to 1.83 metres (3–6 ft)
to about ((convert|3|to about|6|ft)) 3 to about 6 feet (0.91 to about 1.83 m)
+/- ((convert|3|+/-|6|ft)) 3 ± 6 feet (0.91 ± 1.83 m)
± &plusmn; ((convert|3|±|6|ft)) 3 ± 6 feet (0.91 ± 1.83 m)
+ ((convert|3|+|6|ft)) 3 + 6 feet (0.91 + 1.83 m)
, ((convert|3|,|6|ft)) 3, 6 feet (0.91, 1.83 m)
, and ((convert|3|, and|6|ft)) 3, and 6 feet (0.91, and 1.83 m)
, or ((convert|3|, or|6|ft)) 3, or 6 feet (0.91, or 1.83 m)
/ ((convert|83|/|63|F|disp=br()|abbr=values)) 83 / 63
(28 / 17) 		Slash with thin spaces for a table of high/low temperatures.
by ((convert|3|by|6|ft)) 3 by 6 feet (0.91 by 1.83 m)
by(x) ((convert|3|by(x)|6|ft)) 3 by 6 feet (0.91 m × 1.83 m) by on left; multiply (×) on right
by(x)|order=flip ((convert|3|by(x)|6|ft|order=flip)) 0.91 by 1.83 metres (3 ft × 6 ft)
x ((convert|3|x|6|ft)) 3 by 6 feet (0.91 m × 1.83 m) Scientific notation.
|abbr=on alters the punctuation
x|abbr=on ((convert|3|x|6|ft|abbr=on)) 3 ft × 6 ft (0.91 m × 1.83 m)
xx |xx| is deprecated. Use |x| instead
* |*| is deprecated. Use |x| instead

Ranges can use more than two values.

Convert Output
((convert|3|x|4|x|24|in)) 3 by 4 by 24 inches (76 mm × 102 mm × 610 mm)
((convert|3|x|4|to|6+1/2|x|8+3/4|in)) 3 by 4 to 6+1⁄2 by 8+3⁄4 inches (76 mm × 102 mm to 165 mm × 222 mm)

Ranges can be specified in the first parameter although writing ((convert|3.2|-|7.5|ha)) would be clearer.

Convert Output
((convert|3.2-7.5|ha)) 3.2–7.5 hectares (7.9–18.5 acres)
((convert|3x4x24|in)) 3 by 4 by 24 inches (76 mm × 102 mm × 610 mm)

Extra words[edit]

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

Convert Output Description
((convert|4|ft||adj=mid|-long)) 4-foot-long (1.2 m) Adjectival with mid-text between input and output (sets |adj=on)
((convert|40|acre||adj=pre|planted)) 40 planted acres (16 ha) Text before the input unit
((convert|4|m||disp=preunit|+ )) 4+ metres (13+ ft) Same text before the input and output units
((convert|4|m||disp=preunit|+ |or more )) 4+ metres (13 or more ft) Different text before the input and output units
((convert|20|impfloz||disp=x|, approximately )) 20 imperial fluid ounces, approximately 570 ml; 19 US fl oz Text before the output (replaces the join)
((convert|100|m||disp=x|/day (|/day))) 100 metres/day (330 ft/day) Text before and after the output (replaces the join)

In each of the above examples, "||" 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 ((convert|4|ft|adj=mid|-long)) has the same effect as using ((convert|4|ft|-long|adj=mid)), namely that an error would occur because "-long" 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 "-long" ) and how it may be avoided.

Displaying parts of a conversion[edit]

The following examples show how to display only a part of the result.

Note: in Convert, abbr is synonym for unit symbol
Convert Returns Components
((convert|2|cuyd|m3)) 2 cubic yards (1.5 m3) all (default conversion)
((convert|2|cuyd|m3|abbr=values)) 2 (1.5) numbers only
((convert|2|cuyd|m3|disp=unit)) cubic yards input unit
((convert|2|cuyd|m3|disp=unit|adj=on)) cubic-yard input unit, adjectival (hyphenated)
((convert|2|cuyd|m3|disp=unit|adj=on)) cu yd input unit, adjectival (but abbr so not hyphenated)
((convert|2|cuyd|cuyd|disp=unit)) 2.0 cu yd input unit abbr (workaround)
((convert|2|cuyd|m3|disp=out)) 1.5 m3 output value, symbols
((convert|2|cuyd|m3|disp=out|abbr=off)) 1.5 cubic metres output value, names
((convert|2|cuyd|m3|disp=out|adj=on)) 1.5-cubic-metre output, adjective
((convert|2|cuyd|m3|disp=number)) 1.5 output number
((convert|2|cuyd|m3|disp=unit2)) m3 output unit (abbr by default)
((convert|2|cuyd|m3|disp=unit2|abbr=off)) cubic metres output unit (name)
((convert|2|cuyd|m3|disp=unit2|abbr=on)) m3 output unit (abbr)

Flipping the order of output[edit]

To invert the order of measurements, use |order=flip

Wrapping and line breaking[edit]

Convert uses the regular space (" ") and non-breaking space (&nbsp; which displays as " ") to control line-breaking (also called wrapping/nowrapping).

In all examples below, an &nbsp; is shown as "_" (red underscore): "3_ft".

Wrapping is possible where a regular space (" ") is used. Prevent wrapping is enforced in the template using the non-breaking space, that ties and keeps text elements together.

3 feet may break after "3"
3&nbsp;ft, or 3_ft, will not break after "3"
A line break (<br/>) 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 = number × unit, for example length = number × meter.
In ((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 (&nbsp;):

((convert|12|m|ft|abbr=on)) → 12_m (39_ft)
((convert|12|m|ft)) → 12 metres (39_ft)
((convert|3|acre|m2|abbr=on)) → 3 acres (12,000_m2)
((convert|1|ft|6|in|cm)) → 1_foot 6_inches (46_cm)
((convert|2|m|ftin)) → 2 metres (6_ft 7_in)
((convert|2|m|ftin|adj=on)) → 2-metre (6_ft 7_in)
((convert|12|e6m)) → 12_million metres (39,000,000_ft)
Between measurements
((convert|3|ft|m)) → 3 feet (0.91_m)
((convert|12|in|cm|disp=sqbr|abbr=on)) → 12_in_[30_cm] (&nbsp; before "[")
((convert|2|acre|m2 sqft ha)) → 2 acres (8,100_m2; 87,000_sq_ft; 0.81_ha)
Between components of a measurement (e.g., in a range; between foot–inch)
((convert|1|ft|6|in|cm)) → 1_foot 6_inches (46_cm)
((convert|12|to|20|in|cm)) → 12 to 20 inches (30 to 51_cm)
((convert|12|or|20|in|cm)) → 12 or 20 inches (30 or 51_cm)
((convert|12|+/-|2|in|cm)) → 12_±_2 inches (30.5_±_5.1_cm)
((convert|12|,|20|in|cm)) → 12,_20 inches (30,_51_cm)
((convert|12|to(-)|20|in|cm)) → 12_to 20 inches (30–51_cm)
((convert|12|x|20|in|cm)) → 12 by 20 inches (30_cm ×_51_cm)
Overrule by setting a line break
((convert|12|m|ft|disp=br)) → 12 metres<br/>39 feet shows:
12 metres
39 feet
((convert|12|m|ft|disp=br())) → 12 metres<br/>(39 feet) shows:
12 metres
(39 feet)
Preview wikicode

To see the wikicode result of the convert template: put your ((convert|...)) code into Special:ExpandTemplates and then preview by clicking OK.

Tables[edit]

The following parameters are intended for use in tables.

Parameter Description
|disp=table for a table cell with align="right"
|disp=tablecen for a table cell with align="center"
|sortable=on output a numeric hidden sort field for a sortable table

The following shows the wikitext output by some example converts.

Convert Resulting wikitext
((convert|47.5|kg|lb)) 47.5 kilograms (105 lb)
((convert|47.5|kg|lb|disp=table)) align="right"|47.5
|align="right"|105
((convert|47.5|kg|lb|disp=tablecen)) align="center"|47.5
|align="center"|105
((convert|47.5|kg|lb|sortable=on)) <span style="display:none">7001475000000000000</span>47.5 kilograms (105 lb)

Fixed table

This wikitext: 

{|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))
|}

produces this table:

Length Weight
metres ft in kg lb
Lorem ipsum 28.1 92 ft 2 in 47.5 105
Dolor sit amet 9.9 32 ft 6 in 74.1 163
Consectetur 38.2 125 ft 4 in 31.5 69
Adipisicing elit 18.7 61 ft 4 in 52.7 116

Sortable table

This wikitext: 

{|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))
|}

produces this table:

Length Weight
metres ft in kg lb
Lorem ipsum 28.1 92 ft 2 in 47.5 105
Dolor sit amet 9.9 32 ft 6 in 74.1 163
Consectetur 38.2 125 ft 4 in 31.5 69
Adipisicing elit 18.7 61 ft 4 in 52.7 116

Units in singular or plural[edit]

Unit symbols are always singular. Unit names can be singular or plural. A unit is singular when the number is exactly +1:

Parameter list[edit]

Parameter options for ((convert))
Parameter Value Description Note
|abbr=in in Use symbol for first (left-hand side) unit Unit display
|abbr=off off Use name for all units Unit display
|abbr=none none
|abbr=on on Use symbol for all units Unit display
|abbr=out out Use symbol for right-hand side unit (default) Unit display
|abbr=unit unit Use symbol for all units when using scientific notation Unit display
|abbr=values values Omit both the input and output units: show only the numbers Unit display
|abbr=~ ~ Shows both unit name and symbol Unit display
|adj=mid|… mid User-specified text after the input unit; sets adj=on (adjective). Expects 1 unnamed parameter. Word adding, adjective
|adj=on on Unit name is adjective (singular and hyphenated) Grammar, adjective
|adj=pre|… pre User-specified text before input unit. Expects 1 unnamed parameter. Word adding
|adj=ri0 ri0 Round input with precision 0 Input precision
|adj=ri1 ri1 Round input with precision 1 Input precision
|adj=ri2 ri2 Round input with precision 2 Input precision
|adj=ri3 ri3 Round input with precision 3 Input precision
|comma=5 5 Only use comma for thousands separator if 5 or more digits Number format
|comma=gaps gaps Use gaps (space), not comma, for thousands separator Number format
|comma=off off No thousands separator Number format
|disp=b b Join input and output using " (...)" (default) Join values
|disp=sqbr sqbr Join input and output using " [...]" Join values
|disp=br br Join input and output using "<br/>" Join values
|disp=comma comma Join input and output using ", " Join values
|disp=or or Join input and output using " or " Join values
|disp=number number Display output number only Parts only
|disp=output number only output number only
|disp=out out Display only output number and name/symbol Parts only
|disp=output only output only
|disp=preunit|…[|…] preunit Text to be inserted after value and before units, for both input and output, with optionally different text for output. Expects 1 or 2 unnamed parameters. Word adding
|disp=table table Output is suitable for a table cell with align="right" Table columns
|disp=tablecen tablecen Output is suitable for a table cell with align="center" Table columns
|disp=unit unit Display input name/symbol only (not input number, not output) Parts only
|disp=unit2 unit2 Display output name/symbol only (not input; not output number) Parts only
|disp=x|… x Join input and output using user-specified text Word adding
|frac=N N Show imperial number in fractions, denominator=N Number format, fraction
|input=P2048 P2048 (e.g.) Reads and converts Wikidata property Inside template
|lk=in in Link left-hand side unit name or symbol Unit link
|lk=on on Link all unit names or symbols (but not twice for the same unit) Unit link
|lk=out out Link right-hand side unit name or symbol Unit link
|order=flip flip Inverts order of input, output measurements (conversion first) Order
|order=out out Displays output units in the order entered, skipping input unit Order
|qid=Q1056131 Q1056131 (e.g.) Reads Wikidata property from Wikidata item Inside template; testing
|qual=Q613628 Q613628 (e.g.) Qualify Wikidata property
|round=5 5 Rounds calculation to the nearest multiple of 5 Output precision
|round=25 25 Rounds calculation to the nearest multiple of 25 Output precision
|round=each each In a range, each number is rounded by the default rounding Output precision
|sigfig=N N Round output number to N significant figures (N is a positive integer) Output precision
|sortable=on on Adds invisible sort key Table sort
|sp=us us Use U.S. spelling ("meter" instead of default "metre") Spelling U.S. names
|spell=in in Spell input number in words Spelling numbers
|spell=In In Spell input number in words with first letter uppercase Spelling numbers
|spell=on on Spell input and output numbers in words Spelling numbers
|spell=On On Spell input and output numbers in words with first letter uppercase Spelling numbers
|$=€ € Replace $-sign with a currency sign, for example in €/hectare Cost per unit
No currency conversion happens
|debug=yes yes Debugging only. In a sortable table: show the normally hidden sort key Table sort
|disp=flip flip Deprecated. Use |order=flip Order
|sing= Deprecated. Use |adj= Plurals

Complicated grammar[edit]

This example is from article Fort McHenry:

The American defenders had 18-, 24- and 32-pounder (8, 11 and 15 kg) cannons.

This result cannot reasonably be produced by ((convert)). However, convert can be used to construct the required text.

An alternative to subst would be to enter ((convert|18|,|24|,|32|lb|kg|0)) into Special:ExpandTemplates, then copy and edit its result into the article.

Deprecated[edit]

This list: 

Deprecated options should not be used. They may produce incorrect or undesired results and there is no guarantee that they will be supported in the future.

Limitations[edit]

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:

If an expression is wanted, it has to use ((#expr:...)):

Category