Configure Auth0ComponentProvider

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

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

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

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)

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

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

Disable Cache

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

Next.js

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>

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

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 asgetAccessTokenSilently.
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)

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

App.tsx

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

Disable Cache

App.tsx

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