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