Add option to disable baseTheme in appearance

Introduces support for setting `baseTheme: false` in appearance and globalAppearance, allowing users to disable the default base theme. Updates tests, documentation, and internal logic to handle the new option and renames `polishedAppearance` to `baseTheme` for clarity.

Author: alexcarpenter

packages/clerk-js/sandbox/app.ts

@@ -192,6 +192,8 @@ function appearanceVariableOptions() {
   const updateVariables = () => {
     void Clerk.__unstable__updateProps({
       appearance: {
+        // Preserve existing appearance properties like baseTheme
+        ...Clerk.__internal_getOption('appearance'),
         variables: Object.fromEntries(
           Object.entries(variableInputs).map(([key, input]) => {
             sessionStorage.setItem(key, input.value);
@@ -349,6 +351,9 @@ void (async () => {
       ...(componentControls.clerk.getProps() ?? {}),
       signInUrl: '/sign-in',
       signUpUrl: '/sign-up',
+      // appearance: {
+      //   baseTheme: false,
+      // },
     });
     renderCurrentRoute();
     updateVariables();

packages/clerk-js/src/ui/polishedAppearance.ts renamed to packages/clerk-js/src/ui/baseTheme.ts

@@ -93,7 +93,7 @@ const inputStyles = (theme: InternalTheme) => ({
   }),
 });
 
-export const polishedAppearance: Appearance = {
+export const baseTheme: Appearance = {
   elements: ({ theme }: { theme: InternalTheme }): Elements => {
     return {
       button: {

packages/clerk-js/src/ui/customizables/__tests__/parseAppearance.test.tsx

@@ -338,7 +338,7 @@ describe('AppearanceProvider layout flows', () => {
     expect(result.current.parsedLayout.socialButtonsVariant).toBe('blockButton');
   });
 
-  it('removes the polishedAppearance when simpleStyles is passed to globalAppearance', () => {
+  it('removes the baseTheme when simpleStyles is passed to globalAppearance', () => {
     const wrapper = ({ children }) => (
       <AppearanceProvider
         appearanceKey='signIn'
@@ -359,7 +359,7 @@ describe('AppearanceProvider layout flows', () => {
     expect(result.current.parsedElements[0]['alert'].backgroundColor).toBe(themeAColor);
   });
 
-  it('removes the polishedAppearance when simpleStyles is passed to appearance', () => {
+  it('removes the baseTheme when simpleStyles is passed to appearance', () => {
     const wrapper = ({ children }) => (
       <AppearanceProvider
         appearanceKey='signIn'
@@ -379,6 +379,72 @@ describe('AppearanceProvider layout flows', () => {
     //notice the "0" index, not "1" as it would be without simpleStyles
     expect(result.current.parsedElements[0]['alert'].backgroundColor).toBe(themeBColor);
   });
+
+  it('removes the baseTheme when baseTheme is set to false in globalAppearance', () => {
+    const wrapper = ({ children }) => (
+      <AppearanceProvider
+        appearanceKey='signIn'
+        globalAppearance={{
+          baseTheme: false,
+          elements: {
+            alert: { backgroundColor: themeAColor },
+          },
+        }}
+      >
+        {children}
+      </AppearanceProvider>
+    );
+
+    const { result } = renderHook(() => useAppearance(), { wrapper });
+    //notice the "0" index, not "1" as it would be without baseTheme
+    expect(result.current.parsedElements[0]['alert'].backgroundColor).toBe(themeAColor);
+  });
+
+  it('removes the baseTheme when baseTheme is set to false in appearance', () => {
+    const wrapper = ({ children }) => (
+      <AppearanceProvider
+        appearanceKey='signIn'
+        appearance={{
+          baseTheme: false,
+          elements: {
+            alert: { backgroundColor: themeBColor },
+          },
+        }}
+      >
+        {children}
+      </AppearanceProvider>
+    );
+
+    const { result } = renderHook(() => useAppearance(), { wrapper });
+    //notice the "0" index, not "1" as it would be without baseTheme
+    expect(result.current.parsedElements[0]['alert'].backgroundColor).toBe(themeBColor);
+  });
+
+  it('removes the baseTheme when baseTheme is set to false even with globalAppearance', () => {
+    const wrapper = ({ children }) => (
+      <AppearanceProvider
+        appearanceKey='signIn'
+        globalAppearance={{
+          elements: {
+            alert: { backgroundColor: themeAColor },
+          },
+        }}
+        appearance={{
+          baseTheme: false,
+          elements: {
+            alert: { backgroundColor: themeBColor },
+          },
+        }}
+      >
+        {children}
+      </AppearanceProvider>
+    );
+
+    const { result } = renderHook(() => useAppearance(), { wrapper });
+    //notice the "0" index for first element and "1" for second - baseTheme is disabled
+    expect(result.current.parsedElements[0]['alert'].backgroundColor).toBe(themeAColor);
+    expect(result.current.parsedElements[1]['alert'].backgroundColor).toBe(themeBColor);
+  });
 });
 
 describe('AppearanceProvider captcha', () => {

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

@@ -1,6 +1,7 @@
 import { fastDeepMergeAndReplace } from '@clerk/shared/utils';
 import type { Appearance, CaptchaAppearanceOptions, DeepPartial, Elements, Layout, Theme } from '@clerk/types';
 
+import { baseTheme } from '../baseTheme';
 import { createInternalTheme, defaultInternalTheme } from '../foundations';
 import type { InternalTheme } from '../styledSystem';
 import {
@@ -80,9 +81,10 @@ export const parseAppearance = (cascade: AppearanceCascade): ParsedAppearance =>
     !appearanceList.find(a => {
       //@ts-expect-error not public api
       return !!a.simpleStyles;
-    })
+    }) &&
+    !appearanceList.find(a => a.baseTheme === false)
   ) {
-    // appearanceList.unshift(polishedAppearance);
+    appearanceList.unshift(baseTheme);
   }
 
   const parsedElements = parseElements(
@@ -103,9 +105,12 @@ const expand = (theme: Theme | undefined, cascade: any[]) => {
     return;
   }
 
-  (Array.isArray(theme.baseTheme) ? theme.baseTheme : [theme.baseTheme]).forEach(baseTheme =>
-    expand(baseTheme as Theme, cascade),
-  );
+  // Only expand baseTheme if it's not false
+  if (theme.baseTheme !== false) {
+    (Array.isArray(theme.baseTheme) ? theme.baseTheme : [theme.baseTheme]).forEach(baseTheme =>
+      expand(baseTheme as Theme, cascade),
+    );
+  }
 
   cascade.push(theme);
 };

packages/types/src/appearance.ts

@@ -812,11 +812,16 @@ export type Theme = {
   /**
    * A theme used as the base theme for the components.
    * For further customisation, you can use the {@link Theme.layout}, {@link Theme.variables} and {@link Theme.elements} props.
+   * Set to `false` to disable the base theme.
    * @example
    * import { dark } from "@clerk/themes";
    * appearance={{ baseTheme: dark }}
+   *
+   * @example
+   * // Disable base theme
+   * appearance={{ baseTheme: false }}
    */
-  baseTheme?: BaseTheme | BaseTheme[];
+  baseTheme?: BaseTheme | BaseTheme[] | false;
   /**
    * Configuration options that affect the layout of the components, allowing
    * customizations that hard to implement with just CSS.