Skip to main content
​
useChangeLanguage
(options: LanguageChangeOptions) => Promise<void>
React hook that returns a function for changing the display language on the current ACUL screen. The screen automatically re-renders with the new locale after submission. The language must be one of the enabled locales configured in your Auth0 tenant.

​
Key Features

  • Tenant-aware — only accepts locales enabled in your Auth0 tenant configuration.
  • Automatic re-render — the screen updates to the new language after the change is submitted.
  • Session persistence — language preference is stored for the duration of the session by default.

​
Parameters

The returned function accepts a single LanguageChangeOptions argument:
​
language
string
required
The locale code to switch to. Must match one of the locales enabled in your Auth0 tenant. Example: "en", "fr", "es".
​
persist
"session"
Persistence scope for the language preference. Defaults to "session".

​
Returns

(options: LanguageChangeOptions) => Promise<void>A function that submits the language change. The returned promise resolves when submission completes.
Example
import { useChangeLanguage } from "@auth0/auth0-acul-react";

export function LanguageSwitcher() {
  const changeLanguage = useChangeLanguage();

  return (
    <div>
      <button onClick={() => changeLanguage({ language: "en" })}>English</button>
      <button onClick={() => changeLanguage({ language: "fr" })}>Français</button>
      <button onClick={() => changeLanguage({ language: "es" })}>Español</button>
    </div>
  );
}
You can also populate the options dynamically from tenant configuration:
import { useChangeLanguage, useCurrentScreen } from "@auth0/auth0-acul-react";

export function LocaleSelector() {
  const changeLanguage = useChangeLanguage();
  const { tenant, transaction } = useCurrentScreen();

  return (
    <select
      defaultValue={transaction.locale}
      onChange={e => changeLanguage({ language: e.target.value })}
    >
      {tenant.enabledLocales.map(locale => (
        <option key={locale} value={locale}>{locale}</option>
      ))}
    </select>
  );
}

​
Remarks

  • The language value must match a locale enabled in your Auth0 tenant — passing an unsupported locale will result in an error.
  • Use useCurrentScreen() to access tenant.enabledLocales and transaction.locale for dynamic locale selection.
  • Call useChangeLanguage at the top level of your component; do not call it conditionally or inside event handlers.