> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.auth0-mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# useChangeLanguage

<ParamField body="useChangeLanguage" type="(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`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LanguageChangeOptions) argument:

  <ParamField body="language" type="string" required>
    The locale code to switch to. Must match one of the locales enabled in your Auth0 tenant. Example: `"en"`, `"fr"`, `"es"`.
  </ParamField>

  <ParamField body="persist" type="&#x22;session&#x22;">
    Persistence scope for the language preference. Defaults to `"session"`.
  </ParamField>

  ## Returns

  `(options: LanguageChangeOptions) => Promise<void>`

  A function that submits the language change. The returned promise resolves when submission completes.

  ```tsx Example theme={null}
  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:

  ```tsx theme={null}
  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.
</ParamField>