Author:

Creation:2024-08-13Last update:2026-08-22

Reference this doc to your favorite AI assistantChatGPT Claude DeepSeek Google AI mode Gemini Perplexity Mistral Grok

Ask your question and get a summary of the document by referencing this page and the AI provider of your choice

Version History

"Update to Next.js >= 9.4.0 architecture"
v9.4.08/22/2026
"Add useIntl"
v8.0.01/20/2026
"Remove getIntlayerAsync from formatters"
v6.2.010/14/2025
"Add vue formatters"
v5.8.08/20/2025
"Add formatters documentation"
v5.8.08/18/2025
"Add list formatter documentation"
v5.8.08/20/2025
"Add additional Intl utilities (DisplayNames, Collator, PluralRules)"
v5.8.08/20/2025
"Add locale utilities (getLocaleName, getLocaleLang, getLocaleFromPath, etc.)"
v5.8.08/20/2025
"Add content handling utilities (getContent, getTranslation, getIntlayer, etc.)"
v5.8.08/20/2025

Edit this doc

If you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.

GitHub link to the documentation

Copy

Copy doc Markdown to clipboard

Intlayer Formatters

Name: Intlayer
Rating: 4.92 (64 reviews)
Author: Intlayer

Overview

Intlayer provides locale-aware formatting utilities built on top of the native Intl APIs. These formatters automatically use the current locale from your application context, eliminating the need to manually pass locale parameters.

For React, Vue, and other frameworks, use the framework-specific hooks/composables that automatically bind to your app's locale context:

Show all table content

Open the table in a modal to view all data content clearly

Framework	Import
React (client)	`react-intlayer/format`
React (server)	`react-intlayer/server/format`
Next.js (client)	`next-intlayer/client/format`
Next.js (server)	`next-intlayer/server/format`
Vue	`vue-intlayer/format`
Preact	`preact-intlayer/format`
Vanilla JS / Node.js	`intlayer` (requires manual locale passing)

React Formatters

Quick Start

tsx

Copy code

Copy the code to the clipboard

import {
  useNumber,
  useCurrency,
  useDate,
  usePercentage,
  useCompact,
  useList,
  useRelativeTime,
  useUnit,
  useIntl,
} from "react-intlayer/format";
// Next.js client: "next-intlayer/client/format"
// Next.js server: "next-intlayer/server/format"
// Preact: "preact-intlayer/format"

const PriceDisplay = () => {
  const currency = useCurrency();
  const percentage = usePercentage();

  return (
    <div>
      <p>Price: {currency(1234.5, { currency: "EUR" })}</p>
      <p>Discount: {percentage(0.25)}</p>
    </div>
  );
};

Available Hooks

All hooks automatically use the locale from IntlayerProvider (or IntlayerClientProvider / IntlayerServerProvider).

Show all table content

Open the table in a modal to view all data content clearly

Hook	Description	Example Output
`useNumber()`	Format numbers with grouping	`"123,456.789"`
`useCurrency()`	Format currency values	`"€1,234.50"`
`usePercentage()`	Format percentages	`"25%"`
`useDate()`	Format dates and times	`"Aug 2, 2025"`
`useRelativeTime()`	Format relative time	`"in 3 days"`
`useUnit()`	Format values with units	`"5 kilometers"`
`useCompact()`	Format numbers in compact notation	`"1.2K"`
`useList()`	Format arrays as lists	`"apple, banana, and orange"`
`useIntl()`	Get locale-bound `Intl` object	Full `Intl` API access

Complete Example

tsx

Copy code

Copy the code to the clipboard

import {
  useNumber,
  useCurrency,
  useDate,
  usePercentage,
  useCompact,
  useList,
  useRelativeTime,
  useUnit,
} from "react-intlayer/format";

