Customize Style and Themes with Auth0 Universal Components

Customize Auth0 Universal Components using CSS variables, Tailwind v4, and built-in theme presets.

Auth0 Universal Components are built on a design system backed by Tailwind CSS and Radix UI primitives. You apply brand customization by setting CSS custom properties that the components read directly.

Choose your CSS setup below.

Plain CSS

Setup

Import the pre-compiled stylesheet in your app entry point:

import "@auth0/universal-components-react/styles";

Then override tokens in your CSS:

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

All component colors cascade from these two tokens. Add more from the CSS variables reference as needed.

In plain CSS mode, setting --primary or --color-primary has no effect. The compiled stylesheet reads --auth0-* variables directly.

---

Theme presets

Pass themeSettings to Auth0ComponentProvider to switch between built-in visual variants.

<Auth0ComponentProvider
  themeSettings={{
    mode: "light", // 'light' | 'dark'
    theme: "default", // 'default' | 'minimal' | 'rounded'
  }}
>
  <App />
</Auth0ComponentProvider>

Preset	Description
default	Standard Auth0 look with balanced shadows and borders
minimal	Reduced visual weight — fewer shadows, lighter borders
rounded	Increased border radii for a softer appearance

Shadow variables only take effect with the default preset. The minimal and rounded presets disable shadows internally.

---

CSS variables reference

All visual properties are driven by CSS custom properties. Override them in your stylesheet (as shown in Setup above) or via the themeSettings.variables prop.

Set these in :root for light mode defaults. Use .dark or themeSettings.mode for dark mode values.

Colors

:root {
  /* Brand */
  --auth0-primary: oklch(37% 0 0);              /* buttons, links, active states */
  --auth0-primary-foreground: oklch(100% 0 0);  /* text on primary surfaces */

  /* Surfaces */
  --auth0-background: oklch(100% 0 0);          /* page background */
  --auth0-foreground: oklch(9% 0 0);            /* default text */
  --auth0-card: oklch(100% 0 0);                /* card background */
  --auth0-card-foreground: oklch(0% 0 0);       /* text inside cards */
  --auth0-popover: oklch(100% 0 0);             /* dropdown/dialog background */
  --auth0-popover-foreground: oklch(9% 0 0);    /* text inside popovers */
  --auth0-input: oklch(100% 0 0);               /* input field background */

  /* Secondary & muted */
  --auth0-secondary: oklch(96% 0 0);
  --auth0-secondary-foreground: oklch(100% 0 0);
  --auth0-muted: oklch(96% 0 0);                /* disabled/subtle backgrounds */
  --auth0-muted-foreground: oklch(45% 0 0);     /* placeholder text */

  /* Accent & destructive */
  --auth0-accent: oklch(97% 0 0);               /* hover highlights */
  --auth0-accent-foreground: oklch(9% 0 0);
  --auth0-destructive: oklch(93% 0.03 17);      /* error states */
  --auth0-destructive-foreground: oklch(36% 0.14 17);

  /* Borders */
  --auth0-border: oklch(89% 0 0);
  --auth0-ring: oklch(89% 0 0);                 /* focus ring */
}

Status Colors

Status color tokens use no prefix and are set independently from the --auth0-* color set.

Token	Controls
--color-page	Page-level background (outermost container)
--color-info	Info alert background
--color-info-foreground	Info alert text and icon
--color-success	Success alert background
--color-success-foreground	Success alert text and icon
--color-warning	Warning alert background
--color-warning-foreground	Warning alert text and icon
--color-destructive-border	Destructive input/button border
--color-popover-border	Popover/dropdown border
--color-input-foreground	Input text color
--color-input-muted	Muted input variant background

Override them in :root or via themeSettings.variables.light / .dark:

:root {
  --color-success: oklch(94% 0.05 145);
  --color-success-foreground: oklch(30% 0.1 145);
}

Border Radius

:root {
  /* Most commonly adjusted */
  --radius-sm:  4px;   /* tags, chips */
  --radius-md:  6px;   /* small elements */
  --radius-lg:  10px;  /* buttons, inputs */
  --radius-xl:  12px;  /* cards */
  --radius-2xl: 16px;  /* modals, large panels */

  /* Fine-grained */
  --radius-xs:  2px;
  --radius-3xl: 20px;
  --radius-4xl: 24px;
  --radius-5xl: 32px;
  --radius-6xl: 40px;
  --radius-7xl: 48px;
  --radius-8xl: 56px;
  --radius-9xl: 64px;
}

