react-intl

library10.1.2jsnpmunverified

React Intl is a mature and widely-used library for internationalizing React applications. It provides a comprehensive set of components and an API for formatting dates, numbers, and strings, including complex pluralization and translation handling, leveraging JavaScript's built-in `Intl` API. Currently at version 10.1.2, it is part of the broader FormatJS ecosystem, which also includes tools for message extraction and compilation. The library maintains an active development pace, with regular patch and minor releases, and significant major version updates to keep pace with React and JavaScript ecosystem changes. Its key differentiators include a component-based approach for common UI elements, a hook-based API for imperative formatting, and robust support for ICU MessageFormat syntax, making it a powerful choice for globalized React apps.

web-framework serialization

npm install react-intl

package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-INTL

react-intl

web-frameworkjavascriptv10.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IntlProvider

✓ import { IntlProvider } from 'react-intl';

✗ const IntlProvider = require('react-intl').IntlProvider;

`IntlProvider` is a named export. It must wrap your React app to provide the internationalization context.

FormattedMessage

✓ import { FormattedMessage } from 'react-intl';

✗ import FormattedMessage from 'react-intl';

`FormattedMessage` is a named component export used for declarative message formatting.

useIntl

✓ import { useIntl } from 'react-intl';

✗ import { useIntl } from 'react-intl/hooks'; /* deprecated path */

`useIntl` is a named hook export, available since React 16.8, providing imperative access to the Intl API.

defineMessages

✓ import { defineMessages } from 'react-intl';

✗ import defineMessages from 'react-intl';

`defineMessages` is a named helper function used to define messages outside of components for extraction and maintainability.

This quickstart initializes `react-intl` with a French locale and a set of predefined messages. It demonstrates both the declarative `FormattedMessage` component for rendering localized strings with interpolated values and rich text, and the imperative `useIntl` hook for formatting a title. It showcases date, plural, and currency formatting.

import React from 'react'; import { IntlProvider, FormattedMessage, useIntl } from 'react-intl'; // Define messages for a specific locale const messagesInFrench = { greeting: 'Bonjour {name}, bienvenue sur notre site !', welcome_page_title: 'Page d\'accueil', current_date: 'Aujourd\'hui, {ts, date, ::full}', unread_notifications: '{count, plural, one {# notification non lue} other {# notifications non lues}}', product_price: 'Prix : {price, number, currency}', }; // Example functional component using FormattedMessage and useIntl hook const HomePage = () => { const intl = useIntl(); const userName = 'Jean-Luc'; const notificationCount = 3; const productPrice = 42.50; return ( <div> <h1>{intl.formatMessage({ id: 'welcome_page_title' })}</h1> <p> <FormattedMessage id="greeting" values={{ name: <b>{userName}</b> }} /> </p> <p> <FormattedMessage id="current_date" values={{ ts: new Date() }} /> </p> <p> <FormattedMessage id="unread_notifications" values={{ count: notificationCount }} /> </p> <p> <FormattedMessage id="product_price" values={{ price: productPrice, currency: 'EUR' }} /> </p> </div> ); }; // Root component to provide the IntlProvider context const App = () => ( <IntlProvider locale="fr-FR" messages={messagesInFrench}> <HomePage /> </IntlProvider> ); export default App;

Debug

Known issues

breakingReact Intl v10.x primarily targets React 19. Ensure your project's React and `@types/react` dependencies are updated accordingly. Older React versions might encounter compatibility issues, especially with internal key handling for elements in arrays.

fix

Upgrade `react` and `@types/react` to `^19.0.0`. Review the `react-intl` v10 upgrade guide on FormatJS documentation.

affects: >=10.0.0

breakingStarting with React Intl v7, support for Node.js versions older than 16 was dropped. Ensure your development and deployment environments run Node.js 16 or later to leverage full internationalization support natively.

fix

Upgrade your Node.js environment to version 16 or newer. For older environments, polyfills for `Intl` APIs might be required.

affects: >=7.0.0