const MyComponent = () => {
  const number = useNumber();
  const currency = useCurrency();
  const date = useDate();
  const percentage = usePercentage();
  const compact = useCompact();
  const list = useList();
  const relativeTime = useRelativeTime();
  const unit = useUnit();

  return (
    <div>
      <p>{number(123456.789)}</p>
      <p>{currency(1234.5, { currency: "EUR" })}</p>
      <p>{date(new Date(), "short")}</p>
      <p>{percentage(0.25)}</p>
      <p>{compact(1200)}</p>
      <p>{list(["apple", "banana", "orange"])}</p>
      <p>{relativeTime(new Date(), new Date(Date.now() + 86400000))}</p>
      <p>{unit(5, { unit: "kilometer" })}</p>
    </div>
  );
};

`useIntl` Hook

The useIntl hook provides direct access to a locale-bound Intl object. This is useful when you need the full Intl API (e.g., DisplayNames, Collator, PluralRules) with automatic locale injection.

tsx

Copy code

Copy the code to the clipboard

import { useIntl } from "react-intlayer/format";

const MyComponent = () => {
  const intl = useIntl(); // uses context locale

  // Standard Intl API, but locale is auto-injected when undefined
  const formatted = new intl.NumberFormat(undefined, {
    style: "currency",
    currency: "USD",
  }).format(123.45);

  // You can still override the locale if needed
  const date = new intl.DateTimeFormat("fr-FR").format(new Date());

  // Access other Intl features
  const displayNames = new intl.DisplayNames(undefined, { type: "language" });
  const languageName = displayNames.of("fr"); // "French" (or localized)

  return (
    <div>
      <p>{formatted}</p>
      <p>{date}</p>
      <p>{languageName}</p>
    </div>
  );
};

Vue Formatters

Quick Start

vue

Copy code

Copy the code to the clipboard

<script setup>
import {
  useNumber,
  useCurrency,
  useDate,
  usePercentage,
  useCompact,
  useList,
  useRelativeTime,
  useUnit,
  useIntl,
} from "vue-intlayer/format";

const currency = useCurrency();
const percentage = usePercentage();
</script>

<template>
  <div>
    <p>Price: {{ currency.value(1234.5, { currency: "EUR" }) }}</p>
    <p>Discount: {{ percentage.value(0.25) }}</p>
  </div>
</template>

Available Composables

All composables return computed refs that automatically use the locale from the injected IntlayerProvider.

Show all table content

Open the table in a modal to view all data content clearly

Composable	Description	Example Output
`useNumber()`	Format numbers with grouping	`"123,456.789"`
`useCurrency()`	Format currency values	`"€1,234.50"`
`usePercentage()`	Format percentages	`"25%"`
`useDate()`	Format dates and times	`"Aug 2, 2025"`
`useRelativeTime()`	Format relative time	`"in 3 days"`
`useUnit()`	Format values with units	`"5 kilometers"`
`useCompact()`	Format numbers in compact notation	`"1.2K"`
`useList()`	Format arrays as lists	`"apple, banana, and orange"`
`useIntl()`	Get locale-bound `Intl` object	Full `Intl` API access

Complete Example

vue

Copy code

Copy the code to the clipboard

<script setup>
import {
  useNumber,
  useCurrency,
  useDate,
  usePercentage,
  useCompact,
  useList,
  useRelativeTime,
  useUnit,
} from "vue-intlayer/format";

const number = useNumber();
const currency = useCurrency();
const date = useDate();
const percentage = usePercentage();
const compact = useCompact();
const list = useList();
const relativeTime = useRelativeTime();
const unit = useUnit();
</script>

<template>
  <div>
    <p>{{ number.value(123456.789) }}</p>
    <p>{{ currency.value(1234.5, { currency: "EUR" }) }}</p>
    <p>{{ date.value(new Date(), "short") }}</p>
    <p>{{ percentage.value(0.25) }}</p>
    <p>{{ compact.value(1200) }}</p>
    <p>{{ list.value(["apple", "banana", "orange"]) }}</p>
    <p>{{ relativeTime.value(new Date(), new Date(Date.now() + 86400000)) }}</p>
    <p>{{ unit.value(5, { unit: "kilometer" }) }}</p>
  </div>