Typography

:root {
  --font-size-page-header:      2.25rem;   /* 36px — main page title */
  --font-size-heading:          1.5rem;    /* 24px — section headings */
  --font-size-title:            1.25rem;   /* 20px — card titles */
  --font-size-subtitle:         1.125rem;  /* 18px — secondary headings */
  --font-size-body:             1rem;      /* 16px — body text */
  --font-size-paragraph:        0.875rem;  /* 14px — descriptions */
  --font-size-label:            0.875rem;  /* 14px — form labels */
  --font-size-page-description: 0.875rem;  /* 14px — page subtitles */
}

---

Override via JS API

Pass themeSettings.variables to Auth0ComponentProvider for programmatic overrides. These take the highest specificity and override both :root CSS and any stylesheet values.

Variables are organized into three buckets:

• common — applied regardless of mode (radius, typography)
• light — applied when mode: "light"
• dark — applied when mode: "dark"

<Auth0ComponentProvider
  themeSettings={{
    mode: "light",
    variables: {
      common: {
        "--radius-lg": "12px",
        "--font-size-body": "0.875rem",
      },
      light: {
        "--auth0-primary": "#4f46e5",
        "--auth0-primary-foreground": "#ffffff",
        "--auth0-background": "#fafafa",
      },
      dark: {
        "--auth0-primary": "#818cf8",
        "--auth0-background": "#121212",
      },
    },
  }}
>
  <App />
</Auth0ComponentProvider>

themeSettings.variables always uses --auth0-* names for color tokens, regardless of your CSS setup. Border radius and typography tokens use their own names (--radius-*, --font-size-*).

---

Override per component

Every component accepts a styling prop to scope overrides without affecting global styles.

<SsoProviderTable
  styling={{
    variables: {
      common: {
        "--radius-lg": "16px",
      },
      light: {
        "--auth0-primary": "#059669",
        "--auth0-card": "#f8fafc",
      },
      dark: {
        "--auth0-primary": "#34d399",
        "--auth0-card": "#1e293b",
      },
    },
    classes: {
      "SsoProviderTable-header": "shadow-lg",
      "SsoProviderTable-table": "rounded-xl",
    },
  }}
/>

Use variables for CSS token overrides scoped to this component, and classes for Tailwind or custom classes applied to specific component parts.

Available class targets by component

SsoProviderCreate

• SsoProviderCreate-header, SsoProviderCreate-wizard
• ProviderSelect-root, ProviderDetails-root, ProviderConfigure-root

SsoProviderTable

• SsoProviderTable-header, SsoProviderTable-table, SsoProviderTable-row

SsoProviderEdit

• SsoProviderEdit-header, SsoProviderEdit-tabs
• SsoProviderEdit-ssoTab, SsoProviderEdit-provisioningTab, SsoProviderEdit-domainsTab

DomainTable

• DomainTable-header, DomainTable-table
• DomainTable-createModal, DomainTable-configureModal, DomainTable-deleteModal

OrganizationDetailsEdit

• OrganizationDetailsEdit-header, OrganizationDetailsEdit-form, OrganizationDetailsEdit-actions

---

Common customizations

Brand color

:root {
  --auth0-primary: #4f46e5;
  --auth0-primary-foreground: #ffffff;
}

Soft corners

:root {
  --radius-lg: 16px;  /* buttons, inputs */
  --radius-xl: 20px;  /* cards */
  --radius-2xl: 24px; /* modals */
}

Compact typography

:root {
  --font-size-page-header: 1.75rem;
  --font-size-heading: 1.25rem;
  --font-size-title: 1rem;
  --font-size-body: 0.875rem;
}

---

Dark mode

Components respond to themeSettings.mode. Wire it to your app’s theme state:

function App() {
  const [isDark, setIsDark] = useState(false);

  return (
    <Auth0ComponentProvider
      themeSettings={{ mode: isDark ? "dark" : "light" }}
    >
      <YourApp />
    </Auth0ComponentProvider>
  );
}

Or sync with system preference:

const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;

<Auth0ComponentProvider
  themeSettings={{ mode: prefersDark ? "dark" : "light" }}
>

For Next.js with server-side rendering, read the preferred mode from a cookie to avoid a flash on load:

layout.tsx

