Skip to content
Tutorials Center
My learning

Topics

Lesson 113 of 156 · Built-in Tools

Formatting with Intl

Use the built-in Intl API to format numbers, currencies, units, dates, relative times, plurals and lists for any locale, and to sort strings correctly.

1234.5 is "1,234.5" in the United States, "1.234,5" in Germany and "1 234,5" in France. A date written "03/04/2026" means March 4 to an American and April 3 to almost everyone else. If your app shows numbers, money or dates to people around the world, hand-built strings will get something wrong.

JavaScript ships with a complete answer: the Intl object (short for internationalization). It contains formatters that know the rules of hundreds of languages and regions — separators, currency symbols, month names, plural forms, list words and alphabetical order. They are built into every modern browser and Node.js, with nothing to install. This lesson walks through the formatters you will use most.

Locales and the formatter pattern

Every Intl tool follows the same pattern:

  1. Create a formatter with a locale and an options object.
  2. Call its format() method (or select(), compare()…) as many times as you like.

A locale is a language tag such as "en-US" (English, United States), "de-DE" (German, Germany), "pt-BR" (Portuguese, Brazil) or just "ja" (Japanese). If you pass undefined, the formatter uses the visitor's own browser language — usually what you want in a real app. In this lesson we pass explicit locales so everyone sees the same output.

JavaScript
const fmt = new Intl.NumberFormat("de-DE");
fmt.format(1234567.891); // "1.234.567,891"

navigator.language;      // the browser's preferred locale, e.g. "en-GB"

Create once, reuse often. Building a formatter does real work (it loads locale data). If you format hundreds of values, make the formatter once outside the loop and call format() inside it.

Numbers, currencies and percentages

Intl.NumberFormat handles plain numbers and much more through the style option.

JS Numbers around the world

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice a few things in the output:

  • India groups digits as "12,34,567" — rules you would never guess.
  • Japanese yen has no minor unit, so the formatter rounds to whole yen automatically.
  • The currency follows the currency option, not the locale. The locale only decides how the amount is written. A German user can look at a price in US dollars: new Intl.NumberFormat("de-DE", { style: "currency", currency: "USD" }) gives "1.499,50 $".

Never do money math with formatted strings. Keep the raw number (ideally whole cents, to avoid floating-point surprises) and format only at the end.

Units and compact numbers

Two more styles save a lot of hand-written code:

JS Units and compact notation

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Compact notation gives "1.5K" and "2.4M" — perfect for follower counts and view counters.

Dates and times

Intl.DateTimeFormat turns a Date into a readable string. The quickest way is the dateStyle and timeStyle options ("full", "long", "medium" or "short"):

JS Formatting dates

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The timeZone option is something Date alone can't do: it shows any instant in any named IANA time zone, regardless of where the user's computer is.

You can either use dateStyle/timeStyle or individual parts (year, month, day, weekday, hour, minute…), but not both in the same formatter — mixing them throws a TypeError.

Two more methods are worth knowing:

  • formatRange(start, end) writes a range compactly, such as "Jul 4 – 9, 2026".
  • formatToParts(date) returns an array of pieces ({ type: "month", value: "July" }, …) so you can style each part separately.

Relative times

"3 days ago" and "in 2 hours" read better than full timestamps for recent events. Intl.RelativeTimeFormat writes them in any language; you supply the number and the unit.

JS Relative times

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With numeric: "auto" you get natural words like "yesterday" and "tomorrow"; the default ("always") gives "1 day ago".

Plurals with PluralRules

"1 file" but "2 files" — and in other languages the rules are far more complex. Polish, for example, has different word forms for 2–4 and for 5 or more. Intl.PluralRules tells you which category a number belongs to; you supply the words for each category.

JavaScript
const rules = new Intl.PluralRules("en-US");
rules.select(1);  // "one"
rules.select(5);  // "other"

const words = { one: "file", other: "files" };
const label = (n) => `${n} ${words[rules.select(n)]}`;
label(1); // "1 file"
label(3); // "3 files"

The option type: "ordinal" handles ordinals:

JavaScript
const ord = new Intl.PluralRules("en-US", { type: "ordinal" });
const suffix = { one: "st", two: "nd", few: "rd", other: "th" };
const nth = (n) => n + suffix[ord.select(n)];
[1, 2, 3, 4, 11, 21, 102].map(nth); // ["1st", "2nd", "3rd", "4th", "11th", "21st", "102nd"]

The categories a language uses are always some of "zero", "one", "two", "few", "many" and "other".

Lists, sorting and more

Intl.ListFormat joins items with the right commas and words:

JavaScript
const items = ["apples", "pears", "plums"];
new Intl.ListFormat("en", { type: "conjunction" }).format(items); // "apples, pears, and plums"
new Intl.ListFormat("en", { type: "disjunction" }).format(items); // "apples, pears, or plums"
new Intl.ListFormat("es").format(items);                          // "apples, pears y plums"

Intl.Collator compares strings the way a human expects, which makes it ideal for sorting. The default sort() compares UTF-16 code units, so uppercase letters, accents and numbers inside text come out in odd places:

JS Sorting with Intl.Collator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

numeric: true makes "item2" come before "item10". string.localeCompare(other, locale, options) does the same job for a single comparison.

A few more members of the family you may meet:

  • Intl.DisplayNames — names of languages, regions and currencies: new Intl.DisplayNames("en", { type: "region" }).of("JP") gives "Japan".
  • Intl.Segmenter — splits text into user-visible characters, words or sentences, even for languages without spaces and for emoji made of several code points.
  • Intl.supportedValuesOf("currency") — lists the values a browser knows (currencies, time zones, units…).

Check your understanding

Quick check · 5 questions

of 5 answered You scored / 5 · perfect!

  1. 1. What decides the currency symbol in new Intl.NumberFormat("de-DE", { style: "currency", currency: "USD" })?

    The currency always comes from the currency option. The locale only controls separators, symbol position and spacing.
  2. 2. Which option makes RelativeTimeFormat say "yesterday" instead of "1 day ago"?

    numeric: "auto" allows natural phrases such as yesterday, today and tomorrow.
  3. 3. What does new Intl.PluralRules("en-US").select(1) return?

    select() returns a plural category name. You map the category to your own words.
  4. 4. You need to sort file names so that "track2" comes before "track10". What do you use?

    A collator with numeric: true compares digit runs as numbers. The default sort compares character codes, so "track10" comes first.
  5. 5. Why should you create a formatter once and reuse it?

    Construction is the expensive step. A single formatter can format any number of values.

Summary

  • Intl formatters follow one pattern: new Intl.X(locale, options), then format(); pass undefined to use the visitor's language.
  • NumberFormat handles grouping, currencies (from the currency option), percentages, units and compact numbers.
  • DateTimeFormat uses dateStyle/timeStyle or individual parts, and its timeZone option shows any instant in any zone.
  • RelativeTimeFormat writes "3 days ago"; PluralRules picks the right plural category; ListFormat joins lists.
  • Collator (and localeCompare) sorts strings the way people expect, including numbers inside text.

Next: Regular Expressions — describe text patterns and search for them.