</template>

`useIntl` Composable

The useIntl composable provides direct access to a locale-bound Intl object. This is useful when you need the full Intl API with automatic locale injection.

vue

Copy code

Copy the code to the clipboard

<script setup>
import { useIntl } from "vue-intlayer/format";

const intl = useIntl(); // uses context locale

// Standard Intl API, but locale is auto-injected when undefined
const formatted = new intl.value.NumberFormat(undefined, {
  style: "currency",
  currency: "USD",
}).format(123.45);

// You can still override the locale if needed
const date = new intl.value.DateTimeFormat("fr-FR").format(new Date());

// Access other Intl features
const displayNames = new intl.value.DisplayNames(undefined, {
  type: "language",
});
const languageName = displayNames.of("fr");
</script>

<template>
  <div>
    <p>{{ formatted }}</p>
    <p>{{ date }}</p>
    <p>{{ languageName }}</p>
  </div>
</template>

Vanilla JS / Node.js Formatters

For non-framework contexts, import formatters directly from intlayer. Note that you must pass the locale manually.

Import

Copy code

Copy the code to the clipboard

import {
  number,
  percentage,
  currency,
  date,
  relativeTime,
  units,
  compact,
  list,
  Intl,
} from "intlayer";

Formatter Functions

`number(value, options?)`

Formats a numeric value using locale-aware grouping and decimals.

value: number | string
options: Intl.NumberFormatOptions & { locale?: LocalesValues }

Copy code

Copy the code to the clipboard

number(123456.789); // "123,456.789" (in en-US)
number("1000000", { locale: "fr" }); // "1 000 000"
number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"

`percentage(value, options?)`

Formats a number as a percentage string. Values greater than 1 are normalized (e.g., 25 → 25%, 0.25 → 25%).

value: number | string
options: Intl.NumberFormatOptions & { locale?: LocalesValues }

Copy code

Copy the code to the clipboard

percentage(0.25); // "25%"
percentage(25); // "25%"
percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"

`currency(value, options?)`

Formats a value as localized currency. Defaults to USD.

value: number | string
options: Intl.NumberFormatOptions & { locale?: LocalesValues }
- Common: currency, currencyDisplay ("symbol" | "code" | "name")

Copy code

Copy the code to the clipboard

currency(1234.5, { currency: "EUR" }); // "€1,234.50"
currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"

`date(date, optionsOrPreset?)`

Formats a date/time value.

date: Date | string | number
optionsOrPreset: Intl.DateTimeFormatOptions & { locale?: LocalesValues } or preset: "short" | "long" | "dateOnly" | "timeOnly" | "full"

Copy code

Copy the code to the clipboard

date(new Date(), "short"); // e.g., "08/02/25, 14:30"
date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"

`relativeTime(from, to?, options?)`

Formats relative time between two instants.

from: Date | string | number
to: Date | string | number (defaults to new Date())
options: { locale?, unit?, numeric?, style? }

Copy code

Copy the code to the clipboard

const now = new Date();
const in3Days = new Date(now.getTime() + 3 * 864e5);
relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"

const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"

`units(value, options?)`

Formats a numeric value with a unit.

value: number | string
options: Intl.NumberFormatOptions & { locale?: LocalesValues }
- Common: unit (e.g., "kilometer", "byte"), unitDisplay ("short" | "narrow" | "long")

Copy code

Copy the code to the clipboard

units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B"

`compact(value, options?)`

Formats a number using compact notation.

value: number | string
options: Intl.NumberFormatOptions & { locale?: LocalesValues }

Copy code

Copy the code to the clipboard

compact(1200); // "1.2K"
compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"

`list(values, options?)`

Formats an array into a localized list string.