export default async function RootLayout({ children }) {
  const cookieStore = await cookies();
  const mode = cookieStore.get("theme-mode")?.value === "dark" ? "dark" : "light";

  return (
    <html lang="en">
      <body>
        <Auth0ComponentProvider
          mode="proxy"
          domain={process.env.NEXT_PUBLIC_AUTH0_DOMAIN}
          proxyConfig={{ baseUrl: "/api/auth" }}
          themeSettings={{ mode }}
        >
          {children}
        </Auth0ComponentProvider>
      </body>
    </html>
  );
}

Tailwind v4

Setup

Import both Tailwind and the component stylesheet:

@import 'tailwindcss';
@import '@auth0/universal-components-react/tailwind';

Define your design tokens and expose them to Tailwind utilities with @theme inline:

@theme inline {
  --color-primary: var(--color-primary);
  --color-primary-foreground: var(--color-primary-foreground);
  /* add other tokens you use in Tailwind utilities */
}

:root {
  --color-primary: #4f46e5;
  --color-primary-foreground: #ffffff;
}

Next.js: Same pattern — put your @import lines and @theme block in globals.css, then split color overrides into separate light.css and dark.css files imported from globals.css. Import globals.css in your root layout.tsx.

---

Theme presets

Pass themeSettings to Auth0ComponentProvider to switch between built-in visual variants.

<Auth0ComponentProvider
  themeSettings={{
    mode: "light", // 'light' | 'dark'
    theme: "default", // 'default' | 'minimal' | 'rounded'
  }}
>
  <App />
</Auth0ComponentProvider>

Preset	Description
default	Standard Auth0 look with balanced shadows and borders
minimal	Reduced visual weight — fewer shadows, lighter borders
rounded	Increased border radii for a softer appearance

Shadow variables only take effect with the default preset. The minimal and rounded presets disable shadows internally.

---

CSS variables reference

All visual properties are driven by CSS custom properties. Override them in your stylesheet (as shown in Setup above) or via the themeSettings.variables prop.

Set these in :root for light mode defaults. Use .dark or themeSettings.mode for dark mode values.

Colors

:root {
  /* Brand */
  --color-primary: oklch(37% 0 0);              /* buttons, links, active states */
  --color-primary-foreground: oklch(100% 0 0);  /* text on primary surfaces */

  /* Surfaces */
  --color-background: oklch(100% 0 0);          /* page background */
  --color-foreground: oklch(9% 0 0);            /* default text */
  --color-card: oklch(100% 0 0);                /* card background */
  --color-card-foreground: oklch(0% 0 0);       /* text inside cards */
  --color-popover: oklch(100% 0 0);             /* dropdown/dialog background */
  --color-popover-foreground: oklch(9% 0 0);    /* text inside popovers */
  --color-input: oklch(100% 0 0);               /* input field background */

  /* Secondary & muted */
  --color-secondary: oklch(96% 0 0);
  --color-secondary-foreground: oklch(100% 0 0);
  --color-muted: oklch(96% 0 0);                /* disabled/subtle backgrounds */
  --color-muted-foreground: oklch(45% 0 0);     /* placeholder text */

  /* Accent & destructive */
  --color-accent: oklch(97% 0 0);               /* hover highlights */
  --color-accent-foreground: oklch(9% 0 0);
  --color-destructive: oklch(93% 0.03 17);      /* error states */
  --color-destructive-foreground: oklch(36% 0.14 17);

  /* Borders */
  --color-border: oklch(89% 0 0);
  --color-ring: oklch(89% 0 0);                 /* focus ring */
}

Status Colors

Status color tokens share the same --color-* naming as the brand tokens above.

Token	Controls
--color-page	Page-level background (outermost container)
--color-info	Info alert background
--color-info-foreground	Info alert text and icon
--color-success	Success alert background
--color-success-foreground	Success alert text and icon
--color-warning	Warning alert background
--color-warning-foreground	Warning alert text and icon
--color-destructive-border	Destructive input/button border
--color-popover-border	Popover/dropdown border
--color-input-foreground	Input text color
--color-input-muted	Muted input variant background

Override them in :root or via themeSettings.variables.light / .dark:

:root {
  --color-success: oklch(94% 0.05 145);
  --color-success-foreground: oklch(30% 0.1 145);
}

Border Radius

