Firefox Tomorrow

javascript instance method

Intl.NumberFormat.prototype.formatRange()

View on MDN ↗

The formatRange() method of NumberFormat instances formats a range of numbers according to the locale and formatting options of this Intl.NumberFormat object.

Syntax

formatRange(startRange, endRange)

Parameters

  • startRange
    • : A Number, BigInt, or string, to format. Strings are parsed in the same way as in number conversion, except that formatRange() will use the exact value that the string represents, avoiding loss of precision during implicitly conversion to a number.
  • endRange

Return value

A string representing the given range of numbers formatted according to the locale and formatting options of this NumberFormat object. If the start and end values are formatted to the same string, the output will only contain a single value, possibly prefixed with an “approximately equals” symbol (e.g., ”~$3”). The insertion of this symbol only depends on the locale settings, and is inserted even when startRange === endRange.

Exceptions

  • RangeError
    • : Thrown if either startRange or endRange is NaN or an inconvertible string.
  • TypeError
    • : Thrown if either startRange or endRange is undefined.

Description

The formatRange getter function formats a range of numbers into a string according to the locale and formatting options of this NumberFormat object from which it is called.

Examples

Using formatRange

Use the formatRange getter function for formatting a range of currency values:

const nf = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  maximumFractionDigits: 0,
});

console.log(nf.formatRange(3, 5)); // "$3 – $5"

// Note: the "approximately equals" symbol is added if
// startRange and endRange round to the same values.
console.log(nf.formatRange(2.9, 3.1)); // "~$3"

const nf = new Intl.NumberFormat("es-ES", {
  style: "currency",
  currency: "EUR",
  maximumFractionDigits: 0,
});

console.log(nf.formatRange(3, 5)); // "3-5 €"
console.log(nf.formatRange(2.9, 3.1)); // "~3 €"

Specifications

SpecificationsStandards references are available on the canonical MDN page.

Browser compatibility

Browser compatibilityCompatibility data is available on the canonical MDN page.

See also