{"id":11734,"library":"react-intl","title":"React Intl","description":"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.","status":"active","version":"10.1.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/formatjs/formatjs","tags":["javascript","format","formatting","globalization","i18n","internationalization","intl","locale","localization","typescript"],"install":[{"cmd":"npm install react-intl","lang":"bash","label":"npm"},{"cmd":"yarn add react-intl","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-intl","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React components and hooks.","package":"react","optional":false},{"reason":"Peer dependency for TypeScript types, aligning with React versions.","package":"@types/react","optional":false}],"imports":[{"note":"`IntlProvider` is a named export. It must wrap your React app to provide the internationalization context.","wrong":"const IntlProvider = require('react-intl').IntlProvider;","symbol":"IntlProvider","correct":"import { IntlProvider } from 'react-intl';"},{"note":"`FormattedMessage` is a named component export used for declarative message formatting.","wrong":"import FormattedMessage from 'react-intl';","symbol":"FormattedMessage","correct":"import { FormattedMessage } from 'react-intl';"},{"note":"`useIntl` is a named hook export, available since React 16.8, providing imperative access to the Intl API.","wrong":"import { useIntl } from 'react-intl/hooks'; /* deprecated path */","symbol":"useIntl","correct":"import { useIntl } from 'react-intl';"},{"note":"`defineMessages` is a named helper function used to define messages outside of components for extraction and maintainability.","wrong":"import defineMessages from 'react-intl';","symbol":"defineMessages","correct":"import { defineMessages } from 'react-intl';"}],"quickstart":{"code":"import React from 'react';\nimport { IntlProvider, FormattedMessage, useIntl } from 'react-intl';\n\n// Define messages for a specific locale\nconst messagesInFrench = {\n greeting: 'Bonjour {name}, bienvenue sur notre site !',\n welcome_page_title: 'Page d\\'accueil',\n current_date: 'Aujourd\\'hui, {ts, date, ::full}',\n unread_notifications: '{count, plural, one {# notification non lue} other {# notifications non lues}}',\n product_price: 'Prix : {price, number, currency}',\n};\n\n// Example functional component using FormattedMessage and useIntl hook\nconst HomePage = () => {\n const intl = useIntl();\n const userName = 'Jean-Luc';\n const notificationCount = 3;\n const productPrice = 42.50;\n\n return (\n
\n );\n};\n\n// Root component to provide the IntlProvider context\nconst App = () => (\n \n \n \n);\n\nexport default App;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade `react` and `@types/react` to `^19.0.0`. Review the `react-intl` v10 upgrade guide on FormatJS documentation.","message":"React 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.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Upgrade your Node.js environment to version 16 or newer. For older environments, polyfills for `Intl` APIs might be required.","message":"Starting 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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Update to `react-intl@8.0.0` or newer. This issue was fixed by replacing `cloneElement` with `React.Fragment` internally.","message":"Earlier 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`).","severity":"breaking","affected_versions":">=8.0.0 <10.0.0"},{"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.","message":"By 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`.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Wrap your root React component (or the relevant sub-tree) with `IntlProvider`, ensuring it receives `locale` and `messages` props.","message":"All `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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"React 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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure that your entire application or the relevant component tree is wrapped within an `IntlProvider` component, providing the `locale` and `messages` props.","cause":"Attempting to use `FormattedMessage`, `useIntl`, or other `react-intl` components/hooks outside of an `IntlProvider`'s context.","error":"Error: [React Intl] IntlProvider was not found in the React context."},{"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.","cause":"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.","error":"TypeError: (0 , react_intl__WEBPACK_IMPORTED_MODULE_2__.useIntl) is not a function"},{"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.","cause":"The `locale` prop passed to `IntlProvider` is not a string, or is `undefined` (e.g., due to a variable not being correctly initialized).","error":"Invariant Violation: [React Intl] The 'locale' prop must be a string."},{"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.","cause":"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.","error":"ReferenceError: Intl is not defined"},{"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.","cause":"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.","error":"Warning: Missing locale data for locale: \"undefined\". Using default locale: \"en\" as fallback."}],"ecosystem":"npm"}