:root {
  /* Most commonly adjusted */
  --radius-sm:  4px;   /* tags, chips */
  --radius-md:  6px;   /* small elements */
  --radius-lg:  10px;  /* buttons, inputs */
  --radius-xl:  12px;  /* cards */
  --radius-2xl: 16px;  /* modals, large panels */

  /* Fine-grained */
  --radius-xs:  2px;
  --radius-3xl: 20px;
  --radius-4xl: 24px;
  --radius-5xl: 32px;
  --radius-6xl: 40px;
  --radius-7xl: 48px;
  --radius-8xl: 56px;
  --radius-9xl: 64px;
}

Typography

:root {
  --font-size-page-header:      2.25rem;   /* 36px — main page title */
  --font-size-heading:          1.5rem;    /* 24px — section headings */
  --font-size-title:            1.25rem;   /* 20px — card titles */
  --font-size-subtitle:         1.125rem;  /* 18px — secondary headings */
  --font-size-body:             1rem;      /* 16px — body text */
  --font-size-paragraph:        0.875rem;  /* 14px — descriptions */
  --font-size-label:            0.875rem;  /* 14px — form labels */
  --font-size-page-description: 0.875rem;  /* 14px — page subtitles */
}

---

Override via JS API

Pass themeSettings.variables to Auth0ComponentProvider for programmatic overrides. These take the highest specificity and override both :root CSS and any stylesheet values.

Variables are organized into three buckets:

• common — applied regardless of mode (radius, typography)
• light — applied when mode: "light"
• dark — applied when mode: "dark"

<Auth0ComponentProvider
  themeSettings={{
    mode: "light",
    variables: {
      common: {
        "--radius-lg": "12px",
        "--font-size-body": "0.875rem",
      },
    },
  }}
>
  <App />
</Auth0ComponentProvider>

---

Override per component

Every component accepts a styling prop to scope overrides without affecting global styles.

<SsoProviderTable
  styling={{
    variables: {
      common: {
        "--radius-lg": "16px",
      },
    },
    classes: {
      "SsoProviderTable-header": "shadow-lg",
      "SsoProviderTable-table": "rounded-xl",
    },
  }}
/>

Use variables for CSS token overrides scoped to this component, and classes for Tailwind or custom classes applied to specific component parts.

Available class targets by component

SsoProviderCreate

• SsoProviderCreate-header, SsoProviderCreate-wizard
• ProviderSelect-root, ProviderDetails-root, ProviderConfigure-root

SsoProviderTable

• SsoProviderTable-header, SsoProviderTable-table, SsoProviderTable-row

SsoProviderEdit

• SsoProviderEdit-header, SsoProviderEdit-tabs
• SsoProviderEdit-ssoTab, SsoProviderEdit-provisioningTab, SsoProviderEdit-domainsTab

DomainTable

• DomainTable-header, DomainTable-table
• DomainTable-createModal, DomainTable-configureModal, DomainTable-deleteModal

OrganizationDetailsEdit

• OrganizationDetailsEdit-header, OrganizationDetailsEdit-form, OrganizationDetailsEdit-actions

---

Common customizations

Brand color

:root {
  --color-primary: #4f46e5;
  --color-primary-foreground: #ffffff;
}

Soft corners

:root {
  --radius-lg: 16px;  /* buttons, inputs */
  --radius-xl: 20px;  /* cards */
  --radius-2xl: 24px; /* modals */
}

Compact typography

:root {
  --font-size-page-header: 1.75rem;
  --font-size-heading: 1.25rem;
  --font-size-title: 1rem;
  --font-size-body: 0.875rem;
}

---

Dark mode

Components respond to themeSettings.mode. Wire it to your app’s theme state:

function App() {
  const [isDark, setIsDark] = useState(false);

  return (
    <Auth0ComponentProvider
      themeSettings={{ mode: isDark ? "dark" : "light" }}
    >
      <YourApp />
    </Auth0ComponentProvider>
  );
}

Or sync with system preference:

const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;

<Auth0ComponentProvider
  themeSettings={{ mode: prefersDark ? "dark" : "light" }}
>

For Next.js with server-side rendering, read the preferred mode from a cookie to avoid a flash on load:

layout.tsx

export default async function RootLayout({ children }) {
  const cookieStore = await cookies();
  const mode = cookieStore.get("theme-mode")?.value === "dark" ? "dark" : "light";

  return (
    <html lang="en">
      <body>
        <Auth0ComponentProvider
          mode="proxy"
          domain={process.env.NEXT_PUBLIC_AUTH0_DOMAIN}
          proxyConfig={{ baseUrl: "/api/auth" }}
          themeSettings={{ mode }}
        >
          {children}
        </Auth0ComponentProvider>
      </body>
    </html>
  );
}