breakingEarlier versions of React Intl (e.g., v8.x) addressed key warnings related to React 19's stricter key handling when using `React.cloneElement` internally. If upgrading from older versions, be aware of changes to how rich text elements are wrapped (now often with `React.Fragment`).

fix

Update to `react-intl@8.0.0` or newer. This issue was fixed by replacing `cloneElement` with `React.Fragment` internally.

affects: >=8.0.0 <10.0.0

gotchaBy default, `react-intl` bundles with only basic English locale data. To support other languages, you must explicitly import and add the necessary locale data, particularly for features like `Intl.PluralRules` or `Intl.RelativeTimeFormat`.

fix

Dynamically import locale data for each language your application supports using a pattern like `import '@formatjs/intl-pluralrules/locale-data/fr';` and ensure polyfills for `Intl` APIs are included for older browser support.

affects: >=2.0.0

gotchaAll `react-intl` components and hooks must be rendered within an `IntlProvider`. Failure to do so will result in an error indicating that `IntlProvider` was not found in the React context.

fix

Wrap your root React component (or the relevant sub-tree) with `IntlProvider`, ensuring it receives `locale` and `messages` props.

affects: *

gotchaReact Intl expects message IDs to be simple strings (e.g., `homepage.header.greeting`). Using deeply nested JavaScript objects for message IDs within the `messages` prop can lead to unexpected behavior or difficulties with message extraction tools.

fix

Flatten your message keys into dot-separated strings or another convention that results in plain string IDs. Ensure consistency for maintainability and tool compatibility.

affects: *

Errors

Common errors & fixes

Error: [React Intl] IntlProvider was not found in the React context.

Attempting to use `FormattedMessage`, `useIntl`, or other `react-intl` components/hooks outside of an `IntlProvider`'s context.

fix

Ensure that your entire application or the relevant component tree is wrapped within an `IntlProvider` component, providing the `locale` and `messages` props.

TypeError: (0 , react_intl__WEBPACK_IMPORTED_MODULE_2__.useIntl) is not a function

This typically occurs in older React environments (pre-16.8) where hooks are not supported, or if there's a module resolution issue where an older `react-intl` version without hooks is being loaded, or incorrect Babel/Webpack configuration.

fix

Verify that your `react` dependency is at least `16.8.0`. Check your module bundler configuration to ensure `react-intl` is correctly resolved and that you're using a compatible version. Update `react-intl` to a version that supports hooks.

Invariant Violation: [React Intl] The 'locale' prop must be a string.

The `locale` prop passed to `IntlProvider` is not a string, or is `undefined` (e.g., due to a variable not being correctly initialized).

fix

Ensure the `locale` prop passed to `IntlProvider` is always a valid BCP 47 language tag string, such as 'en-US' or 'fr-FR'. Consider a fallback mechanism for determining the user's locale.

ReferenceError: Intl is not defined

The JavaScript runtime environment (e.g., older browsers, specific Node.js builds, or React Native environments without `Intl` support) lacks the native `Intl` object or required `Intl` APIs.

fix

Include polyfills for the `Intl` object and specific `Intl` APIs (`Intl.PluralRules`, `Intl.RelativeTimeFormat`, etc.) as needed for your target environments. For Node.js, ensure version 16+ is used.

Warning: Missing locale data for locale: "undefined". Using default locale: "en" as fallback.

This warning indicates that `react-intl` cannot find the necessary locale data for the requested locale, often because the data hasn't been imported or the locale string is incorrect/missing, causing it to fall back to English.

fix

Ensure you are explicitly importing locale data for all supported languages using `@formatjs/intl-*` packages (e.g., `import '@formatjs/intl-pluralrules/locale-data/fr';`) and that your `IntlProvider` correctly receives the `locale` prop.

Upgrade

Version history

10.1.2latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React components and hooks.

@types/reactrequiredPeer dependency for TypeScript types, aligning with React versions.

Agent activity

4 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/react-intl ↗

homepagehttps://formatjs.io/docs/react-intl ↗