values: (string | number)[]
options: Intl.ListFormatOptions & { locale?: LocalesValues }
- Common: type ("conjunction" | "disjunction" | "unit"), style ("long" | "short" | "narrow")

Copy code

Copy the code to the clipboard

list(["apple", "banana", "orange"]); // "apple, banana, and orange"
list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge, vert ou bleu"

Cached Intl

The exported Intl from intlayer is a cached wrapper around the global Intl. It memoizes formatter instances (NumberFormat, DateTimeFormat, etc.) to avoid repeatedly constructing them, improving performance.

Copy code

Copy the code to the clipboard

import { Intl } from "intlayer";

// Number formatting
const numberFormat = new Intl.NumberFormat("en-GB", {
  style: "currency",
  currency: "GBP",
});
numberFormat.format(1234.5); // "£1,234.50"

// Display names for languages, regions, etc.
const displayNames = new Intl.DisplayNames("fr", { type: "language" });
displayNames.of("en"); // "anglais"

// Collation for sorting
const collator = new Intl.Collator("fr", { sensitivity: "base" });
collator.compare("é", "e"); // 0 (equal)

// Plural rules
const pluralRules = new Intl.PluralRules("fr");
pluralRules.select(1); // "one"
pluralRules.select(2); // "other"

Additional Intl Features

`Intl.DisplayNames`

For localized names of languages, regions, currencies, and scripts:

Copy code

Copy the code to the clipboard

import { Intl } from "intlayer";

const languageNames = new Intl.DisplayNames("en", { type: "language" });
languageNames.of("fr"); // "French"

const regionNames = new Intl.DisplayNames("fr", { type: "region" });
regionNames.of("US"); // "États-Unis"

`Intl.Collator`

For locale-aware string comparison and sorting:

Copy code

Copy the code to the clipboard

import { Intl } from "intlayer";

const collator = new Intl.Collator("de", {
  sensitivity: "base",
  numeric: true,
});

const words = ["äpfel", "zebra", "100", "20"];
words.sort(collator.compare); // ["20", "100", "äpfel", "zebra"]

`Intl.PluralRules`

For determining plural forms in different locales:

Copy code

Copy the code to the clipboard

import { Intl } from "intlayer";

const pluralRules = new Intl.PluralRules("ar");
pluralRules.select(0); // "zero"
pluralRules.select(1); // "one"
pluralRules.select(2); // "two"
pluralRules.select(3); // "few"
pluralRules.select(11); // "many"

Locale Utilities

`getLocaleName(displayLocale, targetLocale?)`

Gets the localized name of a locale:

Copy code

Copy the code to the clipboard

import { getLocaleName } from "intlayer";

getLocaleName("fr", "en"); // "French"
getLocaleName("en", "fr"); // "anglais"
getLocaleName("de", "es"); // "alemán"

`getLocaleLang(locale?)`

Extracts the language code from a locale string:

Copy code

Copy the code to the clipboard

import { getLocaleLang } from "intlayer";

getLocaleLang("en-US"); // "en"
getLocaleLang("fr-CA"); // "fr"

`getLocaleFromPath(inputUrl)`

Extracts the locale segment from a URL or pathname:

Copy code

Copy the code to the clipboard

import { getLocaleFromPath } from "intlayer";

getLocaleFromPath("/en/dashboard"); // "en"
getLocaleFromPath("/fr/dashboard"); // "fr"
getLocaleFromPath("/dashboard"); // "en" (default locale)

`getPathWithoutLocale(inputUrl, locales?)`

Removes the locale segment from a URL:

Copy code

Copy the code to the clipboard

import { getPathWithoutLocale } from "intlayer";

getPathWithoutLocale("/en/dashboard"); // "/dashboard"
getPathWithoutLocale("/fr/dashboard"); // "/dashboard"

`getLocalizedUrl(url, currentLocale, locales?, defaultLocale?, prefixDefault?)`

