feat(core, react): css scoping#80
Conversation
🚀 Preview deploymentBranch: 📝 Preview URL: https://auth0-universal-components-f36rltp7y-okta.vercel.app Updated at 2026-03-05T07:16:14.646Z |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #80 +/- ##
==========================================
+ Coverage 88.17% 88.18% +0.01%
==========================================
Files 143 144 +1
Lines 12497 12513 +16
Branches 1670 1320 -350
==========================================
+ Hits 11019 11035 +16
Misses 1478 1478 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
chakrihacker
requested review from
NaveenChand755,
grandmaester,
harishsundar-okta and
rax7389
| '@tailwindcss/postcss': {}, | ||
| ...(isScoped && { | ||
| 'postcss-prefix-selector': { | ||
| prefix: '.auth0', |
There was a problem hiding this comment.
please cross check with suraj once, regarding the prefix, he had some suggestion
There was a problem hiding this comment.
@SurajThotakura please provide your inputs here
There was a problem hiding this comment.
The name auth0 is too generic and there is a chance that the customers might have a class with the same name. Let's update this to .auth0-uic or .auth0-root whichever makes more sense. @rax7389 please suggest the name.
There was a problem hiding this comment.
@SurajThotakura @chakrihacker .auth0-universal?
There was a problem hiding this comment.
.auth0-universal is good
There was a problem hiding this comment.
i think it should be
// Before: keeps :root (leaks)
return ${selector}, ${prefix}${selector.replace(':root', '')};
// After: replaces :root (scoped)
if (selector === ':root') return prefix;
if (selector.match(/^:root/)) return `${prefix}${selector.replace(':root', '')}`;
if (selector.match(/^\.dark/)) return `${prefix}${selector}`;
| import CodeBlock from '../components/CodeBlock'; | ||
| import TabbedCodeBlock from '../components/TabbedCodeBlock'; | ||
|
|
||
| export default function Styling() { |
There was a problem hiding this comment.
Please have this confirmed form suraj or jcobo, if we need a separate page for this or we are good to have it in Getting Started
There was a problem hiding this comment.
Let's keep styling in it's dedicated page. This is inline with what other UI Libraries do, shadcn has "Theming" and Clerk has "Appearance".
Minor enhancement:
We should add a "Styling" section in the getting started page where we describe how we can customize our components and link to the Styling page.
## Styling
Auth0 components come with pre-built styles — no CSS configuration required. Choose the stylesheet that fits your setup, and customize with CSS variables to match your brand.
<CardGroup cols={2}>
<Card title="Standalone Apps" icon="box">
Import `styles.css` for a self-contained stylesheet with all Tailwind utilities pre-compiled and scoped. No Tailwind setup
required.
```tsx
import '@auth0/universal-components-react/styles';
```
</Card>
<Card title="Tailwind Apps" icon="wind">
Import `tailwind.css` to integrate with your existing Tailwind build. Class names are scanned automatically.
```tsx
import '@auth0/universal-components-react/tailwind';
```
</Card>
</CardGroup>
**Theming options:**
- **Color modes** — Light and dark themes with automatic switching
- **Theme variants** — Choose from `default`, `minimal`, or `rounded` styles
- **CSS variables** — Override 50+ design tokens for colors, typography, shadows, and border radii
<Card title="Styling & Theming Guide" icon="paintbrush" href="/universal-components/styling">
Learn how to customize colors, typography, and component styles to match your brand.
</Card>
There was a problem hiding this comment.
We can further improve this page by addressing the following gaps.
- CardGroup with code blocks in 2 columns - looks cramped
- Redundancy - CSS variables in Tabs are repeated verbatim in tables below
- Missing dark mode - no guidance on dark theme variables
There was a problem hiding this comment.
@chakrihacker can you confirm if this above suggestion is taken care of can you also have this reviewed again by Suraj on the above?
There was a problem hiding this comment.
@chakrihacker can you confirm if this above suggestion is taken care of can you also have this reviewed again by Suraj on the above?
can you confirm on this?
| <ThemeContext.Provider value={{ isDarkMode: mode === 'dark', theme, variables, loader }}> | ||
| <PortalContext.Provider value={portalContainer}> | ||
| <div className="auth0">{children}</div> | ||
| <div className="auth0" data-theme={theme || 'default'} ref={setPortalContainer} /> |
There was a problem hiding this comment.
why not set a fallback value here
const { variables, loader, mode, theme } = React.useMemo(
() => ({
variables: themeSettings?.variables ?? defaultStyleOverrides,
loader: themeSettings?.loader ?? null,
mode: themeSettings?.mode,
theme: themeSettings?.theme ?? 'default',
}),
[themeSettings],
);
so you dont have to do this data-theme={theme || 'default'} and just have data-theme={theme}
| */ | ||
| [data-theme='default'] { | ||
| --background: var(--color-neutral-min); | ||
| --foreground: var(--color-neutral-12); |
There was a problem hiding this comment.
Dont think , this should be needed
| --color-page: var(--color-neutral-2); | ||
| --color-background: var(--background, var(--color-neutral-min)); | ||
| --color-foreground: var(--foreground, var(--color-neutral-12)); | ||
| --color-background: var(--auth0-background, var(--color-neutral-min)); |
There was a problem hiding this comment.
why are we hardcoding auth0 ? what if user defines --foreground at root in his app , shouldnt those be inherited by default by component library ?
There was a problem hiding this comment.
Users have to add auth0 variables to their style variables. It will be documented
rax7389
left a comment
rax7389
left a comment
There was a problem hiding this comment.
@chakrihacker please correct the title of this PR
done |
5 participants
This PR establishes a clear contract between two CSS distribution modes:
styles.css— Scoped build. Auth0 feature components always render with Auth0's own design system, fully isolated from the user's global styles.tailwind.css— Unscoped build. Auth0 components participate in the user's Tailwind design tokens, allowing branding customization.Previously,
styles.cssconsumers who wrapped their app inAuth0ComponentProviderhad their own page elements inadvertently isolated from their custom global styles. This PR fixes that isolation boundary so it applies only to auth0 feature components, not to the user's content.What Changed
The
data-themeattribute is moved from the outerAuth0ComponentProviderwrapper down to the root element of each individual auth0 feature component. This makes the CSS scope boundary precise — it covers exactly the components that need it, nothing more.Scenario Coverage
styles.css, no custom stylesstyles.css, custom global styles definedstyles.css, app wrapped inAuth0ComponentProvidertailwind.css, no custom stylestailwind.css, custom branding tokensstyles.css)Changes
packages/react/postcss.config.mjs
[data-theme='default']. html/body selectors are excluded; :root is expanded to :root, .auth0.
packages/react/src/styles/globals.css
.auth0 [data-theme='...'] { ... } in the built dist/styles.css.
packages/react/src/providers/theme-provider.tsx
packages/react/src/providers/portal-context.tsx (new)
DropdownMenu, Select, Tooltip).
Feature components (domain-table, organization-details-edit, user-mfa-management, sso-provider-table, sso-provider-edit, sso-provider-create)
target.
Examples (next-rwa, react-spa-npm)
Testing
Please describe how this can be tested by reviewers. Be specific about anything not tested and reasons why. If this library has unit and tests should be added for new functionality and existing tests should complete without errors.
Checklist