Intl.NumberFormat.prototype.formatRangeToParts()
================================================

The **`formatRangeToParts()`** method of `Intl.NumberFormat` instances returns an `Array` of objects containing the locale-specific tokens from which it is possible to build custom strings while preserving the locale-specific parts. This makes it possible to provide locale-aware custom formatting ranges of number strings.

Syntax
------


```js
formatRangeToParts(startRange, endRange)
```

### Parameters

`startRange`

A `Number` or `BigInt`.

`endRange`

A `Number` or `BigInt`.

### Return value

An `Array` of objects containing the formatted range of numbers in parts.

The structure of the returned looks like this:


```js
[
  { type: "integer", value: "3", source: "startRange" },
  { type: "literal", value: "-", source: "shared" },
  { type: "integer", value: "5", source: "endRange" },
  { type: "literal", value: " ", source: "shared" },
  { type: "currency", value: "€", source: "shared" },
];
```


Possible values for the `type` property include:

`currency`

The currency string, such as the symbols "$" and "€" or the name "Dollar", "Euro", depending on how `currencyDisplay` is specified.

`decimal`

The decimal separator string (".").

`fraction`

The fraction number.

`group`

The group separator string (",").

`infinity`

The `Infinity` string ("∞").

`integer`

The integer number.

`literal`

Any literal strings or whitespace in the formatted number.

`minusSign`

The minus sign string ("-").

`nan`

The `NaN` string ("NaN").

`plusSign`

The plus sign string ("+").

`percentSign`

The percent sign string ("%").

`unit`

The unit string, such as the "l" or "litres", depending on how `unitDisplay` is specified.

Possible values for the `source` property include:

`startRange`

The object is the start part of the range.

`endRange`

The object is the end part of the range.

`shared`

The object is a "shared" part of the range, such as a separator or currency.

### Exceptions

`RangeError`

Thrown if `startRange` is less than `endRange`, or either value is `NaN`.

`TypeError`

Thrown if either `startRange` or `endRange` is undefined.

Examples
--------

### Comparing formatRange and formatRangeToParts

`NumberFormat` outputs localized, opaque strings that cannot be manipulated directly:


```js
const startRange = 3500;
const endRange = 9500;

const formatter = new Intl.NumberFormat("de-DE", {
  style: "currency",
  currency: "EUR",
});

console.log(formatter.formatRange(startRange, endRange));
// "3.500,00–9.500,00 €"
```


 However, for many user interfaces there is a need to customize the formatting of this string.
 The `formatRangeToParts` method enables locale-aware formatting of strings produced by `NumberFormat` formatters by providing you the string in parts:


```js
console.log(formatter.formatRangeToParts(startRange, endRange));

// return value:
[
  { type: "integer", value: "3", source: "startRange" },
  { type: "group", value: ".", source: "startRange" },
  { type: "integer", value: "500", source: "startRange" },
  { type: "decimal", value: ",", source: "startRange" },
  { type: "fraction", value: "00", source: "startRange" },
  { type: "literal", value: "–", source: "shared" },
  { type: "integer", value: "9", source: "endRange" },
  { type: "group", value: ".", source: "endRange" },
  { type: "integer", value: "500", source: "endRange" },
  { type: "decimal", value: ",", source: "endRange" },
  { type: "fraction", value: "00", source: "endRange" },
  { type: "literal", value: " ", source: "shared" },
  { type: "currency", value: "€", source: "shared" },
];
```

Specifications
--------------

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.numberformat.prototype.formatrangetoparts |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Intl.NumberFormat`
* `Intl.NumberFormat.prototype.format()`
* `Intl.DateTimeFormat.prototype.formatRangeToParts()`