Generates a localized URL:

Copy code

Copy the code to the clipboard

import { getLocalizedUrl } from "intlayer";

getLocalizedUrl("/about", "fr", ["en", "fr"], "en", false); // "/fr/about"
getLocalizedUrl("/about", "en", ["en", "fr"], "en", false); // "/about"

`getHTMLTextDir(locale?)`

Returns the text direction for a locale:

Copy code

Copy the code to the clipboard

import { getHTMLTextDir } from "intlayer";

getHTMLTextDir("en-US"); // "ltr"
getHTMLTextDir("ar"); // "rtl"
getHTMLTextDir("he"); // "rtl"

Content Handling Utilities

`getContent(node, nodeProps, locale?)`

Transforms a content node with all available plugins:

Copy code

Copy the code to the clipboard

import { getContent } from "intlayer";

const content = getContent(
  contentNode,
  { dictionaryKey: "common", dictionaryPath: "/path/to/dict" },
  "fr"
);

`getTranslation(languageContent, locale?, fallback?)`

Extracts content for a specific locale:

Copy code

Copy the code to the clipboard

import { getTranslation } from "intlayer";

const content = getTranslation(
  { en: "Hello", fr: "Bonjour", de: "Hallo" },
  "fr",
  true
); // "Bonjour"

`getIntlayer(dictionaryKey, locale?, plugins?)`

Retrieves and transforms content from a dictionary:

Copy code

Copy the code to the clipboard

import { getIntlayer } from "intlayer";

const content = getIntlayer("common", "fr");

Notes

All helpers accept string inputs; they are internally coerced to numbers or dates.
Locale defaults to your configured internationalization.defaultLocale if not provided.
These utilities are thin wrappers; for advanced formatting, pass through the standard Intl options.

Function Fetching Dynamic Dictionary

Version History

Intlayer Formatters

Table of Contents

Overview

React Formatters

Quick Start

Available Hooks

Complete Example

useIntl Hook

Vue Formatters

Quick Start

Available Composables

Complete Example

useIntl Composable

Vanilla JS / Node.js Formatters

Import

Formatter Functions

number(value, options?)

percentage(value, options?)

currency(value, options?)

date(date, optionsOrPreset?)

relativeTime(from, to?, options?)

units(value, options?)

compact(value, options?)

list(values, options?)

Cached Intl

Additional Intl Features

Intl.DisplayNames

Intl.Collator

Intl.PluralRules

Locale Utilities

getLocaleName(displayLocale, targetLocale?)

getLocaleLang(locale?)

getLocaleFromPath(inputUrl)

getPathWithoutLocale(inputUrl, locales?)

getLocalizedUrl(url, currentLocale, locales?, defaultLocale?, prefixDefault?)

getHTMLTextDir(locale?)

Content Handling Utilities

getContent(node, nodeProps, locale?)

getTranslation(languageContent, locale?, fallback?)

getIntlayer(dictionaryKey, locale?, plugins?)

Notes

`useIntl` Hook

`useIntl` Composable

`number(value, options?)`

`percentage(value, options?)`

`currency(value, options?)`

`date(date, optionsOrPreset?)`

`relativeTime(from, to?, options?)`

`units(value, options?)`

`compact(value, options?)`

`list(values, options?)`

`Intl.DisplayNames`

`Intl.Collator`

`Intl.PluralRules`

`getLocaleName(displayLocale, targetLocale?)`

`getLocaleLang(locale?)`

`getLocaleFromPath(inputUrl)`

`getPathWithoutLocale(inputUrl, locales?)`

`getLocalizedUrl(url, currentLocale, locales?, defaultLocale?, prefixDefault?)`

`getHTMLTextDir(locale?)`

`getContent(node, nodeProps, locale?)`

`getTranslation(languageContent, locale?, fallback?)`

`getIntlayer(dictionaryKey, locale?, plugins?)`