Formats a number (or string that appears to be a number) as one would see it written in imperial measurements, e.g. "1 1/2" instead of "1.5".
Features:
- To use vulgar fraction characters like "⅞", pass
true
as the second argument. Other options like Roman numerals are described below. - The return value will be
null
if the first argument is neither a number nor a string that evaluates to a number usingparseFloat
. - The return value will be an empty string (
""
) if the first argument is0
or"0"
, which fits the primary use case of formatting recipe ingredient quantities.
For the inverse operation—converting a string to a
number
—check out numeric-quantity. It handles mixed numbers, vulgar fractions, comma/underscore separators, and Roman numerals.If you're interested in parsing recipe ingredient strings, try parse-ingredient.
Usage
Installed
import { formatQuantity } from 'format-quantity';
formatQuantity(1.5); // "1 1/2"
formatQuantity(2.66); // "2 2/3"
formatQuantity(3.875, true); // "3⅞"
CDN
As an ES module:
<script type="module">
import { formatQuantity } from 'https://cdn.jsdelivr.net/npm/format-quantity/ esm';
console.log(formatQuantity(10.5)); // "10 1/2"
</script>
As UMD (all exports are properties of the global object FormatQuantity
):
<script src="https://unpkg.com/format-quantity"></script>
<script>
console.log(FormatQuantity.formatQuantity(10.5)); // "10 1/2"
</script>
Options
The second parameter to formatQuantity
can be a boolean
value or an options object.
vulgarFractions
Type | Default |
---|---|
boolean |
false |
Returns vulgar fractions when appropriate. This option has the same effect as passing a plain boolean
value as the second parameter.
formatQuantity(3.875, { vulgarFractions: true }); // "3⅞"
// is the same as
formatQuantity(3.875, true); // "3⅞"
Note: formatQuantity
supports sixteenths, but no vulgar fraction characters exist for that denomination. Therefore the vulgarFractions
option has no effect if the fraction portion of the final string is an odd numerator over a denominator of 16
.
fractionSlash
Type | Default |
---|---|
boolean |
false |
Uses the fraction slash character ("\u2044"
) to separate the numerator and denominator instead of the regular "solidus" slash ("\u002f"
). This option is ignored if the vulgarFractions
option is also true
.
formatQuantity(3.875, { fractionSlash: true }); // "3 7⁄8"
formatQuantity(3.875, { fractionSlash: true, vulgarFractions: true }); // "3⅞"
tolerance
Type | Default |
---|---|
number |
0.0075 |
This option determines how close the decimal portion of a number has to be to the actual quotient of a fraction to be considered a match. For example, consider the fraction 1⁄3: 0.333
(exactly 333 thousandths) is not equivalent to 1⁄3, but it's very close. So even though formatQuantity(0.333)
and formatQuantity(1/3)
will return "1/3"
.
A lower tolerance increases the likelihood that formatQuantity
will return a decimal representation instead of a fraction or mixed number since the matching algorithm will be stricter. An higher tolerance increases the likelihood that formatQuantity
will return a fraction or mixed number, but at the risk of arbitrarily matching an incorrect fraction simply because it gets evaluated first (the export fractionDecimalMatches
defines the order of evaluation).
// Low tolerance - returns a decimal since 0.333 is not close enough to 1/3
formatQuantity(0.333, { tolerance: 0.00001 }); // "0.333"
// High tolerance - matches "1/3" even for 3/10
formatQuantity(0.3, { tolerance: 0.1 }); // "1/3"
// *Way* too high tolerance - incorrect result because thirds get evaluated before halves
formatQuantity(0.5, { tolerance: 0.5 }); // "1/3"
romanNumerals
Type | Default |
---|---|
boolean |
false |
Coerces the number into an integer using Math.floor
, then formats the value as Roman numerals. The algorithm uses strict, modern rules, so the number must be between 1 and 3999 (inclusive).
When this option is true
, all other options are ignored.
formatQuantity(1214, { romanNumerals: true }); // "MCCXIV"
formatQuantity(12.14, { romanNumerals: true, vulgarFractions: true }); // "XII"