@polyt/react

React hooks and provider for Polyt. Provides PolytProvider, useGettext, useTranslatedLabel, useNormalisedLabel, and domain-scoped variants.

Install

pnpm add @polyt/react polyt

Requires react ^19.0.0 as a peer dependency.

API

PolytProvider

Initialises Polyt at the React tree root. Pass the same props as initPolyt:

import { PolytProvider } from "@polyt/react";
import { getGlobTranslations } from "polyt/loader";

const translations = await getGlobTranslations(
  import.meta.glob("./locales/*.po", { query: "?raw", import: "default" }),
);

createRoot(document.getElementById("root")!).render(
  <PolytProvider locales={["en", "fr"]} locale="en" translations={translations}>
    <App />
  </PolytProvider>,
);

usePolyt(errorMessage?)

Returns the current PolytContextProps from the global store. Throws if Polyt has not been initialised.

useGettext()

Returns a GettextUtilities object (all gettext functions) memoised for the current Polyt instance.

import { useGettext } from "@polyt/react";

function MyComponent() {
  const { gettext, ngettext } = useGettext();
  return <p>{gettext("Hello")}</p>;
}

useTranslatedLabel(label, options?)

Translates a Label value reactively.

import { useTranslatedLabel } from "@polyt/react";

function CollectionTitle({ label }: { label: Label }) {
  return <h1>{useTranslatedLabel(label)}</h1>;
}

useNormalisedLabel(label?, options?)

Like useTranslatedLabel but with fallback key humanisation and plural/singular coercion.

getUseBoundDomainGettext(domain)

Higher-order function that returns a useGettext-compatible hook pre-scoped to a specific translation domain. Useful for multi-domain setups.

import { getUseBoundDomainGettext } from "@polyt/react";

const useAdminGettext = getUseBoundDomainGettext("admin");

function AdminPanel() {
  const { gettext } = useAdminGettext();
  return <p>{gettext("Dashboard")}</p>;
}

Unbound hooks

useUnboundGettext, useUnboundTranslatedLabel, useUnboundNormalisedLabel accept a PolytGetter as the first argument for custom injection scenarios.