feat(clerk-js,types): Add css layer name option

.changeset/metal-phones-like.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Introduce `cssLayerName` option to allow users to opt Clerk styles into a native CSS layer.

packages/clerk-js/src/ui/customizables/parseAppearance.ts

@@ -20,7 +20,7 @@ export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
 type PublicAppearanceTopLevelKey = keyof Omit<
  Appearance,
- 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha'
+ 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha' | 'cssLayerName'
 >;
 
 export type AppearanceCascade = {

packages/clerk-js/src/ui/lazyModules/providers.tsx

@@ -32,7 +32,10 @@ type LazyProvidersProps = React.PropsWithChildren<{ clerk: any; environment: any
 
 export const LazyProviders = (props: LazyProvidersProps) => {
  return (
- <StyleCacheProvider nonce={props.options.nonce}>
+ <StyleCacheProvider
+ nonce={props.options.nonce}
+ cssLayerName={props.options.appearance?.cssLayerName}
+ >
  <CoreClerkContextWrapper clerk={props.clerk}>
  <EnvironmentProvider value={props.environment}>
  <OptionsProvider value={props.options}>{props.children}</OptionsProvider>

packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx

@@ -1,26 +1,40 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider } from '@emotion/react';
+import { CacheProvider, type SerializedStyles } from '@emotion/react';
 import React, { useMemo } from 'react';
 
 const el = document.querySelector('style#cl-style-insertion-point');
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
+ /** Optional nonce value for CSP (Content Security Policy) */
  nonce?: string;
+ /** Optional CSS layer name to wrap styles in */
+ cssLayerName?: string;
 }>;
 
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
- const cache = useMemo(
- () =>
- createCache({
- key: 'cl-internal',
- prepend: !el,
- insertionPoint: el ? (el as HTMLElement) : undefined,
- nonce: props.nonce,
- }),
- [props.nonce],
- );
+ const cache = useMemo(() => {
+ const emotionCache = createCache({
+ key: 'cl-internal',
+ prepend: props.cssLayerName ? false : !el,
+ insertionPoint: el ? (el as HTMLElement) : undefined,
+ nonce: props.nonce,
+ });
+
+ if (props.cssLayerName) {
+ const prevInsert = emotionCache.insert.bind(emotionCache);
+ emotionCache.insert = (selector: string, serialized: SerializedStyles, sheet: any, shouldCache: boolean) => {
+ if (serialized && typeof serialized.styles === 'string' && !serialized.styles.startsWith('@layer')) {
+ const newSerialized = { ...serialized };
+ newSerialized.styles = `@layer ${props.cssLayerName} {${serialized.styles}}`;
+ return prevInsert(selector, newSerialized, sheet, shouldCache);
+ }
+ return prevInsert(selector, serialized, sheet, shouldCache);
+ };
+ }
+ return emotionCache;
+ }, [props.nonce, props.cssLayerName]);
 
  return <CacheProvider value={cache}>{props.children}</CacheProvider>;
 };

packages/types/src/appearance.ts

@@ -833,57 +833,67 @@ export type PricingTableTheme = Theme;
 export type CheckoutTheme = Theme;
 export type PlanDetailTheme = Theme;
 
-export type Appearance<T = Theme> = T & {
+type GlobalAppearanceOptions = {
  /**
- * Theme overrides that only apply to the `<SignIn/>` component
+ * The name of the CSS layer for Clerk component styles.
+ * This is useful for advanced CSS customization, allowing you to control the cascade and prevent style conflicts by isolating Clerk's styles within a specific layer.
+ * For more information on CSS layers, see the [MDN documentation on @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
  */
- signIn?: T;
- /**
- * Theme overrides that only apply to the `<SignUp/>` component
- */
- signUp?: T;
- /**
- * Theme overrides that only apply to the `<UserButton/>` component
- */
- userButton?: T;
- /**
- * Theme overrides that only apply to the `<UserProfile/>` component
- */
- userProfile?: T;
- /**
- * Theme overrides that only apply to the `<UserVerification/>` component
- */
- userVerification?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
- */
- organizationSwitcher?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationList/>` component
- */
- organizationList?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationProfile/>` component
- */
- organizationProfile?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- createOrganization?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- oneTap?: T;
- /**
- * Theme overrides that only apply to the `<Waitlist />` component
- */
- waitlist?: T;
- /**
- * Theme overrides that only apply to the `<PricingTable />` component
- */
- pricingTable?: T;
- /**
- * Theme overrides that only apply to the `<Checkout />` component
- */
- checkout?: T;
+ cssLayerName?: string;
 };
+
+export type Appearance<T = Theme> = T &
+ GlobalAppearanceOptions & {
+ /**
+ * Theme overrides that only apply to the `<SignIn/>` component
+ */
+ signIn?: T;
+ /**
+ * Theme overrides that only apply to the `<SignUp/>` component
+ */
+ signUp?: T;
+ /**
+ * Theme overrides that only apply to the `<UserButton/>` component
+ */
+ userButton?: T;
+ /**
+ * Theme overrides that only apply to the `<UserProfile/>` component
+ */
+ userProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<UserVerification/>` component
+ */
+ userVerification?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
+ */
+ organizationSwitcher?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationList/>` component
+ */
+ organizationList?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationProfile/>` component
+ */
+ organizationProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ createOrganization?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ oneTap?: T;
+ /**
+ * Theme overrides that only apply to the `<Waitlist />` component
+ */
+ waitlist?: T;
+ /**
+ * Theme overrides that only apply to the `<PricingTable />` component
+ */
+ pricingTable?: T;
+ /**
+ * Theme overrides that only apply to the `<Checkout />` component
+ */
+ checkout?: T;
+ };

.changeset/metal-phones-like.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Introduce `cssLayerName` option to allow users to opt Clerk styles into a native CSS layer.

packages/clerk-js/src/ui/customizables/parseAppearance.ts

@@ -20,7 +20,7 @@ export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
 type PublicAppearanceTopLevelKey = keyof Omit<
  Appearance,
- 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha'
+ 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha' | 'cssLayerName'
 >;
 
 export type AppearanceCascade = {

packages/clerk-js/src/ui/lazyModules/providers.tsx

@@ -32,7 +32,10 @@ type LazyProvidersProps = React.PropsWithChildren<{ clerk: any; environment: any
 
 export const LazyProviders = (props: LazyProvidersProps) => {
  return (
- <StyleCacheProvider nonce={props.options.nonce}>
+ <StyleCacheProvider
+ nonce={props.options.nonce}
+ cssLayerName={props.options.appearance?.cssLayerName}
+ >
  <CoreClerkContextWrapper clerk={props.clerk}>
  <EnvironmentProvider value={props.environment}>
  <OptionsProvider value={props.options}>{props.children}</OptionsProvider>

packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx

@@ -1,26 +1,40 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider } from '@emotion/react';
+import { CacheProvider, type SerializedStyles } from '@emotion/react';
 import React, { useMemo } from 'react';
 
 const el = document.querySelector('style#cl-style-insertion-point');
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
+ /** Optional nonce value for CSP (Content Security Policy) */
  nonce?: string;
+ /** Optional CSS layer name to wrap styles in */
+ cssLayerName?: string;
 }>;
 
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
- const cache = useMemo(
- () =>
- createCache({
- key: 'cl-internal',
- prepend: !el,
- insertionPoint: el ? (el as HTMLElement) : undefined,
- nonce: props.nonce,
- }),
- [props.nonce],
- );
+ const cache = useMemo(() => {
+ const emotionCache = createCache({
+ key: 'cl-internal',
+ prepend: props.cssLayerName ? false : !el,
+ insertionPoint: el ? (el as HTMLElement) : undefined,
+ nonce: props.nonce,
+ });
+
+ if (props.cssLayerName) {
+ const prevInsert = emotionCache.insert.bind(emotionCache);
+ emotionCache.insert = (selector: string, serialized: SerializedStyles, sheet: any, shouldCache: boolean) => {
+ if (serialized && typeof serialized.styles === 'string' && !serialized.styles.startsWith('@layer')) {
+ const newSerialized = { ...serialized };
+ newSerialized.styles = `@layer ${props.cssLayerName} {${serialized.styles}}`;
+ return prevInsert(selector, newSerialized, sheet, shouldCache);
+ }
+ return prevInsert(selector, serialized, sheet, shouldCache);
+ };
+ }
+ return emotionCache;
+ }, [props.nonce, props.cssLayerName]);
 
  return <CacheProvider value={cache}>{props.children}</CacheProvider>;
 };

packages/types/src/appearance.ts

@@ -833,57 +833,67 @@ export type PricingTableTheme = Theme;
 export type CheckoutTheme = Theme;
 export type PlanDetailTheme = Theme;
 
-export type Appearance<T = Theme> = T & {
+type GlobalAppearanceOptions = {
  /**
- * Theme overrides that only apply to the `<SignIn/>` component
+ * The name of the CSS layer for Clerk component styles.
+ * This is useful for advanced CSS customization, allowing you to control the cascade and prevent style conflicts by isolating Clerk's styles within a specific layer.
+ * For more information on CSS layers, see the [MDN documentation on @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
  */
- signIn?: T;
- /**
- * Theme overrides that only apply to the `<SignUp/>` component
- */
- signUp?: T;
- /**
- * Theme overrides that only apply to the `<UserButton/>` component
- */
- userButton?: T;
- /**
- * Theme overrides that only apply to the `<UserProfile/>` component
- */
- userProfile?: T;
- /**
- * Theme overrides that only apply to the `<UserVerification/>` component
- */
- userVerification?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
- */
- organizationSwitcher?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationList/>` component
- */
- organizationList?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationProfile/>` component
- */
- organizationProfile?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- createOrganization?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- oneTap?: T;
- /**
- * Theme overrides that only apply to the `<Waitlist />` component
- */
- waitlist?: T;
- /**
- * Theme overrides that only apply to the `<PricingTable />` component
- */
- pricingTable?: T;
- /**
- * Theme overrides that only apply to the `<Checkout />` component
- */
- checkout?: T;
+ cssLayerName?: string;
 };
+
+export type Appearance<T = Theme> = T &
+ GlobalAppearanceOptions & {
+ /**
+ * Theme overrides that only apply to the `<SignIn/>` component
+ */
+ signIn?: T;
+ /**
+ * Theme overrides that only apply to the `<SignUp/>` component
+ */
+ signUp?: T;
+ /**
+ * Theme overrides that only apply to the `<UserButton/>` component
+ */
+ userButton?: T;
+ /**
+ * Theme overrides that only apply to the `<UserProfile/>` component
+ */
+ userProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<UserVerification/>` component
+ */
+ userVerification?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
+ */
+ organizationSwitcher?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationList/>` component
+ */
+ organizationList?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationProfile/>` component
+ */
+ organizationProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ createOrganization?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ oneTap?: T;
+ /**
+ * Theme overrides that only apply to the `<Waitlist />` component
+ */
+ waitlist?: T;
+ /**
+ * Theme overrides that only apply to the `<PricingTable />` component
+ */
+ pricingTable?: T;
+ /**
+ * Theme overrides that only apply to the `<Checkout />` component
+ */
+ checkout?: T;
+ };

.changeset/metal-phones-like.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Introduce `cssLayerName` option to allow users to opt Clerk styles into a native CSS layer.

packages/clerk-js/src/ui/customizables/parseAppearance.ts

@@ -20,7 +20,7 @@ export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
 type PublicAppearanceTopLevelKey = keyof Omit<
  Appearance,
- 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha'
+ 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha' | 'cssLayerName'
 >;
 
 export type AppearanceCascade = {

packages/clerk-js/src/ui/lazyModules/providers.tsx

@@ -32,7 +32,10 @@ type LazyProvidersProps = React.PropsWithChildren<{ clerk: any; environment: any
 
 export const LazyProviders = (props: LazyProvidersProps) => {
  return (
- <StyleCacheProvider nonce={props.options.nonce}>
+ <StyleCacheProvider
+ nonce={props.options.nonce}
+ cssLayerName={props.options.appearance?.cssLayerName}
+ >
  <CoreClerkContextWrapper clerk={props.clerk}>
  <EnvironmentProvider value={props.environment}>
  <OptionsProvider value={props.options}>{props.children}</OptionsProvider>

packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx

@@ -1,26 +1,40 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider } from '@emotion/react';
+import { CacheProvider, type SerializedStyles } from '@emotion/react';
 import React, { useMemo } from 'react';
 
 const el = document.querySelector('style#cl-style-insertion-point');
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
+ /** Optional nonce value for CSP (Content Security Policy) */
  nonce?: string;
+ /** Optional CSS layer name to wrap styles in */
+ cssLayerName?: string;
 }>;
 
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
- const cache = useMemo(
- () =>
- createCache({
- key: 'cl-internal',
- prepend: !el,
- insertionPoint: el ? (el as HTMLElement) : undefined,
- nonce: props.nonce,
- }),
- [props.nonce],
- );
+ const cache = useMemo(() => {
+ const emotionCache = createCache({
+ key: 'cl-internal',
+ prepend: props.cssLayerName ? false : !el,
+ insertionPoint: el ? (el as HTMLElement) : undefined,
+ nonce: props.nonce,
+ });
+
+ if (props.cssLayerName) {
+ const prevInsert = emotionCache.insert.bind(emotionCache);
+ emotionCache.insert = (selector: string, serialized: SerializedStyles, sheet: any, shouldCache: boolean) => {
+ if (serialized && typeof serialized.styles === 'string' && !serialized.styles.startsWith('@layer')) {
+ const newSerialized = { ...serialized };
+ newSerialized.styles = `@layer ${props.cssLayerName} {${serialized.styles}}`;
+ return prevInsert(selector, newSerialized, sheet, shouldCache);
+ }
+ return prevInsert(selector, serialized, sheet, shouldCache);
+ };
+ }
+ return emotionCache;
+ }, [props.nonce, props.cssLayerName]);
 
  return <CacheProvider value={cache}>{props.children}</CacheProvider>;
 };

packages/types/src/appearance.ts

@@ -833,57 +833,67 @@ export type PricingTableTheme = Theme;
 export type CheckoutTheme = Theme;
 export type PlanDetailTheme = Theme;
 
-export type Appearance<T = Theme> = T & {
+type GlobalAppearanceOptions = {
  /**
- * Theme overrides that only apply to the `<SignIn/>` component
+ * The name of the CSS layer for Clerk component styles.
+ * This is useful for advanced CSS customization, allowing you to control the cascade and prevent style conflicts by isolating Clerk's styles within a specific layer.
+ * For more information on CSS layers, see the [MDN documentation on @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
  */
- signIn?: T;
- /**
- * Theme overrides that only apply to the `<SignUp/>` component
- */
- signUp?: T;
- /**
- * Theme overrides that only apply to the `<UserButton/>` component
- */
- userButton?: T;
- /**
- * Theme overrides that only apply to the `<UserProfile/>` component
- */
- userProfile?: T;
- /**
- * Theme overrides that only apply to the `<UserVerification/>` component
- */
- userVerification?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
- */
- organizationSwitcher?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationList/>` component
- */
- organizationList?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationProfile/>` component
- */
- organizationProfile?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- createOrganization?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- oneTap?: T;
- /**
- * Theme overrides that only apply to the `<Waitlist />` component
- */
- waitlist?: T;
- /**
- * Theme overrides that only apply to the `<PricingTable />` component
- */
- pricingTable?: T;
- /**
- * Theme overrides that only apply to the `<Checkout />` component
- */
- checkout?: T;
+ cssLayerName?: string;
 };
+
+export type Appearance<T = Theme> = T &
+ GlobalAppearanceOptions & {
+ /**
+ * Theme overrides that only apply to the `<SignIn/>` component
+ */
+ signIn?: T;
+ /**
+ * Theme overrides that only apply to the `<SignUp/>` component
+ */
+ signUp?: T;
+ /**
+ * Theme overrides that only apply to the `<UserButton/>` component
+ */
+ userButton?: T;
+ /**
+ * Theme overrides that only apply to the `<UserProfile/>` component
+ */
+ userProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<UserVerification/>` component
+ */
+ userVerification?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
+ */
+ organizationSwitcher?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationList/>` component
+ */
+ organizationList?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationProfile/>` component
+ */
+ organizationProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ createOrganization?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ oneTap?: T;
+ /**
+ * Theme overrides that only apply to the `<Waitlist />` component
+ */
+ waitlist?: T;
+ /**
+ * Theme overrides that only apply to the `<PricingTable />` component
+ */
+ pricingTable?: T;
+ /**
+ * Theme overrides that only apply to the `<Checkout />` component
+ */
+ checkout?: T;
+ };

.changeset/metal-phones-like.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Introduce `cssLayerName` option to allow users to opt Clerk styles into a native CSS layer.

packages/clerk-js/src/ui/customizables/parseAppearance.ts

@@ -20,7 +20,7 @@ export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
 type PublicAppearanceTopLevelKey = keyof Omit<
  Appearance,
- 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha'
+ 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha' | 'cssLayerName'
 >;
 
 export type AppearanceCascade = {

packages/clerk-js/src/ui/lazyModules/providers.tsx

@@ -32,7 +32,10 @@ type LazyProvidersProps = React.PropsWithChildren<{ clerk: any; environment: any
 
 export const LazyProviders = (props: LazyProvidersProps) => {
  return (
- <StyleCacheProvider nonce={props.options.nonce}>
+ <StyleCacheProvider
+ nonce={props.options.nonce}
+ cssLayerName={props.options.appearance?.cssLayerName}
+ >
  <CoreClerkContextWrapper clerk={props.clerk}>
  <EnvironmentProvider value={props.environment}>
  <OptionsProvider value={props.options}>{props.children}</OptionsProvider>

packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx

@@ -1,26 +1,40 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider } from '@emotion/react';
+import { CacheProvider, type SerializedStyles } from '@emotion/react';
 import React, { useMemo } from 'react';
 
 const el = document.querySelector('style#cl-style-insertion-point');
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
+ /** Optional nonce value for CSP (Content Security Policy) */
  nonce?: string;
+ /** Optional CSS layer name to wrap styles in */
+ cssLayerName?: string;
 }>;
 
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
- const cache = useMemo(
- () =>
- createCache({
- key: 'cl-internal',
- prepend: !el,
- insertionPoint: el ? (el as HTMLElement) : undefined,
- nonce: props.nonce,
- }),
- [props.nonce],
- );
+ const cache = useMemo(() => {
+ const emotionCache = createCache({
+ key: 'cl-internal',
+ prepend: props.cssLayerName ? false : !el,
+ insertionPoint: el ? (el as HTMLElement) : undefined,
+ nonce: props.nonce,
+ });
+
+ if (props.cssLayerName) {
+ const prevInsert = emotionCache.insert.bind(emotionCache);
+ emotionCache.insert = (selector: string, serialized: SerializedStyles, sheet: any, shouldCache: boolean) => {
+ if (serialized && typeof serialized.styles === 'string' && !serialized.styles.startsWith('@layer')) {
+ const newSerialized = { ...serialized };
+ newSerialized.styles = `@layer ${props.cssLayerName} {${serialized.styles}}`;
+ return prevInsert(selector, newSerialized, sheet, shouldCache);
+ }
+ return prevInsert(selector, serialized, sheet, shouldCache);
+ };
+ }
+ return emotionCache;
+ }, [props.nonce, props.cssLayerName]);
 
  return <CacheProvider value={cache}>{props.children}</CacheProvider>;
 };

packages/types/src/appearance.ts

@@ -833,57 +833,67 @@ export type PricingTableTheme = Theme;
 export type CheckoutTheme = Theme;
 export type PlanDetailTheme = Theme;
 
-export type Appearance<T = Theme> = T & {
+type GlobalAppearanceOptions = {
  /**
- * Theme overrides that only apply to the `<SignIn/>` component
+ * The name of the CSS layer for Clerk component styles.
+ * This is useful for advanced CSS customization, allowing you to control the cascade and prevent style conflicts by isolating Clerk's styles within a specific layer.
+ * For more information on CSS layers, see the [MDN documentation on @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
  */
- signIn?: T;
- /**
- * Theme overrides that only apply to the `<SignUp/>` component
- */
- signUp?: T;
- /**
- * Theme overrides that only apply to the `<UserButton/>` component
- */
- userButton?: T;
- /**
- * Theme overrides that only apply to the `<UserProfile/>` component
- */
- userProfile?: T;
- /**
- * Theme overrides that only apply to the `<UserVerification/>` component
- */
- userVerification?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
- */
- organizationSwitcher?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationList/>` component
- */
- organizationList?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationProfile/>` component
- */
- organizationProfile?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- createOrganization?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- oneTap?: T;
- /**
- * Theme overrides that only apply to the `<Waitlist />` component
- */
- waitlist?: T;
- /**
- * Theme overrides that only apply to the `<PricingTable />` component
- */
- pricingTable?: T;
- /**
- * Theme overrides that only apply to the `<Checkout />` component
- */
- checkout?: T;
+ cssLayerName?: string;
 };
+
+export type Appearance<T = Theme> = T &
+ GlobalAppearanceOptions & {
+ /**
+ * Theme overrides that only apply to the `<SignIn/>` component
+ */
+ signIn?: T;
+ /**
+ * Theme overrides that only apply to the `<SignUp/>` component
+ */
+ signUp?: T;
+ /**
+ * Theme overrides that only apply to the `<UserButton/>` component
+ */
+ userButton?: T;
+ /**
+ * Theme overrides that only apply to the `<UserProfile/>` component
+ */
+ userProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<UserVerification/>` component
+ */
+ userVerification?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
+ */
+ organizationSwitcher?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationList/>` component
+ */
+ organizationList?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationProfile/>` component
+ */
+ organizationProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ createOrganization?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ oneTap?: T;
+ /**
+ * Theme overrides that only apply to the `<Waitlist />` component
+ */
+ waitlist?: T;
+ /**
+ * Theme overrides that only apply to the `<PricingTable />` component
+ */
+ pricingTable?: T;
+ /**
+ * Theme overrides that only apply to the `<Checkout />` component
+ */
+ checkout?: T;
+ };

.changeset/metal-phones-like.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Introduce `cssLayerName` option to allow users to opt Clerk styles into a native CSS layer.

packages/clerk-js/src/ui/customizables/parseAppearance.ts

@@ -20,7 +20,7 @@ export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
 type PublicAppearanceTopLevelKey = keyof Omit<
  Appearance,
- 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha'
+ 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha' | 'cssLayerName'
 >;
 
 export type AppearanceCascade = {

packages/clerk-js/src/ui/lazyModules/providers.tsx

@@ -32,7 +32,10 @@ type LazyProvidersProps = React.PropsWithChildren<{ clerk: any; environment: any
 
 export const LazyProviders = (props: LazyProvidersProps) => {
  return (
- <StyleCacheProvider nonce={props.options.nonce}>
+ <StyleCacheProvider
+ nonce={props.options.nonce}
+ cssLayerName={props.options.appearance?.cssLayerName}
+ >
  <CoreClerkContextWrapper clerk={props.clerk}>
  <EnvironmentProvider value={props.environment}>
  <OptionsProvider value={props.options}>{props.children}</OptionsProvider>

packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx

@@ -1,26 +1,40 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider } from '@emotion/react';
+import { CacheProvider, type SerializedStyles } from '@emotion/react';
 import React, { useMemo } from 'react';
 
 const el = document.querySelector('style#cl-style-insertion-point');
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
+ /** Optional nonce value for CSP (Content Security Policy) */
  nonce?: string;
+ /** Optional CSS layer name to wrap styles in */
+ cssLayerName?: string;
 }>;
 
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
- const cache = useMemo(
- () =>
- createCache({
- key: 'cl-internal',
- prepend: !el,
- insertionPoint: el ? (el as HTMLElement) : undefined,
- nonce: props.nonce,
- }),
- [props.nonce],
- );
+ const cache = useMemo(() => {
+ const emotionCache = createCache({
+ key: 'cl-internal',
+ prepend: props.cssLayerName ? false : !el,
+ insertionPoint: el ? (el as HTMLElement) : undefined,
+ nonce: props.nonce,
+ });
+
+ if (props.cssLayerName) {
+ const prevInsert = emotionCache.insert.bind(emotionCache);
+ emotionCache.insert = (selector: string, serialized: SerializedStyles, sheet: any, shouldCache: boolean) => {
+ if (serialized && typeof serialized.styles === 'string' && !serialized.styles.startsWith('@layer')) {
+ const newSerialized = { ...serialized };
+ newSerialized.styles = `@layer ${props.cssLayerName} {${serialized.styles}}`;
+ return prevInsert(selector, newSerialized, sheet, shouldCache);
+ }
+ return prevInsert(selector, serialized, sheet, shouldCache);
+ };
+ }
+ return emotionCache;
+ }, [props.nonce, props.cssLayerName]);
 
  return <CacheProvider value={cache}>{props.children}</CacheProvider>;
 };

packages/types/src/appearance.ts

@@ -833,57 +833,67 @@ export type PricingTableTheme = Theme;
 export type CheckoutTheme = Theme;
 export type PlanDetailTheme = Theme;
 
-export type Appearance<T = Theme> = T & {
+type GlobalAppearanceOptions = {
  /**
- * Theme overrides that only apply to the `<SignIn/>` component
+ * The name of the CSS layer for Clerk component styles.
+ * This is useful for advanced CSS customization, allowing you to control the cascade and prevent style conflicts by isolating Clerk's styles within a specific layer.
+ * For more information on CSS layers, see the [MDN documentation on @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
  */
- signIn?: T;
- /**
- * Theme overrides that only apply to the `<SignUp/>` component
- */
- signUp?: T;
- /**
- * Theme overrides that only apply to the `<UserButton/>` component
- */
- userButton?: T;
- /**
- * Theme overrides that only apply to the `<UserProfile/>` component
- */
- userProfile?: T;
- /**
- * Theme overrides that only apply to the `<UserVerification/>` component
- */
- userVerification?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
- */
- organizationSwitcher?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationList/>` component
- */
- organizationList?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationProfile/>` component
- */
- organizationProfile?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- createOrganization?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- oneTap?: T;
- /**
- * Theme overrides that only apply to the `<Waitlist />` component
- */
- waitlist?: T;
- /**
- * Theme overrides that only apply to the `<PricingTable />` component
- */
- pricingTable?: T;
- /**
- * Theme overrides that only apply to the `<Checkout />` component
- */
- checkout?: T;
+ cssLayerName?: string;
 };
+
+export type Appearance<T = Theme> = T &
+ GlobalAppearanceOptions & {
+ /**
+ * Theme overrides that only apply to the `<SignIn/>` component
+ */
+ signIn?: T;
+ /**
+ * Theme overrides that only apply to the `<SignUp/>` component
+ */
+ signUp?: T;
+ /**
+ * Theme overrides that only apply to the `<UserButton/>` component
+ */
+ userButton?: T;
+ /**
+ * Theme overrides that only apply to the `<UserProfile/>` component
+ */
+ userProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<UserVerification/>` component
+ */
+ userVerification?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
+ */
+ organizationSwitcher?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationList/>` component
+ */
+ organizationList?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationProfile/>` component
+ */
+ organizationProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ createOrganization?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ oneTap?: T;
+ /**
+ * Theme overrides that only apply to the `<Waitlist />` component
+ */
+ waitlist?: T;
+ /**
+ * Theme overrides that only apply to the `<PricingTable />` component
+ */
+ pricingTable?: T;
+ /**
+ * Theme overrides that only apply to the `<Checkout />` component
+ */
+ checkout?: T;
+ };

.changeset/metal-phones-like.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Introduce `cssLayerName` option to allow users to opt Clerk styles into a native CSS layer.

packages/clerk-js/src/ui/customizables/parseAppearance.ts

@@ -20,7 +20,7 @@ export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
 type PublicAppearanceTopLevelKey = keyof Omit<
  Appearance,
- 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha'
+ 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha' | 'cssLayerName'
 >;
 
 export type AppearanceCascade = {

packages/clerk-js/src/ui/lazyModules/providers.tsx

@@ -32,7 +32,10 @@ type LazyProvidersProps = React.PropsWithChildren<{ clerk: any; environment: any
 
 export const LazyProviders = (props: LazyProvidersProps) => {
  return (
- <StyleCacheProvider nonce={props.options.nonce}>
+ <StyleCacheProvider
+ nonce={props.options.nonce}
+ cssLayerName={props.options.appearance?.cssLayerName}
+ >
  <CoreClerkContextWrapper clerk={props.clerk}>
  <EnvironmentProvider value={props.environment}>
  <OptionsProvider value={props.options}>{props.children}</OptionsProvider>

packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx

@@ -1,26 +1,40 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider } from '@emotion/react';
+import { CacheProvider, type SerializedStyles } from '@emotion/react';
 import React, { useMemo } from 'react';
 
 const el = document.querySelector('style#cl-style-insertion-point');
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
+ /** Optional nonce value for CSP (Content Security Policy) */
  nonce?: string;
+ /** Optional CSS layer name to wrap styles in */
+ cssLayerName?: string;
 }>;
 
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
- const cache = useMemo(
- () =>
- createCache({
- key: 'cl-internal',
- prepend: !el,
- insertionPoint: el ? (el as HTMLElement) : undefined,
- nonce: props.nonce,
- }),
- [props.nonce],
- );
+ const cache = useMemo(() => {
+ const emotionCache = createCache({
+ key: 'cl-internal',
+ prepend: props.cssLayerName ? false : !el,
+ insertionPoint: el ? (el as HTMLElement) : undefined,
+ nonce: props.nonce,
+ });
+
+ if (props.cssLayerName) {
+ const prevInsert = emotionCache.insert.bind(emotionCache);
+ emotionCache.insert = (selector: string, serialized: SerializedStyles, sheet: any, shouldCache: boolean) => {
+ if (serialized && typeof serialized.styles === 'string' && !serialized.styles.startsWith('@layer')) {
+ const newSerialized = { ...serialized };
+ newSerialized.styles = `@layer ${props.cssLayerName} {${serialized.styles}}`;
+ return prevInsert(selector, newSerialized, sheet, shouldCache);
+ }
+ return prevInsert(selector, serialized, sheet, shouldCache);
+ };
+ }
+ return emotionCache;
+ }, [props.nonce, props.cssLayerName]);
 
  return <CacheProvider value={cache}>{props.children}</CacheProvider>;
 };

packages/types/src/appearance.ts

@@ -833,57 +833,67 @@ export type PricingTableTheme = Theme;
 export type CheckoutTheme = Theme;
 export type PlanDetailTheme = Theme;
 
-export type Appearance<T = Theme> = T & {
+type GlobalAppearanceOptions = {
  /**
- * Theme overrides that only apply to the `<SignIn/>` component
+ * The name of the CSS layer for Clerk component styles.
+ * This is useful for advanced CSS customization, allowing you to control the cascade and prevent style conflicts by isolating Clerk's styles within a specific layer.
+ * For more information on CSS layers, see the [MDN documentation on @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
  */
- signIn?: T;
- /**
- * Theme overrides that only apply to the `<SignUp/>` component
- */
- signUp?: T;
- /**
- * Theme overrides that only apply to the `<UserButton/>` component
- */
- userButton?: T;
- /**
- * Theme overrides that only apply to the `<UserProfile/>` component
- */
- userProfile?: T;
- /**
- * Theme overrides that only apply to the `<UserVerification/>` component
- */
- userVerification?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
- */
- organizationSwitcher?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationList/>` component
- */
- organizationList?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationProfile/>` component
- */
- organizationProfile?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- createOrganization?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- oneTap?: T;
- /**
- * Theme overrides that only apply to the `<Waitlist />` component
- */
- waitlist?: T;
- /**
- * Theme overrides that only apply to the `<PricingTable />` component
- */
- pricingTable?: T;
- /**
- * Theme overrides that only apply to the `<Checkout />` component
- */
- checkout?: T;
+ cssLayerName?: string;
 };
+
+export type Appearance<T = Theme> = T &
+ GlobalAppearanceOptions & {
+ /**
+ * Theme overrides that only apply to the `<SignIn/>` component
+ */
+ signIn?: T;
+ /**
+ * Theme overrides that only apply to the `<SignUp/>` component
+ */
+ signUp?: T;
+ /**
+ * Theme overrides that only apply to the `<UserButton/>` component
+ */
+ userButton?: T;
+ /**
+ * Theme overrides that only apply to the `<UserProfile/>` component
+ */
+ userProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<UserVerification/>` component
+ */
+ userVerification?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
+ */
+ organizationSwitcher?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationList/>` component
+ */
+ organizationList?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationProfile/>` component
+ */
+ organizationProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ createOrganization?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ oneTap?: T;
+ /**
+ * Theme overrides that only apply to the `<Waitlist />` component
+ */
+ waitlist?: T;
+ /**
+ * Theme overrides that only apply to the `<PricingTable />` component
+ */
+ pricingTable?: T;
+ /**
+ * Theme overrides that only apply to the `<Checkout />` component
+ */
+ checkout?: T;
+ };

.changeset/metal-phones-like.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Introduce `cssLayerName` option to allow users to opt Clerk styles into a native CSS layer.

packages/clerk-js/src/ui/customizables/parseAppearance.ts

@@ -20,7 +20,7 @@ export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
 type PublicAppearanceTopLevelKey = keyof Omit<
  Appearance,
- 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha'
+ 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha' | 'cssLayerName'
 >;
 
 export type AppearanceCascade = {

packages/clerk-js/src/ui/lazyModules/providers.tsx

@@ -32,7 +32,10 @@ type LazyProvidersProps = React.PropsWithChildren<{ clerk: any; environment: any
 
 export const LazyProviders = (props: LazyProvidersProps) => {
  return (
- <StyleCacheProvider nonce={props.options.nonce}>
+ <StyleCacheProvider
+ nonce={props.options.nonce}
+ cssLayerName={props.options.appearance?.cssLayerName}
+ >
  <CoreClerkContextWrapper clerk={props.clerk}>
  <EnvironmentProvider value={props.environment}>
  <OptionsProvider value={props.options}>{props.children}</OptionsProvider>

packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx

@@ -1,26 +1,40 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider } from '@emotion/react';
+import { CacheProvider, type SerializedStyles } from '@emotion/react';
 import React, { useMemo } from 'react';
 
 const el = document.querySelector('style#cl-style-insertion-point');
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
+ /** Optional nonce value for CSP (Content Security Policy) */
  nonce?: string;
+ /** Optional CSS layer name to wrap styles in */
+ cssLayerName?: string;
 }>;
 
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
- const cache = useMemo(
- () =>
- createCache({
- key: 'cl-internal',
- prepend: !el,
- insertionPoint: el ? (el as HTMLElement) : undefined,
- nonce: props.nonce,
- }),
- [props.nonce],
- );
+ const cache = useMemo(() => {
+ const emotionCache = createCache({
+ key: 'cl-internal',
+ prepend: props.cssLayerName ? false : !el,
+ insertionPoint: el ? (el as HTMLElement) : undefined,
+ nonce: props.nonce,
+ });
+
+ if (props.cssLayerName) {
+ const prevInsert = emotionCache.insert.bind(emotionCache);
+ emotionCache.insert = (selector: string, serialized: SerializedStyles, sheet: any, shouldCache: boolean) => {
+ if (serialized && typeof serialized.styles === 'string' && !serialized.styles.startsWith('@layer')) {
+ const newSerialized = { ...serialized };
+ newSerialized.styles = `@layer ${props.cssLayerName} {${serialized.styles}}`;
+ return prevInsert(selector, newSerialized, sheet, shouldCache);
+ }
+ return prevInsert(selector, serialized, sheet, shouldCache);
+ };
+ }
+ return emotionCache;
+ }, [props.nonce, props.cssLayerName]);
 
  return <CacheProvider value={cache}>{props.children}</CacheProvider>;
 };

packages/types/src/appearance.ts

@@ -833,57 +833,67 @@ export type PricingTableTheme = Theme;
 export type CheckoutTheme = Theme;
 export type PlanDetailTheme = Theme;
 
-export type Appearance<T = Theme> = T & {
+type GlobalAppearanceOptions = {
  /**
- * Theme overrides that only apply to the `<SignIn/>` component
+ * The name of the CSS layer for Clerk component styles.
+ * This is useful for advanced CSS customization, allowing you to control the cascade and prevent style conflicts by isolating Clerk's styles within a specific layer.
+ * For more information on CSS layers, see the [MDN documentation on @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
  */
- signIn?: T;
- /**
- * Theme overrides that only apply to the `<SignUp/>` component
- */
- signUp?: T;
- /**
- * Theme overrides that only apply to the `<UserButton/>` component
- */
- userButton?: T;
- /**
- * Theme overrides that only apply to the `<UserProfile/>` component
- */
- userProfile?: T;
- /**
- * Theme overrides that only apply to the `<UserVerification/>` component
- */
- userVerification?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
- */
- organizationSwitcher?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationList/>` component
- */
- organizationList?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationProfile/>` component
- */
- organizationProfile?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- createOrganization?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- oneTap?: T;
- /**
- * Theme overrides that only apply to the `<Waitlist />` component
- */
- waitlist?: T;
- /**
- * Theme overrides that only apply to the `<PricingTable />` component
- */
- pricingTable?: T;
- /**
- * Theme overrides that only apply to the `<Checkout />` component
- */
- checkout?: T;
+ cssLayerName?: string;
 };
+
+export type Appearance<T = Theme> = T &
+ GlobalAppearanceOptions & {
+ /**
+ * Theme overrides that only apply to the `<SignIn/>` component
+ */
+ signIn?: T;
+ /**
+ * Theme overrides that only apply to the `<SignUp/>` component
+ */
+ signUp?: T;
+ /**
+ * Theme overrides that only apply to the `<UserButton/>` component
+ */
+ userButton?: T;
+ /**
+ * Theme overrides that only apply to the `<UserProfile/>` component
+ */
+ userProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<UserVerification/>` component
+ */
+ userVerification?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
+ */
+ organizationSwitcher?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationList/>` component
+ */
+ organizationList?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationProfile/>` component
+ */
+ organizationProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ createOrganization?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ oneTap?: T;
+ /**
+ * Theme overrides that only apply to the `<Waitlist />` component
+ */
+ waitlist?: T;
+ /**
+ * Theme overrides that only apply to the `<PricingTable />` component
+ */
+ pricingTable?: T;
+ /**
+ * Theme overrides that only apply to the `<Checkout />` component
+ */
+ checkout?: T;
+ };

.changeset/metal-phones-like.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Introduce `cssLayerName` option to allow users to opt Clerk styles into a native CSS layer.

packages/clerk-js/src/ui/customizables/parseAppearance.ts

@@ -20,7 +20,7 @@ export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
 type PublicAppearanceTopLevelKey = keyof Omit<
  Appearance,
- 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha'
+ 'baseTheme' | 'elements' | 'layout' | 'variables' | 'captcha' | 'cssLayerName'
 >;
 
 export type AppearanceCascade = {

packages/clerk-js/src/ui/lazyModules/providers.tsx

@@ -32,7 +32,10 @@ type LazyProvidersProps = React.PropsWithChildren<{ clerk: any; environment: any
 
 export const LazyProviders = (props: LazyProvidersProps) => {
  return (
- <StyleCacheProvider nonce={props.options.nonce}>
+ <StyleCacheProvider
+ nonce={props.options.nonce}
+ cssLayerName={props.options.appearance?.cssLayerName}
+ >
  <CoreClerkContextWrapper clerk={props.clerk}>
  <EnvironmentProvider value={props.environment}>
  <OptionsProvider value={props.options}>{props.children}</OptionsProvider>

packages/clerk-js/src/ui/styledSystem/StyleCacheProvider.tsx

@@ -1,26 +1,40 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider } from '@emotion/react';
+import { CacheProvider, type SerializedStyles } from '@emotion/react';
 import React, { useMemo } from 'react';
 
 const el = document.querySelector('style#cl-style-insertion-point');
 
 type StyleCacheProviderProps = React.PropsWithChildren<{
+ /** Optional nonce value for CSP (Content Security Policy) */
  nonce?: string;
+ /** Optional CSS layer name to wrap styles in */
+ cssLayerName?: string;
 }>;
 
 export const StyleCacheProvider = (props: StyleCacheProviderProps) => {
- const cache = useMemo(
- () =>
- createCache({
- key: 'cl-internal',
- prepend: !el,
- insertionPoint: el ? (el as HTMLElement) : undefined,
- nonce: props.nonce,
- }),
- [props.nonce],
- );
+ const cache = useMemo(() => {
+ const emotionCache = createCache({
+ key: 'cl-internal',
+ prepend: props.cssLayerName ? false : !el,
+ insertionPoint: el ? (el as HTMLElement) : undefined,
+ nonce: props.nonce,
+ });
+
+ if (props.cssLayerName) {
+ const prevInsert = emotionCache.insert.bind(emotionCache);
+ emotionCache.insert = (selector: string, serialized: SerializedStyles, sheet: any, shouldCache: boolean) => {
+ if (serialized && typeof serialized.styles === 'string' && !serialized.styles.startsWith('@layer')) {
+ const newSerialized = { ...serialized };
+ newSerialized.styles = `@layer ${props.cssLayerName} {${serialized.styles}}`;
+ return prevInsert(selector, newSerialized, sheet, shouldCache);
+ }
+ return prevInsert(selector, serialized, sheet, shouldCache);
+ };
+ }
+ return emotionCache;
+ }, [props.nonce, props.cssLayerName]);
 
  return <CacheProvider value={cache}>{props.children}</CacheProvider>;
 };

packages/types/src/appearance.ts

@@ -833,57 +833,67 @@ export type PricingTableTheme = Theme;
 export type CheckoutTheme = Theme;
 export type PlanDetailTheme = Theme;
 
-export type Appearance<T = Theme> = T & {
+type GlobalAppearanceOptions = {
  /**
- * Theme overrides that only apply to the `<SignIn/>` component
+ * The name of the CSS layer for Clerk component styles.
+ * This is useful for advanced CSS customization, allowing you to control the cascade and prevent style conflicts by isolating Clerk's styles within a specific layer.
+ * For more information on CSS layers, see the [MDN documentation on @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
  */
- signIn?: T;
- /**
- * Theme overrides that only apply to the `<SignUp/>` component
- */
- signUp?: T;
- /**
- * Theme overrides that only apply to the `<UserButton/>` component
- */
- userButton?: T;
- /**
- * Theme overrides that only apply to the `<UserProfile/>` component
- */
- userProfile?: T;
- /**
- * Theme overrides that only apply to the `<UserVerification/>` component
- */
- userVerification?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
- */
- organizationSwitcher?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationList/>` component
- */
- organizationList?: T;
- /**
- * Theme overrides that only apply to the `<OrganizationProfile/>` component
- */
- organizationProfile?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- createOrganization?: T;
- /**
- * Theme overrides that only apply to the `<CreateOrganization />` component
- */
- oneTap?: T;
- /**
- * Theme overrides that only apply to the `<Waitlist />` component
- */
- waitlist?: T;
- /**
- * Theme overrides that only apply to the `<PricingTable />` component
- */
- pricingTable?: T;
- /**
- * Theme overrides that only apply to the `<Checkout />` component
- */
- checkout?: T;
+ cssLayerName?: string;
 };
+
+export type Appearance<T = Theme> = T &
+ GlobalAppearanceOptions & {
+ /**
+ * Theme overrides that only apply to the `<SignIn/>` component
+ */
+ signIn?: T;
+ /**
+ * Theme overrides that only apply to the `<SignUp/>` component
+ */
+ signUp?: T;
+ /**
+ * Theme overrides that only apply to the `<UserButton/>` component
+ */
+ userButton?: T;
+ /**
+ * Theme overrides that only apply to the `<UserProfile/>` component
+ */
+ userProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<UserVerification/>` component
+ */
+ userVerification?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationSwitcher/>` component
+ */
+ organizationSwitcher?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationList/>` component
+ */
+ organizationList?: T;
+ /**
+ * Theme overrides that only apply to the `<OrganizationProfile/>` component
+ */
+ organizationProfile?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ createOrganization?: T;
+ /**
+ * Theme overrides that only apply to the `<CreateOrganization />` component
+ */
+ oneTap?: T;
+ /**
+ * Theme overrides that only apply to the `<Waitlist />` component
+ */
+ waitlist?: T;
+ /**
+ * Theme overrides that only apply to the `<PricingTable />` component
+ */
+ pricingTable?: T;
+ /**
+ * Theme overrides that only apply to the `<Checkout />` component
+ */
+ checkout?: T;
+ };