@sphinxjs/react

React hooks and provider for Sphinx. Provides SphinxProvider, useGettext, useTranslatedLabel, useNormalisedLabel, and domain-scoped variants.

Install

pnpm add @sphinxjs/react sphinxjs

Requires react ^19.0.0 as a peer dependency.

API

SphinxProvider

Initialises Sphinx at the React tree root. Pass the same props as initSphinx:

import { SphinxProvider } from "@sphinxjs/react";
import { getGlobTranslations } from "sphinxjs/loader";

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

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

useSphinx(errorMessage?)

Returns the current SphinxContextProps from the global store. Throws if Sphinx has not been initialised.

useGettext()

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

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

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

useTranslatedLabel(label, options?)

Translates a Label value reactively.

import { useTranslatedLabel } from "@sphinxjs/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 "@sphinxjs/react";

const useAdminGettext = getUseBoundDomainGettext("admin");

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

Unbound hooks

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