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

# Configure Auth0ComponentProvider

> Learn how Auth0ComponentProvider syncronizes authentication, internationalization, theming, toast notifications, and caching options.

<Warning>
  Auth0 Universal Components is currently in Early Access. By using it, you
  agree to the applicable Free Trial terms in [Okta's Master Subscription
  Agreement](https://www.okta.com/agreements/). To learn more, read [Product
  Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

The `Auth0ComponentProvider` is the orchestration layer for [Auth0 Universal Components](/docs/get-started/universal-components/universal-components-overview). Auth0 SDKs manage sessions and tokens, and the `Auth0ComponentProvider` translates that identity state into a functional, branded UI context. `Auth0ComponentProvider` makes sure components, such as MFA enrollment, have the necessary permissions, cached data, and styling.

## Benefits

`Auth0ComponentProvider` is the required root wrapper for all Auth0 Universal Components. Benefits to using the wrapper are:

* **Identity Alignment**: Bridges the gap between [Auth0 SDKs](/docs/libraries) and the [My Account API](/docs/manage-users/my-account-api) to ensure requests are signed with user-scoped tokens.
* **Performance Optimization**: Implements a shared **TanStack Query** cache specifically tuned for identity workflows to prevent redundant API calls and layout shifts.
* **Design System Consistency**: Propagates **Tailwind CSS** variables and **Shadcn**-compatible themes across the component tree.
* **Global Feedback**: Manages a unified toast notification system for security alerts and workflow status.

## Integration architecture

Nest `Auth0ComponentProvider` in your authentication provider (`Auth0Provider`). This configuration allows access to authentication state and token acquisition methods required to call Auth0 APIs.

## Configure `Auth0ComponentProvider`

<Tabs>
  <Tab title="React">
    ```tsx App.tsx theme={null}
    import { Auth0Provider } from "@auth0/auth0-react";
    import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";

    function App() {
      return (
        <Auth0Provider
          domain="your-tenant.auth0.com"
          clientId="YOUR_CLIENT_ID"
          authorizationParams={{ redirect_uri: window.location.origin }}
          interactiveErrorHandler='popup' // Required to handle step-up auth challenges via Universal Login popup
        >
          <Auth0ComponentProvider domain="your-tenant.auth0.com">
            {/* Your app with Auth0 Universal Components */}
          </Auth0ComponentProvider>
        </Auth0Provider>
      );
    }
    ```

    ***

    ## Properties

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Required</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>domain</code></td>
          <td><code>string</code></td>
          <td>Yes</td>
          <td>Auth0 tenant domain ("YOUR\_AUTH0\_TENANT.auth0.com").</td>
        </tr>

        <tr>
          <td><code>previewMode</code></td>
          <td><code>boolean</code></td>
          <td>No</td>
          <td>When <code>true</code>, skips API client initialization. Used for documentation previews and demos.</td>
        </tr>

        <tr>
          <td><code>i18n</code></td>
          <td><code>I18nOptions</code></td>
          <td>No</td>
          <td>Internationalization settings including currentLanguage and fallbackLanguage.</td>
        </tr>

        <tr>
          <td><code>themeSettings</code></td>
          <td><code>ThemeSettings</code></td>
          <td>No</td>
          <td>Theme configuration including mode (light/dark), theme variant (default/minimal/rounded), and CSS variables.</td>
        </tr>

        <tr>
          <td><code>toastSettings</code></td>
          <td><code>ToastSettings</code></td>
          <td>No</td>
          <td>Toast notification configuration including provider selection (sonner/custom), positioning, duration, and custom toast methods.</td>
        </tr>

        <tr>
          <td><code>cacheConfig</code></td>
          <td><code>QueryCacheConfig</code></td>
          <td>No</td>
          <td>Controls TanStack Query caching (two min stale / five min GC by default). Set <code>enabled: false</code> to force fresh data.</td>
        </tr>

        <tr>
          <td><code>loader</code></td>
          <td><code>React.ReactNode</code></td>
          <td>No</td>
          <td>Custom loading component to display during authentication initialization.</td>
        </tr>
      </tbody>
    </table>

    ***

    ## User experience

    ***

    **i18n**

    Use the following properties to align the Universal Components with your application's design system and locale.

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Required</th>
          <th>Default</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>currentLanguage</code>
          </td>

          <td>
            <code>string</code>
          </td>

          <td>Yes</td>
          <td>-</td>
          <td>Current language code (e.g., "en", "es", "fr")</td>
        </tr>

        <tr>
          <td>
            <code>fallbackLanguage</code>
          </td>

          <td>
            <code>string</code>
          </td>

          <td>No</td>

          <td>
            <code>"en"</code>
          </td>

          <td>Fallback language code when translations are missing</td>
        </tr>
      </tbody>
    </table>

    ***

    **themeSettings**

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Default</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>mode</code>
          </td>

          <td>
            <code>"light" | "dark"</code>
          </td>

          <td>
            <code>"light"</code>
          </td>

          <td>Theme color mode</td>
        </tr>

        <tr>
          <td>
            <code>theme</code>
          </td>

          <td>
            <code>"default" | "minimal" | "rounded"</code>
          </td>

          <td>
            <code>"default"</code>
          </td>

          <td>Theme variant with different styling approaches</td>
        </tr>

        <tr>
          <td>
            <code>variables</code>
          </td>

          <td>
            <code>StylingVariables</code>
          </td>

          <td>
            <code>
              {}
            </code>
          </td>

          <td>CSS custom properties for common, light, and dark themes</td>
        </tr>
      </tbody>
    </table>

    <Accordion title="Available CSS Variables">
      **Common (applies to all themes):**

      **Typography:**

      * `--font-size-page-header`
      * `--font-size-page-description`
      * `--font-size-heading`
      * `--font-size-title`
      * `--font-size-subtitle`
      * `--font-size-body`
      * `--font-size-paragraph`
      * `--font-size-label`

      **Border Radius:**

      * `--radius-xs` through `--radius-9xl`

      **Light & Dark (theme-specific colors and shadows):**

      **Colors:**

      * `--background`, `--foreground`
      * `--card`, `--card-foreground`
      * `--primary`, `--primary-foreground`
      * `--secondary`, `--secondary-foreground`
      * `--accent`, `--accent-foreground`
      * `--muted`, `--muted-foreground`
      * `--destructive`, `--destructive-foreground`
      * `--popover`, `--popover-foreground`
      * `--input`, `--border`, `--ring`
      * `--color-page`
      * `--color-info`, `--color-info-foreground`
      * `--color-success`, `--color-success-foreground`
      * `--color-warning`, `--color-warning-foreground`
      * `--color-destructive-border`
      * `--color-popover-border`
      * `--color-input-foreground`
      * `--color-input-muted`

      **Shadows:**

      * `--shadow-bevel-*` (xs, sm, md, lg, xl, 2xl)
      * `--shadow-button-*` (resting, hover, focus)
      * `--shadow-button-destructive-*`
      * `--shadow-button-outlined-*`
      * `--shadow-input-*` (resting, hover, focus)
      * `--shadow-input-destructive-*`
      * `--shadow-checkbox-*` (resting, hover)
      * `--shadow-switch-*` (resting, hover, focus, thumb, thumb-dark)
    </Accordion>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      For detailed styling examples and customization patterns, read the [Customize
      Style and Themes with Universal
      Components](/docs/get-started/universal-components/universal-components-style).
    </Callout>

    ***

    **toastSettings**

    Toast settings support two provider types: **Sonner** (default) or **custom**. Each provider has its own configuration structure for better type safety.

    <Tabs>
      <Tab title="Sonner Provider (Default)">
        | Property               | Type            | Default       | Description                                                                                                         |
        | ---------------------- | --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
        | `provider`             | `"sonner"`      | `"sonner"`    | Uses the built-in Sonner toast library                                                                              |
        | `settings.position`    | `ToastPosition` | `"top-right"` | Position where toasts appear: "top-left", "top-right", "bottom-left", "bottom-right", "top-center", "bottom-center" |
        | `settings.duration`    | `number`        | `4000`        | Duration in milliseconds before toast auto-dismisses (Sonner default)                                               |
        | `settings.maxToasts`   | `number`        | -             | Maximum number of toasts visible at once                                                                            |
        | `settings.dismissible` | `boolean`       | `true`        | Whether toasts can be manually dismissed by user interaction (Sonner default)                                       |
        | `settings.closeButton` | `boolean`       | `true`        | Whether to show an explicit close button on toasts                                                                  |

        ```tsx Sonner Provider Example theme={null}
        const toastSettings = {
          provider: 'sonner', // Optional, this is the default
          settings: {
            position: 'top-center',
            duration: 6000,
            maxToasts: 5,
            dismissible: true,
            closeButton: true
          }
        };
        ```
      </Tab>

      <Tab title="Custom Provider">
        | Property          | Type                         | Required | Description                           |
        | ----------------- | ---------------------------- | -------- | ------------------------------------- |
        | `provider`        | `"custom"`                   | Yes      | Uses your custom toast implementation |
        | `methods.success` | `(message: string) => void`  | No       | Custom success toast handler          |
        | `methods.error`   | `(message: string) => void`  | No       | Custom error toast handler            |
        | `methods.warning` | `(message: string) => void`  | No       | Custom warning toast handler          |
        | `methods.info`    | `(message: string) => void`  | No       | Custom info toast handler             |
        | `methods.dismiss` | `(toastId?: string) => void` | No       | Custom dismiss handler                |

        ```tsx Custom Provider Example theme={null}
        const toastSettings = {
          provider: 'custom',
          methods: {
            success: (message: string) => {
              // Your custom success toast implementation
              myToastLibrary.success(message);
            },
            error: (message: string) => {
              // Your custom error toast implementation
              myToastLibrary.error(message);
            },
            warning: (message: string) => {
              // Your custom warning toast implementation
              myToastLibrary.warning(message);
            },
            info: (message: string) => {
              // Your custom info toast implementation
              myToastLibrary.info(message);
            },
            dismiss: (toastId?: string) => {
              // Your custom dismiss implementation
              myToastLibrary.dismiss(toastId);
            }
          }
        };
        ```

        <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
          All custom methods are optional. Only implement the ones you need. Methods
          receive the message text only - your implementation handles styling,
          positioning, and timing.
        </Callout>
      </Tab>
    </Tabs>

    ***

    ## State and performance

    Fine-tune TanStack Query caching for every Auth0 component. Defaults keep data fresh for two minutes, garbage-collect after five minutes, and skip window-focus refetches.

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Default</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>enabled</code>
          </td>

          <td>
            <code>boolean</code>
          </td>

          <td>
            <code>true</code>
          </td>

          <td>
            Toggle caching altogether. When set to <code>false</code>, stale data is
            disabled and cached entries are cleared quickly.
          </td>
        </tr>

        <tr>
          <td>
            <code>staleTime</code>
          </td>

          <td>
            <code>number</code>
          </td>

          <td>
            <code>120000</code>
          </td>

          <td>
            Milliseconds before data becomes stale. Default is two minutes. Increase
            for dashboards, decrease for critical workflows.
          </td>
        </tr>

        <tr>
          <td>
            <code>gcTime</code>
          </td>

          <td>
            <code>number</code>
          </td>

          <td>
            <code>300000</code>
          </td>

          <td>
            Milliseconds before inactive queries are garbage-collected. Default is five minutes.
          </td>
        </tr>

        <tr>
          <td>
            <code>refetchOnWindowFocus</code>
          </td>

          <td>
            <code>boolean | "always"</code>
          </td>

          <td>
            <code>false</code>
          </td>

          <td>
            Controls whether queries refetch when the browser regains focus. Use{" "}
            <code>"always"</code> for strict freshness.
          </td>
        </tr>
      </tbody>
    </table>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      **Disable caching:** Pass `{ enabled: false }`. This automatically sets `staleTime` to 0 and shortens the garbage-collection window to five seconds so every render fetches fresh data.

      **Pro tip:** Keep caching enabled but shorten `staleTime` when integrating with admin panels that require near-real-time updates.
    </Callout>

    <Tabs>
      <Tab title="Tune TTL">
        ```tsx theme={null}
        <Auth0ComponentProvider
          domain="your-tenant.auth0.com"
          cacheConfig={{
            staleTime: 10 * 60 * 1000,
            gcTime: 15 * 60 * 1000,
            refetchOnWindowFocus: true,
          }}
        >
          <App />
        </Auth0ComponentProvider>
        ```
      </Tab>

      <Tab title="Disable Cache">
        ```tsx theme={null}
        <Auth0ComponentProvider
          domain="your-tenant.auth0.com"
          cacheConfig={{ enabled: false }}
        >
          <App />
        </Auth0ComponentProvider>
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Next.js">
    ```tsx layout.tsx theme={null}
    import { Auth0ComponentProvider } from "@auth0/universal-components-react/rwa";

    export default function RootLayout({ children }) {
      return (
        <html lang="en">
          <body>
            <Auth0ComponentProvider
              mode="proxy"
              domain="your-tenant.auth0.com"
              proxyConfig={{ baseUrl: "/api/auth" }}
            >
              {children}
            </Auth0ComponentProvider>
          </body>
        </html>
      );
    }
    ```

    ***

    ## Properties

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Required</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>domain</code></td>
          <td><code>string</code></td>
          <td>Yes</td>
          <td>Auth0 tenant domain (e.g., "your-tenant.auth0.com"). Required for proxy mode.</td>
        </tr>

        <tr>
          <td><code>mode</code></td>
          <td><code>'proxy'</code></td>
          <td>Yes</td>
          <td>For Next.js, always use <code>'proxy'</code> mode for server-side authentication.</td>
        </tr>

        <tr>
          <td><code>proxyConfig</code></td>
          <td>`{ baseUrl: string }`</td>
          <td>Yes</td>
          <td>Proxy configuration with base URL to your authentication proxy server.</td>
        </tr>

        <tr>
          <td><code>previewMode</code></td>
          <td><code>boolean</code></td>
          <td>No</td>
          <td>When <code>true</code>, skips API client initialization. Used for documentation previews and demos.</td>
        </tr>

        <tr>
          <td><code>i18n</code></td>
          <td><code>I18nOptions</code></td>
          <td>No</td>
          <td>Internationalization settings including currentLanguage and fallbackLanguage.</td>
        </tr>

        <tr>
          <td><code>themeSettings</code></td>
          <td><code>ThemeSettings</code></td>
          <td>No</td>
          <td>Theme configuration including mode (light/dark), theme variant (default/minimal/rounded), and CSS variables.</td>
        </tr>

        <tr>
          <td><code>toastSettings</code></td>
          <td><code>ToastSettings</code></td>
          <td>No</td>
          <td>Toast notification configuration including provider selection (sonner/custom), positioning, duration, and custom toast methods.</td>
        </tr>

        <tr>
          <td><code>cacheConfig</code></td>
          <td><code>QueryCacheConfig</code></td>
          <td>No</td>
          <td>Controls TanStack Query caching (two min stale / five min GC by default). Set <code>enabled: false</code> to force fresh data.</td>
        </tr>

        <tr>
          <td><code>loader</code></td>
          <td><code>React.ReactNode</code></td>
          <td>No</td>
          <td>Custom loading component to display during authentication initialization.</td>
        </tr>
      </tbody>
    </table>

    ***

    ## Configure proxy mode

    For Next.js applications, use proxy mode with server-side authentication:

    ```tsx layout.tsx theme={null}
    import { Auth0ComponentProvider } from "@auth0/universal-components-react/rwa";

    export default function RootLayout({ children }) {
      return (
        <html lang="en">
          <body>
            <Auth0ComponentProvider
              mode="proxy"
              domain="your-tenant.auth0.com"
              proxyConfig={{ baseUrl: "/api/auth" }}
            >
              {children}
            </Auth0ComponentProvider>
          </body>
        </html>
      );
    }
    ```

    ***

    ### Proxy mode properties

    Configuration for proxy mode authentication. Required when using Next.js.

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Required</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>baseUrl</code>
          </td>

          <td>
            <code>string</code>
          </td>

          <td>Yes</td>

          <td>
            URL to your authentication proxy server (e.g., "/api/auth"). API calls
            append to this base path.
          </td>
        </tr>
      </tbody>
    </table>

    ***

    ## User experience

    ***

    **i18n**

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Required</th>
          <th>Default</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>currentLanguage</code>
          </td>

          <td>
            <code>string</code>
          </td>

          <td>Yes</td>
          <td>-</td>
          <td>Current language code (e.g., "en", "es", "fr")</td>
        </tr>

        <tr>
          <td>
            <code>fallbackLanguage</code>
          </td>

          <td>
            <code>string</code>
          </td>

          <td>No</td>

          <td>
            <code>"en"</code>
          </td>

          <td>Fallback language code when translations are missing</td>
        </tr>
      </tbody>
    </table>

    ***

    **themeSettings**

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Default</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>mode</code>
          </td>

          <td>
            <code>"light" | "dark"</code>
          </td>

          <td>
            <code>"light"</code>
          </td>

          <td>Theme color mode</td>
        </tr>

        <tr>
          <td>
            <code>theme</code>
          </td>

          <td>
            <code>"default" | "minimal" | "rounded"</code>
          </td>

          <td>
            <code>"default"</code>
          </td>

          <td>Theme variant with different styling approaches</td>
        </tr>

        <tr>
          <td>
            <code>variables</code>
          </td>

          <td>
            <code>StylingVariables</code>
          </td>

          <td>
            <code>
              {}
            </code>
          </td>

          <td>CSS custom properties for common, light, and dark themes</td>
        </tr>
      </tbody>
    </table>

    <Accordion title="Available CSS Variables">
      **Common (applies to all themes):**

      **Typography:**

      * `--font-size-page-header`
      * `--font-size-page-description`
      * `--font-size-heading`
      * `--font-size-title`
      * `--font-size-subtitle`
      * `--font-size-body`
      * `--font-size-paragraph`
      * `--font-size-label`

      **Border Radius:**

      * `--radius-xs` through `--radius-9xl`

      **Light & Dark (theme-specific colors and shadows):**

      **Colors:**

      * `--background`, `--foreground`
      * `--card`, `--card-foreground`
      * `--primary`, `--primary-foreground`
      * `--secondary`, `--secondary-foreground`
      * `--accent`, `--accent-foreground`
      * `--muted`, `--muted-foreground`
      * `--destructive`, `--destructive-foreground`
      * `--popover`, `--popover-foreground`
      * `--input`, `--border`, `--ring`
      * `--color-page`
      * `--color-info`, `--color-info-foreground`
      * `--color-success`, `--color-success-foreground`
      * `--color-warning`, `--color-warning-foreground`
      * `--color-destructive-border`
      * `--color-popover-border`
      * `--color-input-foreground`
      * `--color-input-muted`

      **Shadows:**

      * `--shadow-bevel-*` (xs, sm, md, lg, xl, 2xl)
      * `--shadow-button-*` (resting, hover, focus)
      * `--shadow-button-destructive-*`
      * `--shadow-button-outlined-*`
      * `--shadow-input-*` (resting, hover, focus)
      * `--shadow-input-destructive-*`
      * `--shadow-checkbox-*` (resting, hover)
      * `--shadow-switch-*` (resting, hover, focus, thumb, thumb-dark)
    </Accordion>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      For detailed styling examples and customization patterns, read the [Customize
      Style and Themes with Universal
      Components](/docs/get-started/universal-components/universal-components-style).
    </Callout>

    ***

    **toastSettings**

    Toast settings support two provider types: **Sonner** (default) or **custom**. Each provider has its own configuration structure for better type safety.

    <Accordion title="Sonner Provider (Default)">
      | Property               | Type            | Default       | Description                                                                                                         |
      | ---------------------- | --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
      | `provider`             | `"sonner"`      | `"sonner"`    | Uses the built-in Sonner toast library                                                                              |
      | `settings.position`    | `ToastPosition` | `"top-right"` | Position where toasts appear: "top-left", "top-right", "bottom-left", "bottom-right", "top-center", "bottom-center" |
      | `settings.duration`    | `number`        | `4000`        | Duration in milliseconds before toast auto-dismisses (Sonner default)                                               |
      | `settings.maxToasts`   | `number`        | -             | Maximum number of toasts visible at once                                                                            |
      | `settings.dismissible` | `boolean`       | `true`        | Whether toasts can be manually dismissed by user interaction (Sonner default)                                       |
      | `settings.closeButton` | `boolean`       | `true`        | Whether to show an explicit close button on toasts                                                                  |

      ```tsx Sonner Provider Example theme={null}
      const toastSettings = {
        provider: 'sonner', // Optional, this is the default
        settings: {
          position: 'top-center',
          duration: 6000,
          maxToasts: 5,
          dismissible: true,
          closeButton: true
        }
      };
      ```
    </Accordion>

    <Accordion title="Custom Provider">
      | Property          | Type                         | Required | Description                           |
      | ----------------- | ---------------------------- | -------- | ------------------------------------- |
      | `provider`        | `"custom"`                   | Yes      | Uses your custom toast implementation |
      | `methods.success` | `(message: string) => void`  | No       | Custom success toast handler          |
      | `methods.error`   | `(message: string) => void`  | No       | Custom error toast handler            |
      | `methods.warning` | `(message: string) => void`  | No       | Custom warning toast handler          |
      | `methods.info`    | `(message: string) => void`  | No       | Custom info toast handler             |
      | `methods.dismiss` | `(toastId?: string) => void` | No       | Custom dismiss handler                |

      ```tsx Custom Provider Example theme={null}
      const toastSettings = {
        provider: 'custom',
        methods: {
          success: (message: string) => {
            // Your custom success toast implementation
            myToastLibrary.success(message);
          },
          error: (message: string) => {
            // Your custom error toast implementation
            myToastLibrary.error(message);
          },
          warning: (message: string) => {
            // Your custom warning toast implementation
            myToastLibrary.warning(message);
          },
          info: (message: string) => {
            // Your custom info toast implementation
            myToastLibrary.info(message);
          },
          dismiss: (toastId?: string) => {
            // Your custom dismiss implementation
            myToastLibrary.dismiss(toastId);
          }
        }
      };
      ```

      <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
        All custom methods are optional. Only implement the ones you need. Methods receive the message text only - your implementation handles styling, positioning, and timing.
      </Callout>
    </Accordion>

    ***

    ## State and performance

    Fine-tune TanStack Query caching for every Auth0 component. Defaults keep data fresh for two minutes, garbage-collect after five minutes, and skip window-focus refetches.

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Default</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>enabled</code>
          </td>

          <td>
            <code>boolean</code>
          </td>

          <td>
            <code>true</code>
          </td>

          <td>
            Toggle caching altogether. When set to <code>false</code>, stale data is
            disabled and cached entries are cleared quickly.
          </td>
        </tr>

        <tr>
          <td>
            <code>staleTime</code>
          </td>

          <td>
            <code>number</code>
          </td>

          <td>
            <code>120000</code>
          </td>

          <td>
            Milliseconds before data becomes stale (two minutes by default). Increase
            for dashboards, decrease for critical workflows.
          </td>
        </tr>

        <tr>
          <td>
            <code>gcTime</code>
          </td>

          <td>
            <code>number</code>
          </td>

          <td>
            <code>300000</code>
          </td>

          <td>
            Milliseconds before inactive queries are garbage-collected (five minutes by
            default).
          </td>
        </tr>

        <tr>
          <td>
            <code>refetchOnWindowFocus</code>
          </td>

          <td>
            <code>boolean | "always"</code>
          </td>

          <td>
            <code>false</code>
          </td>

          <td>
            Controls whether queries refetch when the browser regains focus. Use{" "}
            <code>"always"</code> for strict freshness.
          </td>
        </tr>
      </tbody>
    </table>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      **Disable caching:** Pass `{ enabled: false }`. This automatically sets `staleTime` to 0 and shortens the garbage-collection window to 5 seconds so every render fetches fresh data.

      **Pro tip:** Keep caching enabled but shorten `staleTime` when integrating with admin panels that require near-real-time updates.
    </Callout>

    <Accordion title="Tune TTL">
      ```tsx layout.tsx theme={null}
      <Auth0ComponentProvider
        mode="proxy"
        domain="your-tenant.auth0.com"
        proxyConfig={{ baseUrl: "/api/auth" }}
        cacheConfig={{
          staleTime: 10 * 60 * 1000,
          gcTime: 15 * 60 * 1000,
          refetchOnWindowFocus: true,
        }}
      >
        <App />
      </Auth0ComponentProvider>
      ```
    </Accordion>

    <Accordion title="Disable Cache">
      ```tsx layout.tsx theme={null}
      <Auth0ComponentProvider
        mode="proxy"
        domain="your-tenant.auth0.com"
        proxyConfig={{ baseUrl: "/api/auth" }}
        cacheConfig={{ enabled: false }}
      >
        <App />
      </Auth0ComponentProvider>
      ```
    </Accordion>
  </Tab>

  <Tab title="shadcn">
    ```tsx App.tsx theme={null}
    import { Auth0Provider } from "@auth0/auth0-react";
    import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";

    function App() {
      return (
        <Auth0Provider
          domain="your-tenant.auth0.com"
          clientId="YOUR_CLIENT_ID"
          authorizationParams={{ redirect_uri: window.location.origin }}
          interactiveErrorHandler='popup' // Required to handle step-up auth challenges via Universal Login popup
        >
          <Auth0ComponentProvider domain="your-tenant.auth0.com">
            {/* Your app with Auth0 Universal Components */}
          </Auth0ComponentProvider>
        </Auth0Provider>
      );
    }
    ```

    ***

    ## Properties

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Required</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>domain</code></td>
          <td><code>string</code></td>
          <td>Yes</td>
          <td>Auth0 tenant domain (e.g., "your-tenant.auth0.com").</td>
        </tr>

        <tr>
          <td><code>authContext</code></td>
          <td><code>ContextInterface</code></td>
          <td>No</td>
          <td>Custom authentication context for SPAs not using `@auth0/auth0-react`. Provides auth functions, such as`getAccessTokenSilently`.</td>
        </tr>

        <tr>
          <td><code>previewMode</code></td>
          <td><code>boolean</code></td>
          <td>No</td>
          <td>When <code>true</code>, skips API client initialization. Used for documentation previews and demos.</td>
        </tr>

        <tr>
          <td><code>i18n</code></td>
          <td><code>I18nOptions</code></td>
          <td>No</td>
          <td>Internationalization settings including currentLanguage and fallbackLanguage.</td>
        </tr>

        <tr>
          <td><code>themeSettings</code></td>
          <td><code>ThemeSettings</code></td>
          <td>No</td>
          <td>Theme configuration including mode (light/dark), theme variant (default/minimal/rounded), and CSS variables.</td>
        </tr>

        <tr>
          <td><code>toastSettings</code></td>
          <td><code>ToastSettings</code></td>
          <td>No</td>
          <td>Toast notification configuration including provider selection (sonner/custom), positioning, duration, and custom toast methods.</td>
        </tr>

        <tr>
          <td><code>cacheConfig</code></td>
          <td><code>QueryCacheConfig</code></td>
          <td>No</td>
          <td>Controls TanStack Query caching (two min stale / five min GC by default). Set <code>enabled: false</code> to force fresh data.</td>
        </tr>

        <tr>
          <td><code>loader</code></td>
          <td><code>React.ReactNode</code></td>
          <td>No</td>
          <td>Custom loading component to display during authentication initialization.</td>
        </tr>
      </tbody>
    </table>

    ***

    ## User experience

    ***

    **i18n**

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Required</th>
          <th>Default</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>currentLanguage</code>
          </td>

          <td>
            <code>string</code>
          </td>

          <td>Yes</td>
          <td>-</td>
          <td>Current language code (e.g., "en", "es", "fr")</td>
        </tr>

        <tr>
          <td>
            <code>fallbackLanguage</code>
          </td>

          <td>
            <code>string</code>
          </td>

          <td>No</td>

          <td>
            <code>"en"</code>
          </td>

          <td>Fallback language code when translations are missing</td>
        </tr>
      </tbody>
    </table>

    ***

    **themeSettings**

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Default</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>mode</code>
          </td>

          <td>
            <code>"light" | "dark"</code>
          </td>

          <td>
            <code>"light"</code>
          </td>

          <td>Theme color mode</td>
        </tr>

        <tr>
          <td>
            <code>theme</code>
          </td>

          <td>
            <code>"default" | "minimal" | "rounded"</code>
          </td>

          <td>
            <code>"default"</code>
          </td>

          <td>Theme variant with different styling approaches</td>
        </tr>

        <tr>
          <td>
            <code>variables</code>
          </td>

          <td>
            <code>StylingVariables</code>
          </td>

          <td>
            <code>
              {}
            </code>
          </td>

          <td>CSS custom properties for common, light, and dark themes</td>
        </tr>
      </tbody>
    </table>

    <Accordion title="Available CSS Variables">
      **Common (applies to all themes):**

      **Typography:**

      * `--font-size-page-header`
      * `--font-size-page-description`
      * `--font-size-heading`
      * `--font-size-title`
      * `--font-size-subtitle`
      * `--font-size-body`
      * `--font-size-paragraph`
      * `--font-size-label`

      **Border Radius:**

      * `--radius-xs` through `--radius-9xl`

      **Light & Dark (theme-specific colors and shadows):**

      **Colors:**

      * `--background`, `--foreground`
      * `--card`, `--card-foreground`
      * `--primary`, `--primary-foreground`
      * `--secondary`, `--secondary-foreground`
      * `--accent`, `--accent-foreground`
      * `--muted`, `--muted-foreground`
      * `--destructive`, `--destructive-foreground`
      * `--popover`, `--popover-foreground`
      * `--input`, `--border`, `--ring`
      * `--color-page`
      * `--color-info`, `--color-info-foreground`
      * `--color-success`, `--color-success-foreground`
      * `--color-warning`, `--color-warning-foreground`
      * `--color-destructive-border`
      * `--color-popover-border`
      * `--color-input-foreground`
      * `--color-input-muted`

      **Shadows:**

      * `--shadow-bevel-*` (xs, sm, md, lg, xl, 2xl)
      * `--shadow-button-*` (resting, hover, focus)
      * `--shadow-button-destructive-*`
      * `--shadow-button-outlined-*`
      * `--shadow-input-*` (resting, hover, focus)
      * `--shadow-input-destructive-*`
      * `--shadow-checkbox-*` (resting, hover)
      * `--shadow-switch-*` (resting, hover, focus, thumb, thumb-dark)
    </Accordion>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      For detailed styling examples and customization patterns, read the [Customize
      Style and Themes with Universal
      Components](/docs/get-started/universal-components/universal-components-style).
    </Callout>

    ***

    **toastSettings**

    Toast settings support two provider types: **Sonner** (default) or **custom**. Each provider has its own configuration structure for better type safety.

    <Tabs>
      <Tab title="Sonner Provider (Default)">
        | Property               | Type            | Default       | Description                                                                                                         |
        | ---------------------- | --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
        | `provider`             | `"sonner"`      | `"sonner"`    | Uses the built-in Sonner toast library                                                                              |
        | `settings.position`    | `ToastPosition` | `"top-right"` | Position where toasts appear: "top-left", "top-right", "bottom-left", "bottom-right", "top-center", "bottom-center" |
        | `settings.duration`    | `number`        | `4000`        | Duration in milliseconds before toast auto-dismisses (Sonner default)                                               |
        | `settings.maxToasts`   | `number`        | -             | Maximum number of toasts visible at once                                                                            |
        | `settings.dismissible` | `boolean`       | `true`        | Whether toasts can be manually dismissed by user interaction (Sonner default)                                       |
        | `settings.closeButton` | `boolean`       | `true`        | Whether to show an explicit close button on toasts                                                                  |

        ```tsx Sonner Provider Example theme={null}
        const toastSettings = {
          provider: 'sonner', // Optional, this is the default
          settings: {
            position: 'top-center',
            duration: 6000,
            maxToasts: 5,
            dismissible: true,
            closeButton: true
          }
        };
        ```
      </Tab>

      <Tab title="Custom Provider">
        | Property          | Type                         | Required | Description                           |
        | ----------------- | ---------------------------- | -------- | ------------------------------------- |
        | `provider`        | `"custom"`                   | Yes      | Uses your custom toast implementation |
        | `methods.success` | `(message: string) => void`  | No       | Custom success toast handler          |
        | `methods.error`   | `(message: string) => void`  | No       | Custom error toast handler            |
        | `methods.warning` | `(message: string) => void`  | No       | Custom warning toast handler          |
        | `methods.info`    | `(message: string) => void`  | No       | Custom info toast handler             |
        | `methods.dismiss` | `(toastId?: string) => void` | No       | Custom dismiss handler                |

        ```tsx Custom Provider Example theme={null}
        const toastSettings = {
          provider: 'custom',
          methods: {
            success: (message: string) => {
              // Your custom success toast implementation
              myToastLibrary.success(message);
            },
            error: (message: string) => {
              // Your custom error toast implementation
              myToastLibrary.error(message);
            },
            warning: (message: string) => {
              // Your custom warning toast implementation
              myToastLibrary.warning(message);
            },
            info: (message: string) => {
              // Your custom info toast implementation
              myToastLibrary.info(message);
            },
            dismiss: (toastId?: string) => {
              // Your custom dismiss implementation
              myToastLibrary.dismiss(toastId);
            }
          }
        };
        ```

        <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
          All custom methods are optional. Only implement the ones you need. Methods
          receive the message text only - your implementation handles styling,
          positioning, and timing.
        </Callout>
      </Tab>
    </Tabs>

    ***

    ## State and performance

    Fine-tune TanStack Query caching for every Auth0 component. Defaults keep data fresh for two minutes, garbage-collect after five minutes, and skip window-focus refetches.

    <table class="table">
      <thead>
        <tr>
          <th>Property</th>
          <th>Type</th>
          <th>Default</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>enabled</code>
          </td>

          <td>
            <code>boolean</code>
          </td>

          <td>
            <code>true</code>
          </td>

          <td>
            Toggle caching altogether. When set to <code>false</code>, stale data is
            disabled and cached entries are cleared quickly.
          </td>
        </tr>

        <tr>
          <td>
            <code>staleTime</code>
          </td>

          <td>
            <code>number</code>
          </td>

          <td>
            <code>120000</code>
          </td>

          <td>
            Milliseconds before data becomes stale (two minutes by default). Increase
            for dashboards, decrease for critical workflows.
          </td>
        </tr>

        <tr>
          <td>
            <code>gcTime</code>
          </td>

          <td>
            <code>number</code>
          </td>

          <td>
            <code>300000</code>
          </td>

          <td>
            Milliseconds before inactive queries are garbage-collected (5 minutes by
            default).
          </td>
        </tr>

        <tr>
          <td>
            <code>refetchOnWindowFocus</code>
          </td>

          <td>
            <code>boolean | "always"</code>
          </td>

          <td>
            <code>false</code>
          </td>

          <td>
            Controls whether queries refetch when the browser regains focus. Use{" "}
            <code>"always"</code> for strict freshness.
          </td>
        </tr>
      </tbody>
    </table>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      **Disable caching:** Pass `{ enabled: false }`. This automatically sets `staleTime` to 0 and shortens the garbage-collection window to 5 seconds so every render fetches fresh data.

      **Pro tip:** Keep caching enabled but shorten `staleTime` when integrating with admin panels that require near-real-time updates.
    </Callout>

    <Tabs>
      <Tab title="Tune TTL">
        ```tsx App.tsx theme={null}
        <Auth0ComponentProvider
          domain="your-tenant.auth0.com"
          cacheConfig={{
            staleTime: 10 * 60 * 1000,
            gcTime: 15 * 60 * 1000,
            refetchOnWindowFocus: true,
          }}
        >
          <App />
        </Auth0ComponentProvider>
        ```
      </Tab>

      <Tab title="Disable Cache">
        ```tsx App.tsx theme={null}
        <Auth0ComponentProvider
          domain="your-tenant.auth0.com"
          cacheConfig={{ enabled: false }}
        >
          <App />
        </Auth0ComponentProvider>
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>