Skip to content

Numbers

Format decimals, percentages, units, scientific and compact notation, and spelled-out or ordinal forms — all in the locale's conventions, straight from ICU. For currency amounts, see Money & currency.

The instance locale determines grouping and decimal separators, digits (such as Western 0-9 or Arabic-Indic ٠-٩), and sign and percent placement. The methods below let you control rounding, precision, notation, and units.

Method overview

Method Use it for Returns
number(value, options?) A plain decimal in the locale's style "123.400,5"
precision(value, fractionDigits?, options?) A decimal with a fixed number of fraction digits (default 2) "1.00"
percentage(value, precision?, options?) A fraction rendered as a percent "20%"
unit(category, unit, value, width?) A measurement with its localised unit "2.19 gigabytes"
compact(value, width?) A short magnitude for large numbers "1.2K" / "1.2 thousand"
scientific(value) Exponential notation "1.2345E4"
symbol(name) A single locale notation symbol "٫" (Persian decimal mark)

All of number(), precision(), percentage(), and money() accept the same options bag; the rest take simple positional arguments described inline.

Decimals, percentages & units

new Cosmo("de").number(123400.5);               // "123.400,5"
new Cosmo("en").precision(1, 2);                // "1.00"
new Cosmo("en").percentage(0.2);                // "20%"
new Cosmo("en").unit("digital", "gigabyte", 2.19); // "2.19 gigabytes"
new Cosmo("tr").unit("temperature", "celsius", 26, "short"); // "26°C"

number() formats a plain decimal in the locale's style — note how de swaps the roles of . and ,. Pass the options bag to control rounding, fraction digits, and grouping.

precision() is the shortcut for a fixed number of fraction digits: it always renders exactly fractionDigits places (default 2), padding with trailing zeros and rounding as needed. precision(1) → "1.00" and precision(1.002) → "1.00" — never "1.0". It is shorthand for number(value, { minimumFractionDigits: n, maximumFractionDigits: n }), and like the others it stays fully localised (de → "1,00"). Pass the options bag as a trailing argument to allow more fraction digits (e.g. { maximumFractionDigits: 3 }) or change the rounding mode.

percentage() takes a fraction, not a pre-multiplied percent: 0.2 → 20%. The optional second argument is the maximum fraction digits (default 3), so percentage(0.1234, 1) → "12.3%". Anything you can pass number() you can also pass as a third options argument; an explicit maximumFractionDigits there overrides the precision shortcut.

unit() pairs a measurement type and unit with a value and an optional width. The type/unit names are the CLDR identifiers (digital/gigabyte, temperature/celsius, length/meter, …). The width selects verbosity:

width Example (celsius, 26) Notes
none / long / full 26 degrees Celsius Spelled-out unit name (the default is full/long)
medium 26°C "short" ICU display
short 26°C "narrow" ICU display — tightest

Finding valid unit identifiers

unit() accepts the ECMA-402 sanctioned units only. List the ones your runtime

supports with supportedValues("unit") and pass them as the unit argument. The category argument ("digital", "temperature", …) is descriptive grouping — ICU does not require it to match, but keeping it accurate documents intent.

Number-formatting options

number(), precision(), percentage(), and money() accept per-call formatting options. Use camelCase keys, such as maximumFractionDigits.

The default rounding mode is halfExpand (round half away from zero).

Key Type / values What it does
minimumIntegerDigits int Zero-pads the whole part (5 → "005" at 3).
minimumFractionDigits int Pads the fraction with trailing zeros up to N places.
maximumFractionDigits int Rounds the fraction to at most N places.
minimumSignificantDigits int Keep at least N significant digits.
maximumSignificantDigits int Round to at most N significant digits.
roundingMode ceil · floor · expand · trunc · halfExpand · halfTrunc · halfEven How the last kept digit is rounded.
roundingIncrement 1,2,5,10,20,25,50,100,…,5000 Round to a multiple (e.g. 25 → nearest 0.25 with 2 fraction digits — "nickel rounding").
useGrouping always · auto · min2 · true/false Thousands separators.

Significant vs fraction digits

ICU treats significant-digit limits and fraction-digit limits as mutually exclusive. Set one or the other, not both — significant digits win where both are supplied.

Additional number-formatting options:

Key Values What it does
signDisplay auto · always · exceptZero · negative · never When to show the sign.
trailingZeroDisplay auto · stripIfInteger Drop .00 on whole values.
roundingPriority auto · morePrecision · lessPrecision Resolve fraction vs significant conflicts.
notation standard · scientific · engineering · compact Inline notation switch.
compactDisplay short · long Only with notation: "compact".

Options in practice

const c = new Cosmo("en");
c.number(1234.5, { minimumFractionDigits: 2 });          // "1,234.50"
c.number(1234.567, { maximumFractionDigits: 2 });        // "1,234.57"
c.number(2.005, { maximumFractionDigits: 2,
                  roundingMode: "halfEven" });           // "2"  (banker's)
c.number(1234.5, { useGrouping: false });                // "1234.5"
c.percentage(0.1234, 1);                                 // "12.3%"

Compact & scientific notation

new Cosmo("en").scientific(12345);    // "1.2345E4"
new Cosmo("en").compact(1200);        // "1.2K"
new Cosmo("en").compact(1200, "long");// "1.2 thousand"

compact() shortens large magnitudes for dashboards, social counters, and tight columns. The width chooses between the symbol form (short, the default — 1.2K) and the spelled scale word (long/full — 1.2 thousand), both fully localised (German 1,2 Tsd., Japanese 1.2万). scientific() renders exponential notation at full double precision.

Practical examples

A file-size display. Pick the unit by magnitude, then format with the digital category at a tight width:

function fileSize(c, bytes) {
  if (bytes < 1024) return c.unit("digital", "byte", bytes, "short");
  const mb = bytes / 1_048_576;
  return c.unit("digital", "megabyte", Number(mb.toFixed(1)), "short");
}
fileSize(new Cosmo("en"), 5_242_880);   // "5 MB"

A percentage with a guaranteed decimal. Combine the precision shortcut with an options bag to also pin a minimum:

new Cosmo("en").percentage(0.5, 2, { minimumFractionDigits: 2 }); // "50.00%"

"Nickel rounding" with roundingIncrement. Round a price to the nearest 0.05:

new Cosmo("en").number(2.13, { maximumFractionDigits: 2,
                               roundingIncrement: 5,
                               minimumFractionDigits: 2 });  // "2.15"