Auth0 Universal Components

Early Access: This feature is currently in Early Access. By using it, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. Learn about release stages →

What’s Included

My Organization Components

Organization management and administration components for SSO provider configuration, domain verification, and organization settings.

Prerequisites

Auth0 Account: Sign up at auth0.com - React 16.11+: This package supports React 16.11.0 and above, including React 17, 18, and 19 - Tailwind CSS 3+: Follow the Tailwind CSS installation guide

Installation

npm install @auth0/universal-components-react react-hook-form @auth0/auth0-react

npm/pnpm: Installs the package with required peer dependencies (react-hook-form and @auth0/auth0-react).shadcn: Installs component source code and @auth0/universal-components-core dependency for shared utilities and Auth0 integration.

Quick Start

1. Wrap Your App with Auth0Provider and Auth0ComponentProvider

App.tsx

import { Auth0Provider } from "@auth0/auth0-react";
import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
import "@auth0/universal-components-react/styles";

const authDetails = {
  domain: import.meta.env.VITE_AUTH0_DOMAIN,
};

function App() {
  return (
    <Auth0Provider
      domain={authDetails.domain}
      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
      authorizationParams={{
        redirect_uri: window.location.origin,
      }}
    >
      <Auth0ComponentProvider authDetails={authDetails}>
        {/* Your app components */}
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

2. Use an Auth0 Universal Component

Components require Auth0 tenant configuration. Check each component’s page for setup requirements.

OrganizationManagementPage.tsx

import { useAuth0 } from "@auth0/auth0-react";
import { OrganizationDetailsEdit } from "@auth0/universal-components-react/spa";

function OrganizationManagementPage() {
  const { isAuthenticated, isLoading } = useAuth0();

  if (isLoading) return <div>Loading...</div>;
  if (!isAuthenticated) return <div>Please log in</div>;

  return (
    <div>
      <OrganizationDetailsEdit />
    </div>
  );
}

Styling

The stylesheet import in the Quick Start (@auth0/universal-components-react/styles) enables all component styles.

Tailwind v4 users: Add @import "@auth0/universal-components-react/tailwind" to your CSS file instead.shadcn users: No import needed, styles are already in your Tailwind build.

Customize with CSS variables to match your brand:

:root {
  --primary: #4f46e5; /* your brand color */
  --primary-foreground: #ffffff; /* text on buttons */
}

Styling & Theming Guide

Theme presets, dark mode, CSS variables reference, and per-component styling options.

Example Implementations

See complete working examples in the sample applications.

View on GitHub

Explore React SPA (npm), React SPA (shadcn), and Next.js sample applications with full implementation patterns.

Auth0ComponentProvider Configuration

The Auth0ComponentProvider accepts the following properties to configure the behavior and appearance of Auth0 UI Components:

Property	Type	Required	Description
`authDetails`	`AuthDetails`	Yes	Authentication configuration including optional domain and optional authProxyUrl
`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 (2 min stale / 5 min GC by default). Set `enabled: false` to force fresh data.
`loader`	`React.ReactNode`	No	Custom loading component to display during authentication initialization

authDetails

Property	Type	Required	Description
`domain`	`string`	No	Your Auth0 domain (e.g., “your-tenant.auth0.com”)
`authProxyUrl`	`string`	Conditional	URL to your authentication proxy server for server-side authentication. Required for RWA/Next.js mode (enables Proxy Mode).
`contextInterface`	`BasicAuth0ContextInterface`	No	Custom authentication context interface for frameworks other than @auth0/auth0-react. Provides authentication functions (getAccessTokenSilently, loginWithRedirect, etc.) when not using the Auth0 React SDK

i18n

Property	Type	Default	Description
`currentLanguage`	`string`	`"en"`	Current language code (e.g., “en”, “es”, “fr”)
`fallbackLanguage`	`string`	`"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`	`ThemeVariables`	`{}`	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)

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
`settings.maxToasts`	`number`	`3`	Maximum number of toasts visible at once
`settings.dismissible`	`boolean`	`true`	Whether toasts can be manually dismissed by user interaction
`settings.closeButton`	`boolean`	`true`	Whether to show an explicit close button on toasts for better UX

Sonner Provider Example

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

Property	Type	Required	Description
`provider`	`"custom"`	Yes	Uses your custom toast implementation
`methods`	`CustomToastMethods`	Yes	Custom toast methods for success, error, warning, info, and dismiss actions

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

Custom methods only receive the message text. Your custom implementation handles all styling, positioning, and timing.

cacheConfig

Fine-tune TanStack Query caching for every Auth0 component. Defaults keep data fresh for 2 minutes, garbage-collect after 5 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 (2 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
Disable Cache

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

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

My Organization

​What’s Included

My Organization Components

​Prerequisites

​Installation

​Quick Start

​1. Wrap Your App with Auth0Provider and Auth0ComponentProvider

​2. Use an Auth0 Universal Component

​Styling

Styling & Theming Guide

​Example Implementations

View on GitHub

​Auth0ComponentProvider Configuration

​authDetails

​i18n

​themeSettings

​toastSettings

​cacheConfig

What’s Included

Prerequisites

Installation

Quick Start

1. Wrap Your App with Auth0Provider and Auth0ComponentProvider

2. Use an Auth0 Universal Component

Styling

Example Implementations

Auth0ComponentProvider Configuration

authDetails

i18n

themeSettings

toastSettings

cacheConfig