React SDK

@messagevisor/react adds React-specific helpers on top of @messagevisor/sdk. It is designed for applications that want both ergonomic hooks and access to the underlying imperative SDK instance.

Install#

Command

$ npm install @messagevisor/sdk @messagevisor/react

Provider setup#

React

import { createMessagevisor } from "@messagevisor/sdk";
import { createICUModule } from "@messagevisor/module-icu";
import { MessagevisorProvider } from "@messagevisor/react";
import datafile from "./datafiles/messagevisor-web-en-US.json";
const m = createMessagevisor({
  datafile,
  locale: "en-US",
  context: { platform: "web" },
  modules: [createICUModule({ ignoreTags: false })],
});
export function AppRoot() {
  return (
    <MessagevisorProvider
      instance={m}
      defaultRichTextElements={{
        strong: (chunks) => <strong>{chunks}</strong>,
        link: (chunks) => <a href="/terms">{chunks}</a>,
      }}
    >
      {/* app */}
    </MessagevisorProvider>
  );
}

API layers#

React support is intentionally split into two layers:

Imperative layer#

useMessagevisor() gives you a stable API object for calling SDK methods directly.

This is good when you want:

t() in event handlers or render logic
imperative state setters such as setLocale() or setContext()
direct access to methods like getDirection(locale?)

Reactive layer#

useReactiveMessagevisor() and the focused hooks subscribe to SDK snapshot changes and re-render when relevant state changes.

This is good when you want:

current locale
direction
context
currency/time zone
translated values that should react to locale/datafile changes

Main exports#

The package exports:

MessagevisorProvider
MessagevisorContext
useMessagevisor
useMessagevisorSnapshot
useReactiveMessagevisor
useSdk

Focused reactive hooks include:

useLocale()
useDirection()
useLocaleInfo()
useMessagevisorContext()
useCurrency()
useTimeZone()
useTranslation()
useFormatMessage()
formatter hooks such as useFormatNumber() and useFormatDate()

Provider options include:

defaultRichTextElements for shared rich text tag handlers
wrapRichTextChunksInFragment for array output wrapping
modules for React-only post-processing transforms
textComponent for formatted components from the compatibility layer

Example#

React

import {
  useDirection,
  useLocaleInfo,
  useMessagevisor,
  useTranslation,
} from "@messagevisor/react";
function Greeting() {
  const { t, setLocale } = useMessagevisor();
  const direction = useDirection();
  const { locale } = useLocaleInfo();
  const welcome = useTranslation("dashboard.welcome", { name: "Ada" });
  return (
    <div dir={direction}>
      <button onClick={() => setLocale("ar-SA")}>Switch</button>
      <p>{locale}</p>
      <p>{welcome}</p>
      <p>{t("auth.signin")}</p>
    </div>
  );
}

`useDirection()` and `useLocaleInfo()`#

These two hooks are especially useful for locale-aware layout:

useDirection() returns the active locale's ltr / rtl value
useLocaleInfo() returns { locale, direction }

This gives you a nice split:

use useDirection() when you only need dir={...}
use useLocaleInfo() when locale and direction should travel together

Imperative vs reactive direction access#

There are two ways to ask for direction:

useDirection() for the active locale, reactively
getDirection(locale?) from useMessagevisor() for imperative lookup

That split is deliberate:

hooks model current app state
imperative methods support arbitrary lookups

Rich text and modules#

React helpers cooperate with the underlying module system, including rich-text flows.

That means useTranslation() and useFormatMessage() do more than just string substitution. They can also wrap richer module output appropriately for React.

The usual rich text setup is:

configure the SDK with createICUModule({ ignoreTags: false })
put common tag handlers on MessagevisorProvider
pass per-call tag handlers only when one message needs special behavior

If you are migrating an app that already uses FormattedMessage, useIntl, or injectIntl, read React Intl compatibility.

Edge cases and behavior notes#

`useMessagevisor()` does not subscribe by itself#

It gives you methods. The actual reactivity comes from hooks that read snapshot state or translated values.

Locale and datafile changes re-trigger reactive hooks#

Hooks such as useDirection() and useLocaleInfo() are designed to respond to:

locale switches
datafile replacement
snapshot changes in the underlying SDK

Keep direction handling close to layout#

Treat direction as a layout concern, not just a translation concern. A small wrapper near your page shell often works better than sprinkling dir props everywhere.