Configure Auth0ComponentProvider

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. To learn more, read Product Release Stages.

The Auth0ComponentProvider is the orchestration layer for Auth0 Universal Components. 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 and the 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`

React
Next.js
shadcn

App.tsx

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 }}
    >
      <Auth0ComponentProvider domain="your-tenant.auth0.com">
        {/* Your app with Auth0 Universal Components */}
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

Properties

Property	Type	Required	Description
`domain`	`string`	Yes	Auth0 tenant domain (“YOUR_AUTH0_TENANT.auth0.com”).
`previewMode`	`boolean`	No	When `true`, skips API client initialization. Used for documentation previews and demos.
`i18n`	`I18nOptions`	No	Internationalization settings including currentLanguage and fallbackLanguage.
`themeSettings`	`ThemeSettings`	No	Theme configuration including mode (light/dark), theme variant (default/minimal/rounded), and CSS variables.
`toastSettings`	`ToastSettings`	No	Toast notification configuration including provider selection (sonner/custom), positioning, duration, and custom toast methods.
`cacheConfig`	`QueryCacheConfig`	No	Controls TanStack Query caching (two min stale / five min GC by default). Set `enabled: false` to force fresh data.
`loader`	`React.ReactNode`	No	Custom loading component to display during authentication initialization.

User experience

i18n

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

Property	Type	Required	Default	Description
`currentLanguage`	`string`	Yes	-	Current language code (e.g., “en”, “es”, “fr”)
`fallbackLanguage`	`string`	No	`”en”`	Fallback language code when translations are missing

themeSettings

Property	Type	Default	Description
`mode`	`”light” \| “dark"`	`"light”`	Theme color mode
`theme`	`”default” \| “minimal” \| “rounded"`	`"default”`	Theme variant with different styling approaches
`variables`	`StylingVariables`	CSS custom properties for common, light, and dark themes

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)

For detailed styling examples and customization patterns, read the Customize Style and Themes with Universal Components.

toastSettings

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

Sonner Provider (Default)
Custom Provider

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

Sonner Provider Example

const toastSettings = {
  provider: 'sonner', // Optional, this is the default
  settings: {
    position: 'top-center',
    duration: 6000,
    maxToasts: 5,
    dismissible: true,
    closeButton: true
  }
};

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

Custom Provider Example

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);
    }
  }
};

All custom methods are optional. Only implement the ones you need. Methods receive the message text only - your implementation handles styling, positioning, and timing.

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.

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Toggle caching altogether. When set to `false`, stale data is disabled and cached entries are cleared quickly.
`staleTime`	`number`	`120000`	Milliseconds before data becomes stale. Default is two minutes. Increase for dashboards, decrease for critical workflows.
`gcTime`	`number`	`300000`	Milliseconds before inactive queries are garbage-collected. Default is five minutes.
`refetchOnWindowFocus`	`boolean \| “always”`	`false`	Controls whether queries refetch when the browser regains focus. Use `“always”` for strict freshness.

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.

Tune TTL
Disable Cache

<Auth0ComponentProvider
  domain="your-tenant.auth0.com"
  cacheConfig={{
    staleTime: 10 * 60 * 1000,
    gcTime: 15 * 60 * 1000,
    refetchOnWindowFocus: true,
  }}
>
  <App />
</Auth0ComponentProvider>

<Auth0ComponentProvider
  domain="your-tenant.auth0.com"
  cacheConfig={{ enabled: false }}
>
  <App />
</Auth0ComponentProvider>

layout.tsx

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

Property	Type	Required	Description
`domain`	`string`	Yes	Auth0 tenant domain (e.g., “your-tenant.auth0.com”). Required for proxy mode.
`mode`	`’proxy’`	Yes	For Next.js, always use `‘proxy’` mode for server-side authentication.
`proxyConfig`	`{ baseUrl: string }`	Yes	Proxy configuration with base URL to your authentication proxy server.
`previewMode`	`boolean`	No	When `true`, skips API client initialization. Used for documentation previews and demos.
`i18n`	`I18nOptions`	No	Internationalization settings including currentLanguage and fallbackLanguage.
`themeSettings`	`ThemeSettings`	No	Theme configuration including mode (light/dark), theme variant (default/minimal/rounded), and CSS variables.
`toastSettings`	`ToastSettings`	No	Toast notification configuration including provider selection (sonner/custom), positioning, duration, and custom toast methods.
`cacheConfig`	`QueryCacheConfig`	No	Controls TanStack Query caching (two min stale / five min GC by default). Set `enabled: false` to force fresh data.
`loader`	`React.ReactNode`	No	Custom loading component to display during authentication initialization.

Configure proxy mode

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

layout.tsx

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.

Property	Type	Required	Description
`baseUrl`	`string`	Yes	URL to your authentication proxy server (e.g., “/api/auth”). API calls append to this base path.

User experience

i18n

Property	Type	Required	Default	Description
`currentLanguage`	`string`	Yes	-	Current language code (e.g., “en”, “es”, “fr”)
`fallbackLanguage`	`string`	No	`”en”`	Fallback language code when translations are missing

themeSettings

Property	Type	Default	Description
`mode`	`”light” \| “dark"`	`"light”`	Theme color mode
`theme`	`”default” \| “minimal” \| “rounded"`	`"default”`	Theme variant with different styling approaches
`variables`	`StylingVariables`	CSS custom properties for common, light, and dark themes

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)

For detailed styling examples and customization patterns, read the Customize Style and Themes with Universal Components.

toastSettings

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

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

Sonner Provider Example

const toastSettings = {
  provider: 'sonner', // Optional, this is the default
  settings: {
    position: 'top-center',
    duration: 6000,
    maxToasts: 5,
    dismissible: true,
    closeButton: true
  }
};

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

Custom Provider Example

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);
    }
  }
};

All custom methods are optional. Only implement the ones you need. Methods receive the message text only - your implementation handles styling, positioning, and timing.

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.

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Toggle caching altogether. When set to `false`, stale data is disabled and cached entries are cleared quickly.
`staleTime`	`number`	`120000`	Milliseconds before data becomes stale (two minutes by default). Increase for dashboards, decrease for critical workflows.
`gcTime`	`number`	`300000`	Milliseconds before inactive queries are garbage-collected (five minutes by default).
`refetchOnWindowFocus`	`boolean \| “always”`	`false`	Controls whether queries refetch when the browser regains focus. Use `“always”` for strict freshness.

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.

Tune TTL

layout.tsx

<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>

Disable Cache

layout.tsx

<Auth0ComponentProvider
  mode="proxy"
  domain="your-tenant.auth0.com"
  proxyConfig={{ baseUrl: "/api/auth" }}
  cacheConfig={{ enabled: false }}
>
  <App />
</Auth0ComponentProvider>

App.tsx

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 }}
    >
      <Auth0ComponentProvider domain="your-tenant.auth0.com">
        {/* Your app with Auth0 Universal Components */}
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

Properties

Property	Type	Required	Description
`domain`	`string`	Yes	Auth0 tenant domain (e.g., “your-tenant.auth0.com”).
`authContext`	`ContextInterface`	No	Custom authentication context for SPAs not using `@auth0/auth0-react`. Provides auth functions, such as`getAccessTokenSilently`.
`previewMode`	`boolean`	No	When `true`, skips API client initialization. Used for documentation previews and demos.
`i18n`	`I18nOptions`	No	Internationalization settings including currentLanguage and fallbackLanguage.
`themeSettings`	`ThemeSettings`	No	Theme configuration including mode (light/dark), theme variant (default/minimal/rounded), and CSS variables.
`toastSettings`	`ToastSettings`	No	Toast notification configuration including provider selection (sonner/custom), positioning, duration, and custom toast methods.
`cacheConfig`	`QueryCacheConfig`	No	Controls TanStack Query caching (two min stale / five min GC by default). Set `enabled: false` to force fresh data.
`loader`	`React.ReactNode`	No	Custom loading component to display during authentication initialization.

User experience

i18n

Property	Type	Required	Default	Description
`currentLanguage`	`string`	Yes	-	Current language code (e.g., “en”, “es”, “fr”)
`fallbackLanguage`	`string`	No	`”en”`	Fallback language code when translations are missing

themeSettings

Property	Type	Default	Description
`mode`	`”light” \| “dark"`	`"light”`	Theme color mode
`theme`	`”default” \| “minimal” \| “rounded"`	`"default”`	Theme variant with different styling approaches
`variables`	`StylingVariables`	CSS custom properties for common, light, and dark themes

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)

For detailed styling examples and customization patterns, read the Customize Style and Themes with Universal Components.

toastSettings

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

Sonner Provider (Default)
Custom Provider

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

Sonner Provider Example

const toastSettings = {
  provider: 'sonner', // Optional, this is the default
  settings: {
    position: 'top-center',
    duration: 6000,
    maxToasts: 5,
    dismissible: true,
    closeButton: true
  }
};

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

Custom Provider Example

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);
    }
  }
};

All custom methods are optional. Only implement the ones you need. Methods receive the message text only - your implementation handles styling, positioning, and timing.

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.

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Toggle caching altogether. When set to `false`, stale data is disabled and cached entries are cleared quickly.
`staleTime`	`number`	`120000`	Milliseconds before data becomes stale (two minutes by default). Increase for dashboards, decrease for critical workflows.
`gcTime`	`number`	`300000`	Milliseconds before inactive queries are garbage-collected (5 minutes by default).
`refetchOnWindowFocus`	`boolean \| “always”`	`false`	Controls whether queries refetch when the browser regains focus. Use `“always”` for strict freshness.

Tune TTL
Disable Cache

App.tsx

<Auth0ComponentProvider
  domain="your-tenant.auth0.com"
  cacheConfig={{
    staleTime: 10 * 60 * 1000,
    gcTime: 15 * 60 * 1000,
    refetchOnWindowFocus: true,
  }}
>
  <App />
</Auth0ComponentProvider>

App.tsx

<Auth0ComponentProvider
  domain="your-tenant.auth0.com"
  cacheConfig={{ enabled: false }}
>
  <App />
</Auth0ComponentProvider>

Auth0 Onboarding

Learn the Basics

Configure Auth0

Plan and Design

Auth0 AI

Universal Components

Configure Auth0ComponentProvider

Benefits

Integration architecture

Configure `Auth0ComponentProvider`

Properties

User experience

i18n

themeSettings

toastSettings

State and performance

Properties

Configure proxy mode

Proxy mode properties

User experience

i18n

themeSettings

toastSettings

State and performance

Properties

User experience

i18n

themeSettings

toastSettings

State and performance

Auth0 Onboarding

Learn the Basics

Configure Auth0

Plan and Design

Auth0 AI

Universal Components

​Benefits

​Integration architecture

​Configure Auth0ComponentProvider

​Properties

​User experience

​i18n

​themeSettings

​toastSettings

​State and performance

​Properties

​Configure proxy mode

​Proxy mode properties

​User experience

​i18n

​themeSettings

​toastSettings

​State and performance

​Properties

​User experience

​i18n

​themeSettings

​toastSettings

​State and performance

Benefits

Integration architecture

Configure `Auth0ComponentProvider`

Properties

User experience

i18n

themeSettings

toastSettings

State and performance

Properties

Configure proxy mode

Proxy mode properties

User experience

i18n

themeSettings

toastSettings

State and performance

Properties

User experience

i18n

themeSettings

toastSettings

State and performance