feat(ui): Add flush appearance option

.changeset/card-elevation-option.md

@@ -0,0 +1,7 @@
+---
+"@clerk/ui": minor
+---
+
+Add `elevation` appearance option with `'raised'` (default) and `'flush'` values. When set to `flush`, card-based components render without border, box-shadow, border-radius, outer padding, and footer background, allowing them to sit flat against their container. Applies to `<SignIn />`, `<SignUp />`, `<Waitlist />`, `<CreateOrganization />`, `<OrganizationList />`, `<OAuthConsent />`, `<UserVerification />`, and session task components. Profile and popover components always render as raised. Modal components always render as raised regardless of this setting.
+
+The `cardBox` element exposes a `data-elevation="flush"` attribute when flush is active, giving className-based themes a hook to neutralize their card chrome via attribute selectors. The `shadcn` theme uses this hook to drop its `shadow-sm border` utilities under flush.

packages/clerk-js/sandbox/app.ts

@@ -281,13 +281,26 @@ function otherOptions() {
  localization: document.getElementById('localizationSelect') as HTMLSelectElement,
  };
 
+ const elevationSelect = document.getElementById('elevationSelect') as HTMLSelectElement;
+ const devWarningsToggle = document.getElementById('devWarningsToggle') as HTMLInputElement;
+
  Object.entries(otherOptionsInputs).forEach(([key, input]) => {
  const savedValue = sessionStorage.getItem(key);
  if (savedValue) {
  input.value = savedValue;
  }
  });
 
+ const savedElevation = sessionStorage.getItem('elevation');
+ if (savedElevation) {
+ elevationSelect.value = savedElevation;
+ }
+
+ const savedDevWarnings = sessionStorage.getItem('devWarnings');
+ if (savedDevWarnings !== null) {
+ devWarningsToggle.checked = savedDevWarnings === 'on';
+ }
+
  const updateOtherOptions = () => {
  void Clerk.__internal_updateProps({
  options: Object.fromEntries(
@@ -304,16 +317,40 @@ function otherOptions() {
  });
  };
 
+ const updateAppearanceOptions = () => {
+ sessionStorage.setItem('elevation', elevationSelect.value);
+ sessionStorage.setItem('devWarnings', devWarningsToggle.checked ? 'on' : 'off');
+ const currentAppearance = Clerk.__internal_getOption('appearance') ?? {};
+ void Clerk.__internal_updateProps({
+ appearance: {
+ ...currentAppearance,
+ options: {
+ ...(currentAppearance as any).options,
+ elevation: elevationSelect.value as 'raised' | 'flush',
+ unsafe_disableDevelopmentModeWarnings: !devWarningsToggle.checked,
+ },
+ },
+ });
+ };
+
  Object.values(otherOptionsInputs).forEach(input => {
  input.addEventListener('change', updateOtherOptions);
  });
 
+ elevationSelect.addEventListener('change', updateAppearanceOptions);
+ devWarningsToggle.addEventListener('change', updateAppearanceOptions);
+
  resetOtherOptionsBtn?.addEventListener('click', () => {
  otherOptionsInputs.localization.value = 'enUS';
+ elevationSelect.value = 'raised';
+ devWarningsToggle.checked = true;
+ sessionStorage.removeItem('elevation');
+ sessionStorage.removeItem('devWarnings');
  updateOtherOptions();
+ updateAppearanceOptions();
  });
 
- return { updateOtherOptions };
+ return { updateOtherOptions, updateAppearanceOptions };
 }
 
 const themes: Record<string, unknown> = {
@@ -411,7 +448,7 @@ void (async () => {
  const { updateVariables } = appearanceVariableOptions();
  const { updateTheme } = themeSelector();
  const { updatePreset } = presetSelector();
- const { updateOtherOptions } = otherOptions();
+ const { updateOtherOptions, updateAppearanceOptions } = otherOptions();
 
  const sidebars = document.querySelectorAll('[data-sidebar]');
  document.addEventListener('keydown', e => {
@@ -540,6 +577,15 @@ void (async () => {
  const initialTheme = initialThemeName ? themes[initialThemeName] : undefined;
  const initialPresetName = sessionStorage.getItem('preset') ?? '';
  const initialPreset = initialPresetName ? presets[initialPresetName] : undefined;
+ const initialElevation = sessionStorage.getItem('elevation') as 'raised' | 'flush' | null;
+ const initialDevWarnings = sessionStorage.getItem('devWarnings');
+ const initialAppearanceOptions: Record<string, unknown> = {};
+ if (initialElevation) {
+ initialAppearanceOptions.elevation = initialElevation;
+ }
+ if (initialDevWarnings === 'off') {
+ initialAppearanceOptions.unsafe_disableDevelopmentModeWarnings = true;
+ }
 
  await Clerk.load({
  ...(componentControls.clerk.getProps() ?? {}),
@@ -549,6 +595,7 @@ void (async () => {
  appearance: {
  ...(initialTheme ? { theme: initialTheme } : {}),
  ...presetToAppearance(initialPreset),
+ ...(Object.keys(initialAppearanceOptions).length ? { options: initialAppearanceOptions } : {}),
  },
  });
  renderCurrentRoute();
@@ -560,6 +607,7 @@ void (async () => {
  updateVariables();
  }
  updateOtherOptions();
+ updateAppearanceOptions();
  } else {
  console.error(`Unknown route: "${route}".`);
  }

packages/clerk-js/sandbox/template.html

@@ -33,7 +33,7 @@
  }
  </script>
  </head>
- <body class="flex min-h-full flex-col overflow-x-hidden bg-gray-50 lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
+ <body class="flex min-h-full flex-col overflow-x-hidden bg-white lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
  <div
  data-sidebar
  class="fixed inset-y-0 left-0 w-72 overflow-y-auto border-r border-gray-100 bg-white px-2 py-4 max-lg:hidden"
@@ -436,6 +436,24 @@
  <span class="font-mono text-xs">localization</span>
  <select id="localizationSelect"></select>
  </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">elevation</span>
+ <select
+ id="elevationSelect"
+ class="text-sm"
+ >
+ <option value="raised">raised</option>
+ <option value="flush">flush</option>
+ </select>
+ </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">devWarnings</span>
+ <input
+ type="checkbox"
+ id="devWarningsToggle"
+ checked
+ />
+ </label>
  </fieldset>
  </div>
 

packages/ui/src/customizables/AppearanceContext.tsx

@@ -23,4 +23,4 @@ const AppearanceProvider = (props: AppearanceProviderProps) => {
  return <AppearanceContext.Provider value={ctxValue}>{props.children}</AppearanceContext.Provider>;
 };
 
-export { AppearanceProvider, useAppearance };
+export { AppearanceContext, AppearanceProvider, useAppearance };

packages/ui/src/customizables/__tests__/parseAppearance.test.tsx

@@ -238,6 +238,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -255,6 +256,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(false);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('bottom');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('iconButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the appearance prop', () => {
@@ -272,6 +274,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -289,6 +292,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the globalAppearance and appearance prop', () => {
@@ -306,6 +310,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  appearance={{
@@ -319,6 +324,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'raised',
  },
  }}
  >
@@ -336,6 +342,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('raised');
  });
 
  it('removes the base theme when simpleStyles is passed to globalAppearance', () => {

packages/ui/src/customizables/index.ts

@@ -6,7 +6,7 @@ import { makeResponsive } from './makeResponsive';
 import { sanitizeDomProps } from './sanitizeDomProps';
 
 export * from './Flow';
-export { AppearanceProvider, useAppearance } from './AppearanceContext';
+export { AppearanceContext, AppearanceProvider, useAppearance } from './AppearanceContext';
 export { descriptors } from './elementDescriptors';
 export { localizationKeys, useLocalizations } from '../localization';
 export type { LocalizationKey } from '../localization';

packages/ui/src/customizables/parseAppearance.ts

@@ -52,6 +52,7 @@ const defaultOptions: ParsedOptions = {
  animations: true,
  unsafe_disableDevelopmentModeWarnings: false,
  autoFocus: true,
+ elevation: 'raised',
 };
 
 const defaultCaptchaOptions: ParsedCaptcha = {

packages/ui/src/elements/Card/CardClerkAndPagesTag.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 
 import { useEnvironment } from '../../contexts';
-import { Box, Col, Flex, Icon, Link, Text } from '../../customizables';
+import { Box, Col, descriptors, Flex, Icon, Link, Text } from '../../customizables';
 import { useDevMode } from '../../hooks/useDevMode';
 import { LogoMark } from '../../icons';
 import type { PropsOfComponent, ThemableCssProp } from '../../styledSystem';
@@ -28,6 +28,7 @@ export const CardClerkAndPagesTag = React.memo(
 
  return (
  <Box
+ elementDescriptor={descriptors.footerItem}
  sx={[
  {
  width: '100%',

packages/ui/src/elements/Card/CardRoot.tsx

@@ -1,18 +1,102 @@
 import React from 'react';
 
-import { Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
+import { AppearanceContext, Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
 import type { ElementDescriptor } from '../../customizables/elementDescriptors';
-import type { PropsOfComponent } from '../../styledSystem';
+import type { InternalTheme, PropsOfComponent } from '../../styledSystem';
 import { mqu } from '../../styledSystem';
 import { ApplicationLogo } from '../ApplicationLogo';
 import { useFlowMetadata } from '../contexts';
+import { ModalContext } from '../Modal';
 
-type CardRootProps = PropsOfComponent<typeof Col>;
+// Flush overrides injected into parsedElements after baseTheme but before user overrides.
+const getFlushElements = (t: InternalTheme) => ({
+ cardBox: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ overflow: 'visible',
+ },
+ card: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ backgroundColor: 'transparent',
+ paddingInline: 0,
+ paddingBlock: 0,
+ marginBlockStart: 0,
+ marginInline: 0,
+ },
+ footer: {
+ background: 'transparent',
+ marginTop: t.space.$8,
+ paddingTop: 0,
+ rowGap: t.space.$8,
+ '>:first-of-type': {
+ padding: 0,
+ },
+ '>:not(:first-of-type)': {
+ borderTopWidth: 0,
+ padding: 0,
+ },
+ },
+});
+
+type CardRootProps = PropsOfComponent<typeof Col> & {
+ /**
+ * Override the visual elevation for this card instance.
+ * When omitted, falls back to `appearance.options.elevation` for page-mounted
+ * components, and `'raised'` for modals.
+ * Profile and popover card roots pass `'raised'` explicitly to opt out of flush.
+ */
+ elevation?: 'raised' | 'flush';
+};
 export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props, ref) => {
- const { sx, children, ...rest } = props;
+ const { sx, children, elevation: elevationProp, ...rest } = props;
  const appearance = useAppearance();
  const flowMetadata = useFlowMetadata();
 
+ const rawModalCtx = React.useContext(ModalContext);
+ const isModal = rawModalCtx !== undefined;
+ // Explicit prop wins; modals always raised; otherwise use appearance option
+ const elevation = elevationProp ?? (isModal ? 'raised' : appearance.parsedOptions.elevation);
+ const isFlush = elevation === 'flush';
+
+ const augmentedAppearance = React.useMemo(() => {
+ if (!isFlush) {
+ return appearance;
+ }
+ const flushElements = getFlushElements(appearance.parsedInternalTheme);
+ const newParsedElements = [appearance.parsedElements[0], flushElements, ...appearance.parsedElements.slice(1)];
+ return { ...appearance, parsedElements: newParsedElements };
+ }, [appearance, isFlush]);
+
+ const cardBox = (
+ <Col
+ elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
+ className={generateFlowPartClassname(flowMetadata)}
+ ref={ref}
+ data-elevation={isFlush ? 'flush' : undefined}
+ sx={[
+ t => ({
+ isolation: 'isolate',
+ maxWidth: `calc(100vw - ${t.sizes.$10})`,
+ width: t.sizes.$100,
+ borderWidth: t.borderWidths.$normal,
+ borderStyle: t.borderStyles.$solid,
+ borderColor: t.colors.$borderAlpha150,
+ borderRadius: t.radii.$xl,
+ color: t.colors.$colorForeground,
+ position: 'relative',
+ overflow: 'hidden',
+ }),
+ sx,
+ ]}
+ {...rest}
+ >
+ {children}
+ </Col>
+ );
+
  return (
  <>
  {appearance.parsedOptions.logoPlacement === 'outside' && (
@@ -25,33 +109,11 @@ export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props,
  })}
  />
  )}
- <Col
- elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
- className={generateFlowPartClassname(flowMetadata)}
- ref={ref}
- sx={[
- t => ({
- /**
- * All components should create their own stack context
- * https://developer.mozilla.org/en-US/docs/Web/CSS/isolation
- */
- isolation: 'isolate',
- maxWidth: `calc(100vw - ${t.sizes.$10})`,
- width: t.sizes.$100,
- borderWidth: t.borderWidths.$normal,
- borderStyle: t.borderStyles.$solid,
- borderColor: t.colors.$borderAlpha150,
- borderRadius: t.radii.$xl,
- color: t.colors.$colorForeground,
- position: 'relative',
- overflow: 'hidden',
- }),
- sx,
- ]}
- {...rest}
- >
- {children}
- </Col>
+ {isFlush ? (
+ <AppearanceContext.Provider value={{ value: augmentedAppearance }}>{cardBox}</AppearanceContext.Provider>
+ ) : (
+ cardBox
+ )}
  </>
  );
 });

.changeset/card-elevation-option.md

@@ -0,0 +1,7 @@
+---
+"@clerk/ui": minor
+---
+
+Add `elevation` appearance option with `'raised'` (default) and `'flush'` values. When set to `flush`, card-based components render without border, box-shadow, border-radius, outer padding, and footer background, allowing them to sit flat against their container. Applies to `<SignIn />`, `<SignUp />`, `<Waitlist />`, `<CreateOrganization />`, `<OrganizationList />`, `<OAuthConsent />`, `<UserVerification />`, and session task components. Profile and popover components always render as raised. Modal components always render as raised regardless of this setting.
+
+The `cardBox` element exposes a `data-elevation="flush"` attribute when flush is active, giving className-based themes a hook to neutralize their card chrome via attribute selectors. The `shadcn` theme uses this hook to drop its `shadow-sm border` utilities under flush.

packages/clerk-js/sandbox/app.ts

@@ -281,13 +281,26 @@ function otherOptions() {
  localization: document.getElementById('localizationSelect') as HTMLSelectElement,
  };
 
+ const elevationSelect = document.getElementById('elevationSelect') as HTMLSelectElement;
+ const devWarningsToggle = document.getElementById('devWarningsToggle') as HTMLInputElement;
+
  Object.entries(otherOptionsInputs).forEach(([key, input]) => {
  const savedValue = sessionStorage.getItem(key);
  if (savedValue) {
  input.value = savedValue;
  }
  });
 
+ const savedElevation = sessionStorage.getItem('elevation');
+ if (savedElevation) {
+ elevationSelect.value = savedElevation;
+ }
+
+ const savedDevWarnings = sessionStorage.getItem('devWarnings');
+ if (savedDevWarnings !== null) {
+ devWarningsToggle.checked = savedDevWarnings === 'on';
+ }
+
  const updateOtherOptions = () => {
  void Clerk.__internal_updateProps({
  options: Object.fromEntries(
@@ -304,16 +317,40 @@ function otherOptions() {
  });
  };
 
+ const updateAppearanceOptions = () => {
+ sessionStorage.setItem('elevation', elevationSelect.value);
+ sessionStorage.setItem('devWarnings', devWarningsToggle.checked ? 'on' : 'off');
+ const currentAppearance = Clerk.__internal_getOption('appearance') ?? {};
+ void Clerk.__internal_updateProps({
+ appearance: {
+ ...currentAppearance,
+ options: {
+ ...(currentAppearance as any).options,
+ elevation: elevationSelect.value as 'raised' | 'flush',
+ unsafe_disableDevelopmentModeWarnings: !devWarningsToggle.checked,
+ },
+ },
+ });
+ };
+
  Object.values(otherOptionsInputs).forEach(input => {
  input.addEventListener('change', updateOtherOptions);
  });
 
+ elevationSelect.addEventListener('change', updateAppearanceOptions);
+ devWarningsToggle.addEventListener('change', updateAppearanceOptions);
+
  resetOtherOptionsBtn?.addEventListener('click', () => {
  otherOptionsInputs.localization.value = 'enUS';
+ elevationSelect.value = 'raised';
+ devWarningsToggle.checked = true;
+ sessionStorage.removeItem('elevation');
+ sessionStorage.removeItem('devWarnings');
  updateOtherOptions();
+ updateAppearanceOptions();
  });
 
- return { updateOtherOptions };
+ return { updateOtherOptions, updateAppearanceOptions };
 }
 
 const themes: Record<string, unknown> = {
@@ -411,7 +448,7 @@ void (async () => {
  const { updateVariables } = appearanceVariableOptions();
  const { updateTheme } = themeSelector();
  const { updatePreset } = presetSelector();
- const { updateOtherOptions } = otherOptions();
+ const { updateOtherOptions, updateAppearanceOptions } = otherOptions();
 
  const sidebars = document.querySelectorAll('[data-sidebar]');
  document.addEventListener('keydown', e => {
@@ -540,6 +577,15 @@ void (async () => {
  const initialTheme = initialThemeName ? themes[initialThemeName] : undefined;
  const initialPresetName = sessionStorage.getItem('preset') ?? '';
  const initialPreset = initialPresetName ? presets[initialPresetName] : undefined;
+ const initialElevation = sessionStorage.getItem('elevation') as 'raised' | 'flush' | null;
+ const initialDevWarnings = sessionStorage.getItem('devWarnings');
+ const initialAppearanceOptions: Record<string, unknown> = {};
+ if (initialElevation) {
+ initialAppearanceOptions.elevation = initialElevation;
+ }
+ if (initialDevWarnings === 'off') {
+ initialAppearanceOptions.unsafe_disableDevelopmentModeWarnings = true;
+ }
 
  await Clerk.load({
  ...(componentControls.clerk.getProps() ?? {}),
@@ -549,6 +595,7 @@ void (async () => {
  appearance: {
  ...(initialTheme ? { theme: initialTheme } : {}),
  ...presetToAppearance(initialPreset),
+ ...(Object.keys(initialAppearanceOptions).length ? { options: initialAppearanceOptions } : {}),
  },
  });
  renderCurrentRoute();
@@ -560,6 +607,7 @@ void (async () => {
  updateVariables();
  }
  updateOtherOptions();
+ updateAppearanceOptions();
  } else {
  console.error(`Unknown route: "${route}".`);
  }

packages/clerk-js/sandbox/template.html

@@ -33,7 +33,7 @@
  }
  </script>
  </head>
- <body class="flex min-h-full flex-col overflow-x-hidden bg-gray-50 lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
+ <body class="flex min-h-full flex-col overflow-x-hidden bg-white lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
  <div
  data-sidebar
  class="fixed inset-y-0 left-0 w-72 overflow-y-auto border-r border-gray-100 bg-white px-2 py-4 max-lg:hidden"
@@ -436,6 +436,24 @@
  <span class="font-mono text-xs">localization</span>
  <select id="localizationSelect"></select>
  </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">elevation</span>
+ <select
+ id="elevationSelect"
+ class="text-sm"
+ >
+ <option value="raised">raised</option>
+ <option value="flush">flush</option>
+ </select>
+ </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">devWarnings</span>
+ <input
+ type="checkbox"
+ id="devWarningsToggle"
+ checked
+ />
+ </label>
  </fieldset>
  </div>
 

packages/ui/src/customizables/AppearanceContext.tsx

@@ -23,4 +23,4 @@ const AppearanceProvider = (props: AppearanceProviderProps) => {
  return <AppearanceContext.Provider value={ctxValue}>{props.children}</AppearanceContext.Provider>;
 };
 
-export { AppearanceProvider, useAppearance };
+export { AppearanceContext, AppearanceProvider, useAppearance };

packages/ui/src/customizables/__tests__/parseAppearance.test.tsx

@@ -238,6 +238,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -255,6 +256,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(false);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('bottom');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('iconButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the appearance prop', () => {
@@ -272,6 +274,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -289,6 +292,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the globalAppearance and appearance prop', () => {
@@ -306,6 +310,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  appearance={{
@@ -319,6 +324,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'raised',
  },
  }}
  >
@@ -336,6 +342,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('raised');
  });
 
  it('removes the base theme when simpleStyles is passed to globalAppearance', () => {

packages/ui/src/customizables/index.ts

@@ -6,7 +6,7 @@ import { makeResponsive } from './makeResponsive';
 import { sanitizeDomProps } from './sanitizeDomProps';
 
 export * from './Flow';
-export { AppearanceProvider, useAppearance } from './AppearanceContext';
+export { AppearanceContext, AppearanceProvider, useAppearance } from './AppearanceContext';
 export { descriptors } from './elementDescriptors';
 export { localizationKeys, useLocalizations } from '../localization';
 export type { LocalizationKey } from '../localization';

packages/ui/src/customizables/parseAppearance.ts

@@ -52,6 +52,7 @@ const defaultOptions: ParsedOptions = {
  animations: true,
  unsafe_disableDevelopmentModeWarnings: false,
  autoFocus: true,
+ elevation: 'raised',
 };
 
 const defaultCaptchaOptions: ParsedCaptcha = {

packages/ui/src/elements/Card/CardClerkAndPagesTag.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 
 import { useEnvironment } from '../../contexts';
-import { Box, Col, Flex, Icon, Link, Text } from '../../customizables';
+import { Box, Col, descriptors, Flex, Icon, Link, Text } from '../../customizables';
 import { useDevMode } from '../../hooks/useDevMode';
 import { LogoMark } from '../../icons';
 import type { PropsOfComponent, ThemableCssProp } from '../../styledSystem';
@@ -28,6 +28,7 @@ export const CardClerkAndPagesTag = React.memo(
 
  return (
  <Box
+ elementDescriptor={descriptors.footerItem}
  sx={[
  {
  width: '100%',

packages/ui/src/elements/Card/CardRoot.tsx

@@ -1,18 +1,102 @@
 import React from 'react';
 
-import { Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
+import { AppearanceContext, Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
 import type { ElementDescriptor } from '../../customizables/elementDescriptors';
-import type { PropsOfComponent } from '../../styledSystem';
+import type { InternalTheme, PropsOfComponent } from '../../styledSystem';
 import { mqu } from '../../styledSystem';
 import { ApplicationLogo } from '../ApplicationLogo';
 import { useFlowMetadata } from '../contexts';
+import { ModalContext } from '../Modal';
 
-type CardRootProps = PropsOfComponent<typeof Col>;
+// Flush overrides injected into parsedElements after baseTheme but before user overrides.
+const getFlushElements = (t: InternalTheme) => ({
+ cardBox: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ overflow: 'visible',
+ },
+ card: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ backgroundColor: 'transparent',
+ paddingInline: 0,
+ paddingBlock: 0,
+ marginBlockStart: 0,
+ marginInline: 0,
+ },
+ footer: {
+ background: 'transparent',
+ marginTop: t.space.$8,
+ paddingTop: 0,
+ rowGap: t.space.$8,
+ '>:first-of-type': {
+ padding: 0,
+ },
+ '>:not(:first-of-type)': {
+ borderTopWidth: 0,
+ padding: 0,
+ },
+ },
+});
+
+type CardRootProps = PropsOfComponent<typeof Col> & {
+ /**
+ * Override the visual elevation for this card instance.
+ * When omitted, falls back to `appearance.options.elevation` for page-mounted
+ * components, and `'raised'` for modals.
+ * Profile and popover card roots pass `'raised'` explicitly to opt out of flush.
+ */
+ elevation?: 'raised' | 'flush';
+};
 export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props, ref) => {
- const { sx, children, ...rest } = props;
+ const { sx, children, elevation: elevationProp, ...rest } = props;
  const appearance = useAppearance();
  const flowMetadata = useFlowMetadata();
 
+ const rawModalCtx = React.useContext(ModalContext);
+ const isModal = rawModalCtx !== undefined;
+ // Explicit prop wins; modals always raised; otherwise use appearance option
+ const elevation = elevationProp ?? (isModal ? 'raised' : appearance.parsedOptions.elevation);
+ const isFlush = elevation === 'flush';
+
+ const augmentedAppearance = React.useMemo(() => {
+ if (!isFlush) {
+ return appearance;
+ }
+ const flushElements = getFlushElements(appearance.parsedInternalTheme);
+ const newParsedElements = [appearance.parsedElements[0], flushElements, ...appearance.parsedElements.slice(1)];
+ return { ...appearance, parsedElements: newParsedElements };
+ }, [appearance, isFlush]);
+
+ const cardBox = (
+ <Col
+ elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
+ className={generateFlowPartClassname(flowMetadata)}
+ ref={ref}
+ data-elevation={isFlush ? 'flush' : undefined}
+ sx={[
+ t => ({
+ isolation: 'isolate',
+ maxWidth: `calc(100vw - ${t.sizes.$10})`,
+ width: t.sizes.$100,
+ borderWidth: t.borderWidths.$normal,
+ borderStyle: t.borderStyles.$solid,
+ borderColor: t.colors.$borderAlpha150,
+ borderRadius: t.radii.$xl,
+ color: t.colors.$colorForeground,
+ position: 'relative',
+ overflow: 'hidden',
+ }),
+ sx,
+ ]}
+ {...rest}
+ >
+ {children}
+ </Col>
+ );
+
  return (
  <>
  {appearance.parsedOptions.logoPlacement === 'outside' && (
@@ -25,33 +109,11 @@ export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props,
  })}
  />
  )}
- <Col
- elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
- className={generateFlowPartClassname(flowMetadata)}
- ref={ref}
- sx={[
- t => ({
- /**
- * All components should create their own stack context
- * https://developer.mozilla.org/en-US/docs/Web/CSS/isolation
- */
- isolation: 'isolate',
- maxWidth: `calc(100vw - ${t.sizes.$10})`,
- width: t.sizes.$100,
- borderWidth: t.borderWidths.$normal,
- borderStyle: t.borderStyles.$solid,
- borderColor: t.colors.$borderAlpha150,
- borderRadius: t.radii.$xl,
- color: t.colors.$colorForeground,
- position: 'relative',
- overflow: 'hidden',
- }),
- sx,
- ]}
- {...rest}
- >
- {children}
- </Col>
+ {isFlush ? (
+ <AppearanceContext.Provider value={{ value: augmentedAppearance }}>{cardBox}</AppearanceContext.Provider>
+ ) : (
+ cardBox
+ )}
  </>
  );
 });

.changeset/card-elevation-option.md

@@ -0,0 +1,7 @@
+---
+"@clerk/ui": minor
+---
+
+Add `elevation` appearance option with `'raised'` (default) and `'flush'` values. When set to `flush`, card-based components render without border, box-shadow, border-radius, outer padding, and footer background, allowing them to sit flat against their container. Applies to `<SignIn />`, `<SignUp />`, `<Waitlist />`, `<CreateOrganization />`, `<OrganizationList />`, `<OAuthConsent />`, `<UserVerification />`, and session task components. Profile and popover components always render as raised. Modal components always render as raised regardless of this setting.
+
+The `cardBox` element exposes a `data-elevation="flush"` attribute when flush is active, giving className-based themes a hook to neutralize their card chrome via attribute selectors. The `shadcn` theme uses this hook to drop its `shadow-sm border` utilities under flush.

packages/clerk-js/sandbox/app.ts

@@ -281,13 +281,26 @@ function otherOptions() {
  localization: document.getElementById('localizationSelect') as HTMLSelectElement,
  };
 
+ const elevationSelect = document.getElementById('elevationSelect') as HTMLSelectElement;
+ const devWarningsToggle = document.getElementById('devWarningsToggle') as HTMLInputElement;
+
  Object.entries(otherOptionsInputs).forEach(([key, input]) => {
  const savedValue = sessionStorage.getItem(key);
  if (savedValue) {
  input.value = savedValue;
  }
  });
 
+ const savedElevation = sessionStorage.getItem('elevation');
+ if (savedElevation) {
+ elevationSelect.value = savedElevation;
+ }
+
+ const savedDevWarnings = sessionStorage.getItem('devWarnings');
+ if (savedDevWarnings !== null) {
+ devWarningsToggle.checked = savedDevWarnings === 'on';
+ }
+
  const updateOtherOptions = () => {
  void Clerk.__internal_updateProps({
  options: Object.fromEntries(
@@ -304,16 +317,40 @@ function otherOptions() {
  });
  };
 
+ const updateAppearanceOptions = () => {
+ sessionStorage.setItem('elevation', elevationSelect.value);
+ sessionStorage.setItem('devWarnings', devWarningsToggle.checked ? 'on' : 'off');
+ const currentAppearance = Clerk.__internal_getOption('appearance') ?? {};
+ void Clerk.__internal_updateProps({
+ appearance: {
+ ...currentAppearance,
+ options: {
+ ...(currentAppearance as any).options,
+ elevation: elevationSelect.value as 'raised' | 'flush',
+ unsafe_disableDevelopmentModeWarnings: !devWarningsToggle.checked,
+ },
+ },
+ });
+ };
+
  Object.values(otherOptionsInputs).forEach(input => {
  input.addEventListener('change', updateOtherOptions);
  });
 
+ elevationSelect.addEventListener('change', updateAppearanceOptions);
+ devWarningsToggle.addEventListener('change', updateAppearanceOptions);
+
  resetOtherOptionsBtn?.addEventListener('click', () => {
  otherOptionsInputs.localization.value = 'enUS';
+ elevationSelect.value = 'raised';
+ devWarningsToggle.checked = true;
+ sessionStorage.removeItem('elevation');
+ sessionStorage.removeItem('devWarnings');
  updateOtherOptions();
+ updateAppearanceOptions();
  });
 
- return { updateOtherOptions };
+ return { updateOtherOptions, updateAppearanceOptions };
 }
 
 const themes: Record<string, unknown> = {
@@ -411,7 +448,7 @@ void (async () => {
  const { updateVariables } = appearanceVariableOptions();
  const { updateTheme } = themeSelector();
  const { updatePreset } = presetSelector();
- const { updateOtherOptions } = otherOptions();
+ const { updateOtherOptions, updateAppearanceOptions } = otherOptions();
 
  const sidebars = document.querySelectorAll('[data-sidebar]');
  document.addEventListener('keydown', e => {
@@ -540,6 +577,15 @@ void (async () => {
  const initialTheme = initialThemeName ? themes[initialThemeName] : undefined;
  const initialPresetName = sessionStorage.getItem('preset') ?? '';
  const initialPreset = initialPresetName ? presets[initialPresetName] : undefined;
+ const initialElevation = sessionStorage.getItem('elevation') as 'raised' | 'flush' | null;
+ const initialDevWarnings = sessionStorage.getItem('devWarnings');
+ const initialAppearanceOptions: Record<string, unknown> = {};
+ if (initialElevation) {
+ initialAppearanceOptions.elevation = initialElevation;
+ }
+ if (initialDevWarnings === 'off') {
+ initialAppearanceOptions.unsafe_disableDevelopmentModeWarnings = true;
+ }
 
  await Clerk.load({
  ...(componentControls.clerk.getProps() ?? {}),
@@ -549,6 +595,7 @@ void (async () => {
  appearance: {
  ...(initialTheme ? { theme: initialTheme } : {}),
  ...presetToAppearance(initialPreset),
+ ...(Object.keys(initialAppearanceOptions).length ? { options: initialAppearanceOptions } : {}),
  },
  });
  renderCurrentRoute();
@@ -560,6 +607,7 @@ void (async () => {
  updateVariables();
  }
  updateOtherOptions();
+ updateAppearanceOptions();
  } else {
  console.error(`Unknown route: "${route}".`);
  }

packages/clerk-js/sandbox/template.html

@@ -33,7 +33,7 @@
  }
  </script>
  </head>
- <body class="flex min-h-full flex-col overflow-x-hidden bg-gray-50 lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
+ <body class="flex min-h-full flex-col overflow-x-hidden bg-white lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
  <div
  data-sidebar
  class="fixed inset-y-0 left-0 w-72 overflow-y-auto border-r border-gray-100 bg-white px-2 py-4 max-lg:hidden"
@@ -436,6 +436,24 @@
  <span class="font-mono text-xs">localization</span>
  <select id="localizationSelect"></select>
  </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">elevation</span>
+ <select
+ id="elevationSelect"
+ class="text-sm"
+ >
+ <option value="raised">raised</option>
+ <option value="flush">flush</option>
+ </select>
+ </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">devWarnings</span>
+ <input
+ type="checkbox"
+ id="devWarningsToggle"
+ checked
+ />
+ </label>
  </fieldset>
  </div>
 

packages/ui/src/customizables/AppearanceContext.tsx

@@ -23,4 +23,4 @@ const AppearanceProvider = (props: AppearanceProviderProps) => {
  return <AppearanceContext.Provider value={ctxValue}>{props.children}</AppearanceContext.Provider>;
 };
 
-export { AppearanceProvider, useAppearance };
+export { AppearanceContext, AppearanceProvider, useAppearance };

packages/ui/src/customizables/__tests__/parseAppearance.test.tsx

@@ -238,6 +238,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -255,6 +256,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(false);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('bottom');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('iconButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the appearance prop', () => {
@@ -272,6 +274,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -289,6 +292,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the globalAppearance and appearance prop', () => {
@@ -306,6 +310,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  appearance={{
@@ -319,6 +324,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'raised',
  },
  }}
  >
@@ -336,6 +342,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('raised');
  });
 
  it('removes the base theme when simpleStyles is passed to globalAppearance', () => {

packages/ui/src/customizables/index.ts

@@ -6,7 +6,7 @@ import { makeResponsive } from './makeResponsive';
 import { sanitizeDomProps } from './sanitizeDomProps';
 
 export * from './Flow';
-export { AppearanceProvider, useAppearance } from './AppearanceContext';
+export { AppearanceContext, AppearanceProvider, useAppearance } from './AppearanceContext';
 export { descriptors } from './elementDescriptors';
 export { localizationKeys, useLocalizations } from '../localization';
 export type { LocalizationKey } from '../localization';

packages/ui/src/customizables/parseAppearance.ts

@@ -52,6 +52,7 @@ const defaultOptions: ParsedOptions = {
  animations: true,
  unsafe_disableDevelopmentModeWarnings: false,
  autoFocus: true,
+ elevation: 'raised',
 };
 
 const defaultCaptchaOptions: ParsedCaptcha = {

packages/ui/src/elements/Card/CardClerkAndPagesTag.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 
 import { useEnvironment } from '../../contexts';
-import { Box, Col, Flex, Icon, Link, Text } from '../../customizables';
+import { Box, Col, descriptors, Flex, Icon, Link, Text } from '../../customizables';
 import { useDevMode } from '../../hooks/useDevMode';
 import { LogoMark } from '../../icons';
 import type { PropsOfComponent, ThemableCssProp } from '../../styledSystem';
@@ -28,6 +28,7 @@ export const CardClerkAndPagesTag = React.memo(
 
  return (
  <Box
+ elementDescriptor={descriptors.footerItem}
  sx={[
  {
  width: '100%',

packages/ui/src/elements/Card/CardRoot.tsx

@@ -1,18 +1,102 @@
 import React from 'react';
 
-import { Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
+import { AppearanceContext, Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
 import type { ElementDescriptor } from '../../customizables/elementDescriptors';
-import type { PropsOfComponent } from '../../styledSystem';
+import type { InternalTheme, PropsOfComponent } from '../../styledSystem';
 import { mqu } from '../../styledSystem';
 import { ApplicationLogo } from '../ApplicationLogo';
 import { useFlowMetadata } from '../contexts';
+import { ModalContext } from '../Modal';
 
-type CardRootProps = PropsOfComponent<typeof Col>;
+// Flush overrides injected into parsedElements after baseTheme but before user overrides.
+const getFlushElements = (t: InternalTheme) => ({
+ cardBox: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ overflow: 'visible',
+ },
+ card: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ backgroundColor: 'transparent',
+ paddingInline: 0,
+ paddingBlock: 0,
+ marginBlockStart: 0,
+ marginInline: 0,
+ },
+ footer: {
+ background: 'transparent',
+ marginTop: t.space.$8,
+ paddingTop: 0,
+ rowGap: t.space.$8,
+ '>:first-of-type': {
+ padding: 0,
+ },
+ '>:not(:first-of-type)': {
+ borderTopWidth: 0,
+ padding: 0,
+ },
+ },
+});
+
+type CardRootProps = PropsOfComponent<typeof Col> & {
+ /**
+ * Override the visual elevation for this card instance.
+ * When omitted, falls back to `appearance.options.elevation` for page-mounted
+ * components, and `'raised'` for modals.
+ * Profile and popover card roots pass `'raised'` explicitly to opt out of flush.
+ */
+ elevation?: 'raised' | 'flush';
+};
 export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props, ref) => {
- const { sx, children, ...rest } = props;
+ const { sx, children, elevation: elevationProp, ...rest } = props;
  const appearance = useAppearance();
  const flowMetadata = useFlowMetadata();
 
+ const rawModalCtx = React.useContext(ModalContext);
+ const isModal = rawModalCtx !== undefined;
+ // Explicit prop wins; modals always raised; otherwise use appearance option
+ const elevation = elevationProp ?? (isModal ? 'raised' : appearance.parsedOptions.elevation);
+ const isFlush = elevation === 'flush';
+
+ const augmentedAppearance = React.useMemo(() => {
+ if (!isFlush) {
+ return appearance;
+ }
+ const flushElements = getFlushElements(appearance.parsedInternalTheme);
+ const newParsedElements = [appearance.parsedElements[0], flushElements, ...appearance.parsedElements.slice(1)];
+ return { ...appearance, parsedElements: newParsedElements };
+ }, [appearance, isFlush]);
+
+ const cardBox = (
+ <Col
+ elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
+ className={generateFlowPartClassname(flowMetadata)}
+ ref={ref}
+ data-elevation={isFlush ? 'flush' : undefined}
+ sx={[
+ t => ({
+ isolation: 'isolate',
+ maxWidth: `calc(100vw - ${t.sizes.$10})`,
+ width: t.sizes.$100,
+ borderWidth: t.borderWidths.$normal,
+ borderStyle: t.borderStyles.$solid,
+ borderColor: t.colors.$borderAlpha150,
+ borderRadius: t.radii.$xl,
+ color: t.colors.$colorForeground,
+ position: 'relative',
+ overflow: 'hidden',
+ }),
+ sx,
+ ]}
+ {...rest}
+ >
+ {children}
+ </Col>
+ );
+
  return (
  <>
  {appearance.parsedOptions.logoPlacement === 'outside' && (
@@ -25,33 +109,11 @@ export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props,
  })}
  />
  )}
- <Col
- elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
- className={generateFlowPartClassname(flowMetadata)}
- ref={ref}
- sx={[
- t => ({
- /**
- * All components should create their own stack context
- * https://developer.mozilla.org/en-US/docs/Web/CSS/isolation
- */
- isolation: 'isolate',
- maxWidth: `calc(100vw - ${t.sizes.$10})`,
- width: t.sizes.$100,
- borderWidth: t.borderWidths.$normal,
- borderStyle: t.borderStyles.$solid,
- borderColor: t.colors.$borderAlpha150,
- borderRadius: t.radii.$xl,
- color: t.colors.$colorForeground,
- position: 'relative',
- overflow: 'hidden',
- }),
- sx,
- ]}
- {...rest}
- >
- {children}
- </Col>
+ {isFlush ? (
+ <AppearanceContext.Provider value={{ value: augmentedAppearance }}>{cardBox}</AppearanceContext.Provider>
+ ) : (
+ cardBox
+ )}
  </>
  );
 });

.changeset/card-elevation-option.md

@@ -0,0 +1,7 @@
+---
+"@clerk/ui": minor
+---
+
+Add `elevation` appearance option with `'raised'` (default) and `'flush'` values. When set to `flush`, card-based components render without border, box-shadow, border-radius, outer padding, and footer background, allowing them to sit flat against their container. Applies to `<SignIn />`, `<SignUp />`, `<Waitlist />`, `<CreateOrganization />`, `<OrganizationList />`, `<OAuthConsent />`, `<UserVerification />`, and session task components. Profile and popover components always render as raised. Modal components always render as raised regardless of this setting.
+
+The `cardBox` element exposes a `data-elevation="flush"` attribute when flush is active, giving className-based themes a hook to neutralize their card chrome via attribute selectors. The `shadcn` theme uses this hook to drop its `shadow-sm border` utilities under flush.

packages/clerk-js/sandbox/app.ts

@@ -281,13 +281,26 @@ function otherOptions() {
  localization: document.getElementById('localizationSelect') as HTMLSelectElement,
  };
 
+ const elevationSelect = document.getElementById('elevationSelect') as HTMLSelectElement;
+ const devWarningsToggle = document.getElementById('devWarningsToggle') as HTMLInputElement;
+
  Object.entries(otherOptionsInputs).forEach(([key, input]) => {
  const savedValue = sessionStorage.getItem(key);
  if (savedValue) {
  input.value = savedValue;
  }
  });
 
+ const savedElevation = sessionStorage.getItem('elevation');
+ if (savedElevation) {
+ elevationSelect.value = savedElevation;
+ }
+
+ const savedDevWarnings = sessionStorage.getItem('devWarnings');
+ if (savedDevWarnings !== null) {
+ devWarningsToggle.checked = savedDevWarnings === 'on';
+ }
+
  const updateOtherOptions = () => {
  void Clerk.__internal_updateProps({
  options: Object.fromEntries(
@@ -304,16 +317,40 @@ function otherOptions() {
  });
  };
 
+ const updateAppearanceOptions = () => {
+ sessionStorage.setItem('elevation', elevationSelect.value);
+ sessionStorage.setItem('devWarnings', devWarningsToggle.checked ? 'on' : 'off');
+ const currentAppearance = Clerk.__internal_getOption('appearance') ?? {};
+ void Clerk.__internal_updateProps({
+ appearance: {
+ ...currentAppearance,
+ options: {
+ ...(currentAppearance as any).options,
+ elevation: elevationSelect.value as 'raised' | 'flush',
+ unsafe_disableDevelopmentModeWarnings: !devWarningsToggle.checked,
+ },
+ },
+ });
+ };
+
  Object.values(otherOptionsInputs).forEach(input => {
  input.addEventListener('change', updateOtherOptions);
  });
 
+ elevationSelect.addEventListener('change', updateAppearanceOptions);
+ devWarningsToggle.addEventListener('change', updateAppearanceOptions);
+
  resetOtherOptionsBtn?.addEventListener('click', () => {
  otherOptionsInputs.localization.value = 'enUS';
+ elevationSelect.value = 'raised';
+ devWarningsToggle.checked = true;
+ sessionStorage.removeItem('elevation');
+ sessionStorage.removeItem('devWarnings');
  updateOtherOptions();
+ updateAppearanceOptions();
  });
 
- return { updateOtherOptions };
+ return { updateOtherOptions, updateAppearanceOptions };
 }
 
 const themes: Record<string, unknown> = {
@@ -411,7 +448,7 @@ void (async () => {
  const { updateVariables } = appearanceVariableOptions();
  const { updateTheme } = themeSelector();
  const { updatePreset } = presetSelector();
- const { updateOtherOptions } = otherOptions();
+ const { updateOtherOptions, updateAppearanceOptions } = otherOptions();
 
  const sidebars = document.querySelectorAll('[data-sidebar]');
  document.addEventListener('keydown', e => {
@@ -540,6 +577,15 @@ void (async () => {
  const initialTheme = initialThemeName ? themes[initialThemeName] : undefined;
  const initialPresetName = sessionStorage.getItem('preset') ?? '';
  const initialPreset = initialPresetName ? presets[initialPresetName] : undefined;
+ const initialElevation = sessionStorage.getItem('elevation') as 'raised' | 'flush' | null;
+ const initialDevWarnings = sessionStorage.getItem('devWarnings');
+ const initialAppearanceOptions: Record<string, unknown> = {};
+ if (initialElevation) {
+ initialAppearanceOptions.elevation = initialElevation;
+ }
+ if (initialDevWarnings === 'off') {
+ initialAppearanceOptions.unsafe_disableDevelopmentModeWarnings = true;
+ }
 
  await Clerk.load({
  ...(componentControls.clerk.getProps() ?? {}),
@@ -549,6 +595,7 @@ void (async () => {
  appearance: {
  ...(initialTheme ? { theme: initialTheme } : {}),
  ...presetToAppearance(initialPreset),
+ ...(Object.keys(initialAppearanceOptions).length ? { options: initialAppearanceOptions } : {}),
  },
  });
  renderCurrentRoute();
@@ -560,6 +607,7 @@ void (async () => {
  updateVariables();
  }
  updateOtherOptions();
+ updateAppearanceOptions();
  } else {
  console.error(`Unknown route: "${route}".`);
  }

packages/clerk-js/sandbox/template.html

@@ -33,7 +33,7 @@
  }
  </script>
  </head>
- <body class="flex min-h-full flex-col overflow-x-hidden bg-gray-50 lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
+ <body class="flex min-h-full flex-col overflow-x-hidden bg-white lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
  <div
  data-sidebar
  class="fixed inset-y-0 left-0 w-72 overflow-y-auto border-r border-gray-100 bg-white px-2 py-4 max-lg:hidden"
@@ -436,6 +436,24 @@
  <span class="font-mono text-xs">localization</span>
  <select id="localizationSelect"></select>
  </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">elevation</span>
+ <select
+ id="elevationSelect"
+ class="text-sm"
+ >
+ <option value="raised">raised</option>
+ <option value="flush">flush</option>
+ </select>
+ </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">devWarnings</span>
+ <input
+ type="checkbox"
+ id="devWarningsToggle"
+ checked
+ />
+ </label>
  </fieldset>
  </div>
 

packages/ui/src/customizables/AppearanceContext.tsx

@@ -23,4 +23,4 @@ const AppearanceProvider = (props: AppearanceProviderProps) => {
  return <AppearanceContext.Provider value={ctxValue}>{props.children}</AppearanceContext.Provider>;
 };
 
-export { AppearanceProvider, useAppearance };
+export { AppearanceContext, AppearanceProvider, useAppearance };

packages/ui/src/customizables/__tests__/parseAppearance.test.tsx

@@ -238,6 +238,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -255,6 +256,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(false);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('bottom');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('iconButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the appearance prop', () => {
@@ -272,6 +274,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -289,6 +292,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the globalAppearance and appearance prop', () => {
@@ -306,6 +310,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  appearance={{
@@ -319,6 +324,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'raised',
  },
  }}
  >
@@ -336,6 +342,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('raised');
  });
 
  it('removes the base theme when simpleStyles is passed to globalAppearance', () => {

packages/ui/src/customizables/index.ts

@@ -6,7 +6,7 @@ import { makeResponsive } from './makeResponsive';
 import { sanitizeDomProps } from './sanitizeDomProps';
 
 export * from './Flow';
-export { AppearanceProvider, useAppearance } from './AppearanceContext';
+export { AppearanceContext, AppearanceProvider, useAppearance } from './AppearanceContext';
 export { descriptors } from './elementDescriptors';
 export { localizationKeys, useLocalizations } from '../localization';
 export type { LocalizationKey } from '../localization';

packages/ui/src/customizables/parseAppearance.ts

@@ -52,6 +52,7 @@ const defaultOptions: ParsedOptions = {
  animations: true,
  unsafe_disableDevelopmentModeWarnings: false,
  autoFocus: true,
+ elevation: 'raised',
 };
 
 const defaultCaptchaOptions: ParsedCaptcha = {

packages/ui/src/elements/Card/CardClerkAndPagesTag.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 
 import { useEnvironment } from '../../contexts';
-import { Box, Col, Flex, Icon, Link, Text } from '../../customizables';
+import { Box, Col, descriptors, Flex, Icon, Link, Text } from '../../customizables';
 import { useDevMode } from '../../hooks/useDevMode';
 import { LogoMark } from '../../icons';
 import type { PropsOfComponent, ThemableCssProp } from '../../styledSystem';
@@ -28,6 +28,7 @@ export const CardClerkAndPagesTag = React.memo(
 
  return (
  <Box
+ elementDescriptor={descriptors.footerItem}
  sx={[
  {
  width: '100%',

packages/ui/src/elements/Card/CardRoot.tsx

@@ -1,18 +1,102 @@
 import React from 'react';
 
-import { Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
+import { AppearanceContext, Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
 import type { ElementDescriptor } from '../../customizables/elementDescriptors';
-import type { PropsOfComponent } from '../../styledSystem';
+import type { InternalTheme, PropsOfComponent } from '../../styledSystem';
 import { mqu } from '../../styledSystem';
 import { ApplicationLogo } from '../ApplicationLogo';
 import { useFlowMetadata } from '../contexts';
+import { ModalContext } from '../Modal';
 
-type CardRootProps = PropsOfComponent<typeof Col>;
+// Flush overrides injected into parsedElements after baseTheme but before user overrides.
+const getFlushElements = (t: InternalTheme) => ({
+ cardBox: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ overflow: 'visible',
+ },
+ card: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ backgroundColor: 'transparent',
+ paddingInline: 0,
+ paddingBlock: 0,
+ marginBlockStart: 0,
+ marginInline: 0,
+ },
+ footer: {
+ background: 'transparent',
+ marginTop: t.space.$8,
+ paddingTop: 0,
+ rowGap: t.space.$8,
+ '>:first-of-type': {
+ padding: 0,
+ },
+ '>:not(:first-of-type)': {
+ borderTopWidth: 0,
+ padding: 0,
+ },
+ },
+});
+
+type CardRootProps = PropsOfComponent<typeof Col> & {
+ /**
+ * Override the visual elevation for this card instance.
+ * When omitted, falls back to `appearance.options.elevation` for page-mounted
+ * components, and `'raised'` for modals.
+ * Profile and popover card roots pass `'raised'` explicitly to opt out of flush.
+ */
+ elevation?: 'raised' | 'flush';
+};
 export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props, ref) => {
- const { sx, children, ...rest } = props;
+ const { sx, children, elevation: elevationProp, ...rest } = props;
  const appearance = useAppearance();
  const flowMetadata = useFlowMetadata();
 
+ const rawModalCtx = React.useContext(ModalContext);
+ const isModal = rawModalCtx !== undefined;
+ // Explicit prop wins; modals always raised; otherwise use appearance option
+ const elevation = elevationProp ?? (isModal ? 'raised' : appearance.parsedOptions.elevation);
+ const isFlush = elevation === 'flush';
+
+ const augmentedAppearance = React.useMemo(() => {
+ if (!isFlush) {
+ return appearance;
+ }
+ const flushElements = getFlushElements(appearance.parsedInternalTheme);
+ const newParsedElements = [appearance.parsedElements[0], flushElements, ...appearance.parsedElements.slice(1)];
+ return { ...appearance, parsedElements: newParsedElements };
+ }, [appearance, isFlush]);
+
+ const cardBox = (
+ <Col
+ elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
+ className={generateFlowPartClassname(flowMetadata)}
+ ref={ref}
+ data-elevation={isFlush ? 'flush' : undefined}
+ sx={[
+ t => ({
+ isolation: 'isolate',
+ maxWidth: `calc(100vw - ${t.sizes.$10})`,
+ width: t.sizes.$100,
+ borderWidth: t.borderWidths.$normal,
+ borderStyle: t.borderStyles.$solid,
+ borderColor: t.colors.$borderAlpha150,
+ borderRadius: t.radii.$xl,
+ color: t.colors.$colorForeground,
+ position: 'relative',
+ overflow: 'hidden',
+ }),
+ sx,
+ ]}
+ {...rest}
+ >
+ {children}
+ </Col>
+ );
+
  return (
  <>
  {appearance.parsedOptions.logoPlacement === 'outside' && (
@@ -25,33 +109,11 @@ export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props,
  })}
  />
  )}
- <Col
- elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
- className={generateFlowPartClassname(flowMetadata)}
- ref={ref}
- sx={[
- t => ({
- /**
- * All components should create their own stack context
- * https://developer.mozilla.org/en-US/docs/Web/CSS/isolation
- */
- isolation: 'isolate',
- maxWidth: `calc(100vw - ${t.sizes.$10})`,
- width: t.sizes.$100,
- borderWidth: t.borderWidths.$normal,
- borderStyle: t.borderStyles.$solid,
- borderColor: t.colors.$borderAlpha150,
- borderRadius: t.radii.$xl,
- color: t.colors.$colorForeground,
- position: 'relative',
- overflow: 'hidden',
- }),
- sx,
- ]}
- {...rest}
- >
- {children}
- </Col>
+ {isFlush ? (
+ <AppearanceContext.Provider value={{ value: augmentedAppearance }}>{cardBox}</AppearanceContext.Provider>
+ ) : (
+ cardBox
+ )}
  </>
  );
 });

.changeset/card-elevation-option.md

@@ -0,0 +1,7 @@
+---
+"@clerk/ui": minor
+---
+
+Add `elevation` appearance option with `'raised'` (default) and `'flush'` values. When set to `flush`, card-based components render without border, box-shadow, border-radius, outer padding, and footer background, allowing them to sit flat against their container. Applies to `<SignIn />`, `<SignUp />`, `<Waitlist />`, `<CreateOrganization />`, `<OrganizationList />`, `<OAuthConsent />`, `<UserVerification />`, and session task components. Profile and popover components always render as raised. Modal components always render as raised regardless of this setting.
+
+The `cardBox` element exposes a `data-elevation="flush"` attribute when flush is active, giving className-based themes a hook to neutralize their card chrome via attribute selectors. The `shadcn` theme uses this hook to drop its `shadow-sm border` utilities under flush.

packages/clerk-js/sandbox/app.ts

@@ -281,13 +281,26 @@ function otherOptions() {
  localization: document.getElementById('localizationSelect') as HTMLSelectElement,
  };
 
+ const elevationSelect = document.getElementById('elevationSelect') as HTMLSelectElement;
+ const devWarningsToggle = document.getElementById('devWarningsToggle') as HTMLInputElement;
+
  Object.entries(otherOptionsInputs).forEach(([key, input]) => {
  const savedValue = sessionStorage.getItem(key);
  if (savedValue) {
  input.value = savedValue;
  }
  });
 
+ const savedElevation = sessionStorage.getItem('elevation');
+ if (savedElevation) {
+ elevationSelect.value = savedElevation;
+ }
+
+ const savedDevWarnings = sessionStorage.getItem('devWarnings');
+ if (savedDevWarnings !== null) {
+ devWarningsToggle.checked = savedDevWarnings === 'on';
+ }
+
  const updateOtherOptions = () => {
  void Clerk.__internal_updateProps({
  options: Object.fromEntries(
@@ -304,16 +317,40 @@ function otherOptions() {
  });
  };
 
+ const updateAppearanceOptions = () => {
+ sessionStorage.setItem('elevation', elevationSelect.value);
+ sessionStorage.setItem('devWarnings', devWarningsToggle.checked ? 'on' : 'off');
+ const currentAppearance = Clerk.__internal_getOption('appearance') ?? {};
+ void Clerk.__internal_updateProps({
+ appearance: {
+ ...currentAppearance,
+ options: {
+ ...(currentAppearance as any).options,
+ elevation: elevationSelect.value as 'raised' | 'flush',
+ unsafe_disableDevelopmentModeWarnings: !devWarningsToggle.checked,
+ },
+ },
+ });
+ };
+
  Object.values(otherOptionsInputs).forEach(input => {
  input.addEventListener('change', updateOtherOptions);
  });
 
+ elevationSelect.addEventListener('change', updateAppearanceOptions);
+ devWarningsToggle.addEventListener('change', updateAppearanceOptions);
+
  resetOtherOptionsBtn?.addEventListener('click', () => {
  otherOptionsInputs.localization.value = 'enUS';
+ elevationSelect.value = 'raised';
+ devWarningsToggle.checked = true;
+ sessionStorage.removeItem('elevation');
+ sessionStorage.removeItem('devWarnings');
  updateOtherOptions();
+ updateAppearanceOptions();
  });
 
- return { updateOtherOptions };
+ return { updateOtherOptions, updateAppearanceOptions };
 }
 
 const themes: Record<string, unknown> = {
@@ -411,7 +448,7 @@ void (async () => {
  const { updateVariables } = appearanceVariableOptions();
  const { updateTheme } = themeSelector();
  const { updatePreset } = presetSelector();
- const { updateOtherOptions } = otherOptions();
+ const { updateOtherOptions, updateAppearanceOptions } = otherOptions();
 
  const sidebars = document.querySelectorAll('[data-sidebar]');
  document.addEventListener('keydown', e => {
@@ -540,6 +577,15 @@ void (async () => {
  const initialTheme = initialThemeName ? themes[initialThemeName] : undefined;
  const initialPresetName = sessionStorage.getItem('preset') ?? '';
  const initialPreset = initialPresetName ? presets[initialPresetName] : undefined;
+ const initialElevation = sessionStorage.getItem('elevation') as 'raised' | 'flush' | null;
+ const initialDevWarnings = sessionStorage.getItem('devWarnings');
+ const initialAppearanceOptions: Record<string, unknown> = {};
+ if (initialElevation) {
+ initialAppearanceOptions.elevation = initialElevation;
+ }
+ if (initialDevWarnings === 'off') {
+ initialAppearanceOptions.unsafe_disableDevelopmentModeWarnings = true;
+ }
 
  await Clerk.load({
  ...(componentControls.clerk.getProps() ?? {}),
@@ -549,6 +595,7 @@ void (async () => {
  appearance: {
  ...(initialTheme ? { theme: initialTheme } : {}),
  ...presetToAppearance(initialPreset),
+ ...(Object.keys(initialAppearanceOptions).length ? { options: initialAppearanceOptions } : {}),
  },
  });
  renderCurrentRoute();
@@ -560,6 +607,7 @@ void (async () => {
  updateVariables();
  }
  updateOtherOptions();
+ updateAppearanceOptions();
  } else {
  console.error(`Unknown route: "${route}".`);
  }

packages/clerk-js/sandbox/template.html

@@ -33,7 +33,7 @@
  }
  </script>
  </head>
- <body class="flex min-h-full flex-col overflow-x-hidden bg-gray-50 lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
+ <body class="flex min-h-full flex-col overflow-x-hidden bg-white lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
  <div
  data-sidebar
  class="fixed inset-y-0 left-0 w-72 overflow-y-auto border-r border-gray-100 bg-white px-2 py-4 max-lg:hidden"
@@ -436,6 +436,24 @@
  <span class="font-mono text-xs">localization</span>
  <select id="localizationSelect"></select>
  </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">elevation</span>
+ <select
+ id="elevationSelect"
+ class="text-sm"
+ >
+ <option value="raised">raised</option>
+ <option value="flush">flush</option>
+ </select>
+ </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">devWarnings</span>
+ <input
+ type="checkbox"
+ id="devWarningsToggle"
+ checked
+ />
+ </label>
  </fieldset>
  </div>
 

packages/ui/src/customizables/AppearanceContext.tsx

@@ -23,4 +23,4 @@ const AppearanceProvider = (props: AppearanceProviderProps) => {
  return <AppearanceContext.Provider value={ctxValue}>{props.children}</AppearanceContext.Provider>;
 };
 
-export { AppearanceProvider, useAppearance };
+export { AppearanceContext, AppearanceProvider, useAppearance };

packages/ui/src/customizables/__tests__/parseAppearance.test.tsx

@@ -238,6 +238,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -255,6 +256,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(false);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('bottom');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('iconButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the appearance prop', () => {
@@ -272,6 +274,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -289,6 +292,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the globalAppearance and appearance prop', () => {
@@ -306,6 +310,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  appearance={{
@@ -319,6 +324,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'raised',
  },
  }}
  >
@@ -336,6 +342,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('raised');
  });
 
  it('removes the base theme when simpleStyles is passed to globalAppearance', () => {

packages/ui/src/customizables/index.ts

@@ -6,7 +6,7 @@ import { makeResponsive } from './makeResponsive';
 import { sanitizeDomProps } from './sanitizeDomProps';
 
 export * from './Flow';
-export { AppearanceProvider, useAppearance } from './AppearanceContext';
+export { AppearanceContext, AppearanceProvider, useAppearance } from './AppearanceContext';
 export { descriptors } from './elementDescriptors';
 export { localizationKeys, useLocalizations } from '../localization';
 export type { LocalizationKey } from '../localization';

packages/ui/src/customizables/parseAppearance.ts

@@ -52,6 +52,7 @@ const defaultOptions: ParsedOptions = {
  animations: true,
  unsafe_disableDevelopmentModeWarnings: false,
  autoFocus: true,
+ elevation: 'raised',
 };
 
 const defaultCaptchaOptions: ParsedCaptcha = {

packages/ui/src/elements/Card/CardClerkAndPagesTag.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 
 import { useEnvironment } from '../../contexts';
-import { Box, Col, Flex, Icon, Link, Text } from '../../customizables';
+import { Box, Col, descriptors, Flex, Icon, Link, Text } from '../../customizables';
 import { useDevMode } from '../../hooks/useDevMode';
 import { LogoMark } from '../../icons';
 import type { PropsOfComponent, ThemableCssProp } from '../../styledSystem';
@@ -28,6 +28,7 @@ export const CardClerkAndPagesTag = React.memo(
 
  return (
  <Box
+ elementDescriptor={descriptors.footerItem}
  sx={[
  {
  width: '100%',

packages/ui/src/elements/Card/CardRoot.tsx

@@ -1,18 +1,102 @@
 import React from 'react';
 
-import { Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
+import { AppearanceContext, Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
 import type { ElementDescriptor } from '../../customizables/elementDescriptors';
-import type { PropsOfComponent } from '../../styledSystem';
+import type { InternalTheme, PropsOfComponent } from '../../styledSystem';
 import { mqu } from '../../styledSystem';
 import { ApplicationLogo } from '../ApplicationLogo';
 import { useFlowMetadata } from '../contexts';
+import { ModalContext } from '../Modal';
 
-type CardRootProps = PropsOfComponent<typeof Col>;
+// Flush overrides injected into parsedElements after baseTheme but before user overrides.
+const getFlushElements = (t: InternalTheme) => ({
+ cardBox: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ overflow: 'visible',
+ },
+ card: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ backgroundColor: 'transparent',
+ paddingInline: 0,
+ paddingBlock: 0,
+ marginBlockStart: 0,
+ marginInline: 0,
+ },
+ footer: {
+ background: 'transparent',
+ marginTop: t.space.$8,
+ paddingTop: 0,
+ rowGap: t.space.$8,
+ '>:first-of-type': {
+ padding: 0,
+ },
+ '>:not(:first-of-type)': {
+ borderTopWidth: 0,
+ padding: 0,
+ },
+ },
+});
+
+type CardRootProps = PropsOfComponent<typeof Col> & {
+ /**
+ * Override the visual elevation for this card instance.
+ * When omitted, falls back to `appearance.options.elevation` for page-mounted
+ * components, and `'raised'` for modals.
+ * Profile and popover card roots pass `'raised'` explicitly to opt out of flush.
+ */
+ elevation?: 'raised' | 'flush';
+};
 export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props, ref) => {
- const { sx, children, ...rest } = props;
+ const { sx, children, elevation: elevationProp, ...rest } = props;
  const appearance = useAppearance();
  const flowMetadata = useFlowMetadata();
 
+ const rawModalCtx = React.useContext(ModalContext);
+ const isModal = rawModalCtx !== undefined;
+ // Explicit prop wins; modals always raised; otherwise use appearance option
+ const elevation = elevationProp ?? (isModal ? 'raised' : appearance.parsedOptions.elevation);
+ const isFlush = elevation === 'flush';
+
+ const augmentedAppearance = React.useMemo(() => {
+ if (!isFlush) {
+ return appearance;
+ }
+ const flushElements = getFlushElements(appearance.parsedInternalTheme);
+ const newParsedElements = [appearance.parsedElements[0], flushElements, ...appearance.parsedElements.slice(1)];
+ return { ...appearance, parsedElements: newParsedElements };
+ }, [appearance, isFlush]);
+
+ const cardBox = (
+ <Col
+ elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
+ className={generateFlowPartClassname(flowMetadata)}
+ ref={ref}
+ data-elevation={isFlush ? 'flush' : undefined}
+ sx={[
+ t => ({
+ isolation: 'isolate',
+ maxWidth: `calc(100vw - ${t.sizes.$10})`,
+ width: t.sizes.$100,
+ borderWidth: t.borderWidths.$normal,
+ borderStyle: t.borderStyles.$solid,
+ borderColor: t.colors.$borderAlpha150,
+ borderRadius: t.radii.$xl,
+ color: t.colors.$colorForeground,
+ position: 'relative',
+ overflow: 'hidden',
+ }),
+ sx,
+ ]}
+ {...rest}
+ >
+ {children}
+ </Col>
+ );
+
  return (
  <>
  {appearance.parsedOptions.logoPlacement === 'outside' && (
@@ -25,33 +109,11 @@ export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props,
  })}
  />
  )}
- <Col
- elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
- className={generateFlowPartClassname(flowMetadata)}
- ref={ref}
- sx={[
- t => ({
- /**
- * All components should create their own stack context
- * https://developer.mozilla.org/en-US/docs/Web/CSS/isolation
- */
- isolation: 'isolate',
- maxWidth: `calc(100vw - ${t.sizes.$10})`,
- width: t.sizes.$100,
- borderWidth: t.borderWidths.$normal,
- borderStyle: t.borderStyles.$solid,
- borderColor: t.colors.$borderAlpha150,
- borderRadius: t.radii.$xl,
- color: t.colors.$colorForeground,
- position: 'relative',
- overflow: 'hidden',
- }),
- sx,
- ]}
- {...rest}
- >
- {children}
- </Col>
+ {isFlush ? (
+ <AppearanceContext.Provider value={{ value: augmentedAppearance }}>{cardBox}</AppearanceContext.Provider>
+ ) : (
+ cardBox
+ )}
  </>
  );
 });

.changeset/card-elevation-option.md

@@ -0,0 +1,7 @@
+---
+"@clerk/ui": minor
+---
+
+Add `elevation` appearance option with `'raised'` (default) and `'flush'` values. When set to `flush`, card-based components render without border, box-shadow, border-radius, outer padding, and footer background, allowing them to sit flat against their container. Applies to `<SignIn />`, `<SignUp />`, `<Waitlist />`, `<CreateOrganization />`, `<OrganizationList />`, `<OAuthConsent />`, `<UserVerification />`, and session task components. Profile and popover components always render as raised. Modal components always render as raised regardless of this setting.
+
+The `cardBox` element exposes a `data-elevation="flush"` attribute when flush is active, giving className-based themes a hook to neutralize their card chrome via attribute selectors. The `shadcn` theme uses this hook to drop its `shadow-sm border` utilities under flush.

packages/clerk-js/sandbox/app.ts

@@ -281,13 +281,26 @@ function otherOptions() {
  localization: document.getElementById('localizationSelect') as HTMLSelectElement,
  };
 
+ const elevationSelect = document.getElementById('elevationSelect') as HTMLSelectElement;
+ const devWarningsToggle = document.getElementById('devWarningsToggle') as HTMLInputElement;
+
  Object.entries(otherOptionsInputs).forEach(([key, input]) => {
  const savedValue = sessionStorage.getItem(key);
  if (savedValue) {
  input.value = savedValue;
  }
  });
 
+ const savedElevation = sessionStorage.getItem('elevation');
+ if (savedElevation) {
+ elevationSelect.value = savedElevation;
+ }
+
+ const savedDevWarnings = sessionStorage.getItem('devWarnings');
+ if (savedDevWarnings !== null) {
+ devWarningsToggle.checked = savedDevWarnings === 'on';
+ }
+
  const updateOtherOptions = () => {
  void Clerk.__internal_updateProps({
  options: Object.fromEntries(
@@ -304,16 +317,40 @@ function otherOptions() {
  });
  };
 
+ const updateAppearanceOptions = () => {
+ sessionStorage.setItem('elevation', elevationSelect.value);
+ sessionStorage.setItem('devWarnings', devWarningsToggle.checked ? 'on' : 'off');
+ const currentAppearance = Clerk.__internal_getOption('appearance') ?? {};
+ void Clerk.__internal_updateProps({
+ appearance: {
+ ...currentAppearance,
+ options: {
+ ...(currentAppearance as any).options,
+ elevation: elevationSelect.value as 'raised' | 'flush',
+ unsafe_disableDevelopmentModeWarnings: !devWarningsToggle.checked,
+ },
+ },
+ });
+ };
+
  Object.values(otherOptionsInputs).forEach(input => {
  input.addEventListener('change', updateOtherOptions);
  });
 
+ elevationSelect.addEventListener('change', updateAppearanceOptions);
+ devWarningsToggle.addEventListener('change', updateAppearanceOptions);
+
  resetOtherOptionsBtn?.addEventListener('click', () => {
  otherOptionsInputs.localization.value = 'enUS';
+ elevationSelect.value = 'raised';
+ devWarningsToggle.checked = true;
+ sessionStorage.removeItem('elevation');
+ sessionStorage.removeItem('devWarnings');
  updateOtherOptions();
+ updateAppearanceOptions();
  });
 
- return { updateOtherOptions };
+ return { updateOtherOptions, updateAppearanceOptions };
 }
 
 const themes: Record<string, unknown> = {
@@ -411,7 +448,7 @@ void (async () => {
  const { updateVariables } = appearanceVariableOptions();
  const { updateTheme } = themeSelector();
  const { updatePreset } = presetSelector();
- const { updateOtherOptions } = otherOptions();
+ const { updateOtherOptions, updateAppearanceOptions } = otherOptions();
 
  const sidebars = document.querySelectorAll('[data-sidebar]');
  document.addEventListener('keydown', e => {
@@ -540,6 +577,15 @@ void (async () => {
  const initialTheme = initialThemeName ? themes[initialThemeName] : undefined;
  const initialPresetName = sessionStorage.getItem('preset') ?? '';
  const initialPreset = initialPresetName ? presets[initialPresetName] : undefined;
+ const initialElevation = sessionStorage.getItem('elevation') as 'raised' | 'flush' | null;
+ const initialDevWarnings = sessionStorage.getItem('devWarnings');
+ const initialAppearanceOptions: Record<string, unknown> = {};
+ if (initialElevation) {
+ initialAppearanceOptions.elevation = initialElevation;
+ }
+ if (initialDevWarnings === 'off') {
+ initialAppearanceOptions.unsafe_disableDevelopmentModeWarnings = true;
+ }
 
  await Clerk.load({
  ...(componentControls.clerk.getProps() ?? {}),
@@ -549,6 +595,7 @@ void (async () => {
  appearance: {
  ...(initialTheme ? { theme: initialTheme } : {}),
  ...presetToAppearance(initialPreset),
+ ...(Object.keys(initialAppearanceOptions).length ? { options: initialAppearanceOptions } : {}),
  },
  });
  renderCurrentRoute();
@@ -560,6 +607,7 @@ void (async () => {
  updateVariables();
  }
  updateOtherOptions();
+ updateAppearanceOptions();
  } else {
  console.error(`Unknown route: "${route}".`);
  }

packages/clerk-js/sandbox/template.html

@@ -33,7 +33,7 @@
  }
  </script>
  </head>
- <body class="flex min-h-full flex-col overflow-x-hidden bg-gray-50 lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
+ <body class="flex min-h-full flex-col overflow-x-hidden bg-white lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
  <div
  data-sidebar
  class="fixed inset-y-0 left-0 w-72 overflow-y-auto border-r border-gray-100 bg-white px-2 py-4 max-lg:hidden"
@@ -436,6 +436,24 @@
  <span class="font-mono text-xs">localization</span>
  <select id="localizationSelect"></select>
  </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">elevation</span>
+ <select
+ id="elevationSelect"
+ class="text-sm"
+ >
+ <option value="raised">raised</option>
+ <option value="flush">flush</option>
+ </select>
+ </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">devWarnings</span>
+ <input
+ type="checkbox"
+ id="devWarningsToggle"
+ checked
+ />
+ </label>
  </fieldset>
  </div>
 

packages/ui/src/customizables/AppearanceContext.tsx

@@ -23,4 +23,4 @@ const AppearanceProvider = (props: AppearanceProviderProps) => {
  return <AppearanceContext.Provider value={ctxValue}>{props.children}</AppearanceContext.Provider>;
 };
 
-export { AppearanceProvider, useAppearance };
+export { AppearanceContext, AppearanceProvider, useAppearance };

packages/ui/src/customizables/__tests__/parseAppearance.test.tsx

@@ -238,6 +238,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -255,6 +256,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(false);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('bottom');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('iconButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the appearance prop', () => {
@@ -272,6 +274,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -289,6 +292,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the globalAppearance and appearance prop', () => {
@@ -306,6 +310,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  appearance={{
@@ -319,6 +324,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'raised',
  },
  }}
  >
@@ -336,6 +342,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('raised');
  });
 
  it('removes the base theme when simpleStyles is passed to globalAppearance', () => {

packages/ui/src/customizables/index.ts

@@ -6,7 +6,7 @@ import { makeResponsive } from './makeResponsive';
 import { sanitizeDomProps } from './sanitizeDomProps';
 
 export * from './Flow';
-export { AppearanceProvider, useAppearance } from './AppearanceContext';
+export { AppearanceContext, AppearanceProvider, useAppearance } from './AppearanceContext';
 export { descriptors } from './elementDescriptors';
 export { localizationKeys, useLocalizations } from '../localization';
 export type { LocalizationKey } from '../localization';

packages/ui/src/customizables/parseAppearance.ts

@@ -52,6 +52,7 @@ const defaultOptions: ParsedOptions = {
  animations: true,
  unsafe_disableDevelopmentModeWarnings: false,
  autoFocus: true,
+ elevation: 'raised',
 };
 
 const defaultCaptchaOptions: ParsedCaptcha = {

packages/ui/src/elements/Card/CardClerkAndPagesTag.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 
 import { useEnvironment } from '../../contexts';
-import { Box, Col, Flex, Icon, Link, Text } from '../../customizables';
+import { Box, Col, descriptors, Flex, Icon, Link, Text } from '../../customizables';
 import { useDevMode } from '../../hooks/useDevMode';
 import { LogoMark } from '../../icons';
 import type { PropsOfComponent, ThemableCssProp } from '../../styledSystem';
@@ -28,6 +28,7 @@ export const CardClerkAndPagesTag = React.memo(
 
  return (
  <Box
+ elementDescriptor={descriptors.footerItem}
  sx={[
  {
  width: '100%',

packages/ui/src/elements/Card/CardRoot.tsx

@@ -1,18 +1,102 @@
 import React from 'react';
 
-import { Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
+import { AppearanceContext, Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
 import type { ElementDescriptor } from '../../customizables/elementDescriptors';
-import type { PropsOfComponent } from '../../styledSystem';
+import type { InternalTheme, PropsOfComponent } from '../../styledSystem';
 import { mqu } from '../../styledSystem';
 import { ApplicationLogo } from '../ApplicationLogo';
 import { useFlowMetadata } from '../contexts';
+import { ModalContext } from '../Modal';
 
-type CardRootProps = PropsOfComponent<typeof Col>;
+// Flush overrides injected into parsedElements after baseTheme but before user overrides.
+const getFlushElements = (t: InternalTheme) => ({
+ cardBox: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ overflow: 'visible',
+ },
+ card: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ backgroundColor: 'transparent',
+ paddingInline: 0,
+ paddingBlock: 0,
+ marginBlockStart: 0,
+ marginInline: 0,
+ },
+ footer: {
+ background: 'transparent',
+ marginTop: t.space.$8,
+ paddingTop: 0,
+ rowGap: t.space.$8,
+ '>:first-of-type': {
+ padding: 0,
+ },
+ '>:not(:first-of-type)': {
+ borderTopWidth: 0,
+ padding: 0,
+ },
+ },
+});
+
+type CardRootProps = PropsOfComponent<typeof Col> & {
+ /**
+ * Override the visual elevation for this card instance.
+ * When omitted, falls back to `appearance.options.elevation` for page-mounted
+ * components, and `'raised'` for modals.
+ * Profile and popover card roots pass `'raised'` explicitly to opt out of flush.
+ */
+ elevation?: 'raised' | 'flush';
+};
 export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props, ref) => {
- const { sx, children, ...rest } = props;
+ const { sx, children, elevation: elevationProp, ...rest } = props;
  const appearance = useAppearance();
  const flowMetadata = useFlowMetadata();
 
+ const rawModalCtx = React.useContext(ModalContext);
+ const isModal = rawModalCtx !== undefined;
+ // Explicit prop wins; modals always raised; otherwise use appearance option
+ const elevation = elevationProp ?? (isModal ? 'raised' : appearance.parsedOptions.elevation);
+ const isFlush = elevation === 'flush';
+
+ const augmentedAppearance = React.useMemo(() => {
+ if (!isFlush) {
+ return appearance;
+ }
+ const flushElements = getFlushElements(appearance.parsedInternalTheme);
+ const newParsedElements = [appearance.parsedElements[0], flushElements, ...appearance.parsedElements.slice(1)];
+ return { ...appearance, parsedElements: newParsedElements };
+ }, [appearance, isFlush]);
+
+ const cardBox = (
+ <Col
+ elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
+ className={generateFlowPartClassname(flowMetadata)}
+ ref={ref}
+ data-elevation={isFlush ? 'flush' : undefined}
+ sx={[
+ t => ({
+ isolation: 'isolate',
+ maxWidth: `calc(100vw - ${t.sizes.$10})`,
+ width: t.sizes.$100,
+ borderWidth: t.borderWidths.$normal,
+ borderStyle: t.borderStyles.$solid,
+ borderColor: t.colors.$borderAlpha150,
+ borderRadius: t.radii.$xl,
+ color: t.colors.$colorForeground,
+ position: 'relative',
+ overflow: 'hidden',
+ }),
+ sx,
+ ]}
+ {...rest}
+ >
+ {children}
+ </Col>
+ );
+
  return (
  <>
  {appearance.parsedOptions.logoPlacement === 'outside' && (
@@ -25,33 +109,11 @@ export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props,
  })}
  />
  )}
- <Col
- elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
- className={generateFlowPartClassname(flowMetadata)}
- ref={ref}
- sx={[
- t => ({
- /**
- * All components should create their own stack context
- * https://developer.mozilla.org/en-US/docs/Web/CSS/isolation
- */
- isolation: 'isolate',
- maxWidth: `calc(100vw - ${t.sizes.$10})`,
- width: t.sizes.$100,
- borderWidth: t.borderWidths.$normal,
- borderStyle: t.borderStyles.$solid,
- borderColor: t.colors.$borderAlpha150,
- borderRadius: t.radii.$xl,
- color: t.colors.$colorForeground,
- position: 'relative',
- overflow: 'hidden',
- }),
- sx,
- ]}
- {...rest}
- >
- {children}
- </Col>
+ {isFlush ? (
+ <AppearanceContext.Provider value={{ value: augmentedAppearance }}>{cardBox}</AppearanceContext.Provider>
+ ) : (
+ cardBox
+ )}
  </>
  );
 });

.changeset/card-elevation-option.md

@@ -0,0 +1,7 @@
+---
+"@clerk/ui": minor
+---
+
+Add `elevation` appearance option with `'raised'` (default) and `'flush'` values. When set to `flush`, card-based components render without border, box-shadow, border-radius, outer padding, and footer background, allowing them to sit flat against their container. Applies to `<SignIn />`, `<SignUp />`, `<Waitlist />`, `<CreateOrganization />`, `<OrganizationList />`, `<OAuthConsent />`, `<UserVerification />`, and session task components. Profile and popover components always render as raised. Modal components always render as raised regardless of this setting.
+
+The `cardBox` element exposes a `data-elevation="flush"` attribute when flush is active, giving className-based themes a hook to neutralize their card chrome via attribute selectors. The `shadcn` theme uses this hook to drop its `shadow-sm border` utilities under flush.

packages/clerk-js/sandbox/app.ts

@@ -281,13 +281,26 @@ function otherOptions() {
  localization: document.getElementById('localizationSelect') as HTMLSelectElement,
  };
 
+ const elevationSelect = document.getElementById('elevationSelect') as HTMLSelectElement;
+ const devWarningsToggle = document.getElementById('devWarningsToggle') as HTMLInputElement;
+
  Object.entries(otherOptionsInputs).forEach(([key, input]) => {
  const savedValue = sessionStorage.getItem(key);
  if (savedValue) {
  input.value = savedValue;
  }
  });
 
+ const savedElevation = sessionStorage.getItem('elevation');
+ if (savedElevation) {
+ elevationSelect.value = savedElevation;
+ }
+
+ const savedDevWarnings = sessionStorage.getItem('devWarnings');
+ if (savedDevWarnings !== null) {
+ devWarningsToggle.checked = savedDevWarnings === 'on';
+ }
+
  const updateOtherOptions = () => {
  void Clerk.__internal_updateProps({
  options: Object.fromEntries(
@@ -304,16 +317,40 @@ function otherOptions() {
  });
  };
 
+ const updateAppearanceOptions = () => {
+ sessionStorage.setItem('elevation', elevationSelect.value);
+ sessionStorage.setItem('devWarnings', devWarningsToggle.checked ? 'on' : 'off');
+ const currentAppearance = Clerk.__internal_getOption('appearance') ?? {};
+ void Clerk.__internal_updateProps({
+ appearance: {
+ ...currentAppearance,
+ options: {
+ ...(currentAppearance as any).options,
+ elevation: elevationSelect.value as 'raised' | 'flush',
+ unsafe_disableDevelopmentModeWarnings: !devWarningsToggle.checked,
+ },
+ },
+ });
+ };
+
  Object.values(otherOptionsInputs).forEach(input => {
  input.addEventListener('change', updateOtherOptions);
  });
 
+ elevationSelect.addEventListener('change', updateAppearanceOptions);
+ devWarningsToggle.addEventListener('change', updateAppearanceOptions);
+
  resetOtherOptionsBtn?.addEventListener('click', () => {
  otherOptionsInputs.localization.value = 'enUS';
+ elevationSelect.value = 'raised';
+ devWarningsToggle.checked = true;
+ sessionStorage.removeItem('elevation');
+ sessionStorage.removeItem('devWarnings');
  updateOtherOptions();
+ updateAppearanceOptions();
  });
 
- return { updateOtherOptions };
+ return { updateOtherOptions, updateAppearanceOptions };
 }
 
 const themes: Record<string, unknown> = {
@@ -411,7 +448,7 @@ void (async () => {
  const { updateVariables } = appearanceVariableOptions();
  const { updateTheme } = themeSelector();
  const { updatePreset } = presetSelector();
- const { updateOtherOptions } = otherOptions();
+ const { updateOtherOptions, updateAppearanceOptions } = otherOptions();
 
  const sidebars = document.querySelectorAll('[data-sidebar]');
  document.addEventListener('keydown', e => {
@@ -540,6 +577,15 @@ void (async () => {
  const initialTheme = initialThemeName ? themes[initialThemeName] : undefined;
  const initialPresetName = sessionStorage.getItem('preset') ?? '';
  const initialPreset = initialPresetName ? presets[initialPresetName] : undefined;
+ const initialElevation = sessionStorage.getItem('elevation') as 'raised' | 'flush' | null;
+ const initialDevWarnings = sessionStorage.getItem('devWarnings');
+ const initialAppearanceOptions: Record<string, unknown> = {};
+ if (initialElevation) {
+ initialAppearanceOptions.elevation = initialElevation;
+ }
+ if (initialDevWarnings === 'off') {
+ initialAppearanceOptions.unsafe_disableDevelopmentModeWarnings = true;
+ }
 
  await Clerk.load({
  ...(componentControls.clerk.getProps() ?? {}),
@@ -549,6 +595,7 @@ void (async () => {
  appearance: {
  ...(initialTheme ? { theme: initialTheme } : {}),
  ...presetToAppearance(initialPreset),
+ ...(Object.keys(initialAppearanceOptions).length ? { options: initialAppearanceOptions } : {}),
  },
  });
  renderCurrentRoute();
@@ -560,6 +607,7 @@ void (async () => {
  updateVariables();
  }
  updateOtherOptions();
+ updateAppearanceOptions();
  } else {
  console.error(`Unknown route: "${route}".`);
  }

packages/clerk-js/sandbox/template.html

@@ -33,7 +33,7 @@
  }
  </script>
  </head>
- <body class="flex min-h-full flex-col overflow-x-hidden bg-gray-50 lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
+ <body class="flex min-h-full flex-col overflow-x-hidden bg-white lg:has-[*[data-sidebar]:not(.hidden)]:px-72">
  <div
  data-sidebar
  class="fixed inset-y-0 left-0 w-72 overflow-y-auto border-r border-gray-100 bg-white px-2 py-4 max-lg:hidden"
@@ -436,6 +436,24 @@
  <span class="font-mono text-xs">localization</span>
  <select id="localizationSelect"></select>
  </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">elevation</span>
+ <select
+ id="elevationSelect"
+ class="text-sm"
+ >
+ <option value="raised">raised</option>
+ <option value="flush">flush</option>
+ </select>
+ </label>
+ <label class="flex items-center justify-between border-t border-gray-100 py-2">
+ <span class="font-mono text-xs">devWarnings</span>
+ <input
+ type="checkbox"
+ id="devWarningsToggle"
+ checked
+ />
+ </label>
  </fieldset>
  </div>
 

packages/ui/src/customizables/AppearanceContext.tsx

@@ -23,4 +23,4 @@ const AppearanceProvider = (props: AppearanceProviderProps) => {
  return <AppearanceContext.Provider value={ctxValue}>{props.children}</AppearanceContext.Provider>;
 };
 
-export { AppearanceProvider, useAppearance };
+export { AppearanceContext, AppearanceProvider, useAppearance };

packages/ui/src/customizables/__tests__/parseAppearance.test.tsx

@@ -238,6 +238,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -255,6 +256,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(false);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('bottom');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('iconButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the appearance prop', () => {
@@ -272,6 +274,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'flush',
  },
  }}
  >
@@ -289,6 +292,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('flush');
  });
 
  it('sets the parsedOptions correctly from the globalAppearance and appearance prop', () => {
@@ -306,6 +310,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: false,
  socialButtonsPlacement: 'bottom',
  socialButtonsVariant: 'iconButton',
+ elevation: 'flush',
  },
  }}
  appearance={{
@@ -319,6 +324,7 @@ describe('AppearanceProvider options flows', () => {
  showOptionalFields: true,
  socialButtonsPlacement: 'top',
  socialButtonsVariant: 'blockButton',
+ elevation: 'raised',
  },
  }}
  >
@@ -336,6 +342,7 @@ describe('AppearanceProvider options flows', () => {
  expect(result.current.parsedOptions.showOptionalFields).toBe(true);
  expect(result.current.parsedOptions.socialButtonsPlacement).toBe('top');
  expect(result.current.parsedOptions.socialButtonsVariant).toBe('blockButton');
+ expect(result.current.parsedOptions.elevation).toBe('raised');
  });
 
  it('removes the base theme when simpleStyles is passed to globalAppearance', () => {

packages/ui/src/customizables/index.ts

@@ -6,7 +6,7 @@ import { makeResponsive } from './makeResponsive';
 import { sanitizeDomProps } from './sanitizeDomProps';
 
 export * from './Flow';
-export { AppearanceProvider, useAppearance } from './AppearanceContext';
+export { AppearanceContext, AppearanceProvider, useAppearance } from './AppearanceContext';
 export { descriptors } from './elementDescriptors';
 export { localizationKeys, useLocalizations } from '../localization';
 export type { LocalizationKey } from '../localization';

packages/ui/src/customizables/parseAppearance.ts

@@ -52,6 +52,7 @@ const defaultOptions: ParsedOptions = {
  animations: true,
  unsafe_disableDevelopmentModeWarnings: false,
  autoFocus: true,
+ elevation: 'raised',
 };
 
 const defaultCaptchaOptions: ParsedCaptcha = {

packages/ui/src/elements/Card/CardClerkAndPagesTag.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 
 import { useEnvironment } from '../../contexts';
-import { Box, Col, Flex, Icon, Link, Text } from '../../customizables';
+import { Box, Col, descriptors, Flex, Icon, Link, Text } from '../../customizables';
 import { useDevMode } from '../../hooks/useDevMode';
 import { LogoMark } from '../../icons';
 import type { PropsOfComponent, ThemableCssProp } from '../../styledSystem';
@@ -28,6 +28,7 @@ export const CardClerkAndPagesTag = React.memo(
 
  return (
  <Box
+ elementDescriptor={descriptors.footerItem}
  sx={[
  {
  width: '100%',

packages/ui/src/elements/Card/CardRoot.tsx

@@ -1,18 +1,102 @@
 import React from 'react';
 
-import { Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
+import { AppearanceContext, Col, descriptors, generateFlowPartClassname, useAppearance } from '../../customizables';
 import type { ElementDescriptor } from '../../customizables/elementDescriptors';
-import type { PropsOfComponent } from '../../styledSystem';
+import type { InternalTheme, PropsOfComponent } from '../../styledSystem';
 import { mqu } from '../../styledSystem';
 import { ApplicationLogo } from '../ApplicationLogo';
 import { useFlowMetadata } from '../contexts';
+import { ModalContext } from '../Modal';
 
-type CardRootProps = PropsOfComponent<typeof Col>;
+// Flush overrides injected into parsedElements after baseTheme but before user overrides.
+const getFlushElements = (t: InternalTheme) => ({
+ cardBox: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ overflow: 'visible',
+ },
+ card: {
+ borderWidth: 0,
+ borderRadius: 0,
+ boxShadow: 'none',
+ backgroundColor: 'transparent',
+ paddingInline: 0,
+ paddingBlock: 0,
+ marginBlockStart: 0,
+ marginInline: 0,
+ },
+ footer: {
+ background: 'transparent',
+ marginTop: t.space.$8,
+ paddingTop: 0,
+ rowGap: t.space.$8,
+ '>:first-of-type': {
+ padding: 0,
+ },
+ '>:not(:first-of-type)': {
+ borderTopWidth: 0,
+ padding: 0,
+ },
+ },
+});
+
+type CardRootProps = PropsOfComponent<typeof Col> & {
+ /**
+ * Override the visual elevation for this card instance.
+ * When omitted, falls back to `appearance.options.elevation` for page-mounted
+ * components, and `'raised'` for modals.
+ * Profile and popover card roots pass `'raised'` explicitly to opt out of flush.
+ */
+ elevation?: 'raised' | 'flush';
+};
 export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props, ref) => {
- const { sx, children, ...rest } = props;
+ const { sx, children, elevation: elevationProp, ...rest } = props;
  const appearance = useAppearance();
  const flowMetadata = useFlowMetadata();
 
+ const rawModalCtx = React.useContext(ModalContext);
+ const isModal = rawModalCtx !== undefined;
+ // Explicit prop wins; modals always raised; otherwise use appearance option
+ const elevation = elevationProp ?? (isModal ? 'raised' : appearance.parsedOptions.elevation);
+ const isFlush = elevation === 'flush';
+
+ const augmentedAppearance = React.useMemo(() => {
+ if (!isFlush) {
+ return appearance;
+ }
+ const flushElements = getFlushElements(appearance.parsedInternalTheme);
+ const newParsedElements = [appearance.parsedElements[0], flushElements, ...appearance.parsedElements.slice(1)];
+ return { ...appearance, parsedElements: newParsedElements };
+ }, [appearance, isFlush]);
+
+ const cardBox = (
+ <Col
+ elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
+ className={generateFlowPartClassname(flowMetadata)}
+ ref={ref}
+ data-elevation={isFlush ? 'flush' : undefined}
+ sx={[
+ t => ({
+ isolation: 'isolate',
+ maxWidth: `calc(100vw - ${t.sizes.$10})`,
+ width: t.sizes.$100,
+ borderWidth: t.borderWidths.$normal,
+ borderStyle: t.borderStyles.$solid,
+ borderColor: t.colors.$borderAlpha150,
+ borderRadius: t.radii.$xl,
+ color: t.colors.$colorForeground,
+ position: 'relative',
+ overflow: 'hidden',
+ }),
+ sx,
+ ]}
+ {...rest}
+ >
+ {children}
+ </Col>
+ );
+
  return (
  <>
  {appearance.parsedOptions.logoPlacement === 'outside' && (
@@ -25,33 +109,11 @@ export const CardRoot = React.forwardRef<HTMLDivElement, CardRootProps>((props,
  })}
  />
  )}
- <Col
- elementDescriptor={[descriptors.cardBox, props.elementDescriptor as ElementDescriptor]}
- className={generateFlowPartClassname(flowMetadata)}
- ref={ref}
- sx={[
- t => ({
- /**
- * All components should create their own stack context
- * https://developer.mozilla.org/en-US/docs/Web/CSS/isolation
- */
- isolation: 'isolate',
- maxWidth: `calc(100vw - ${t.sizes.$10})`,
- width: t.sizes.$100,
- borderWidth: t.borderWidths.$normal,
- borderStyle: t.borderStyles.$solid,
- borderColor: t.colors.$borderAlpha150,
- borderRadius: t.radii.$xl,
- color: t.colors.$colorForeground,
- position: 'relative',
- overflow: 'hidden',
- }),
- sx,
- ]}
- {...rest}
- >
- {children}
- </Col>
+ {isFlush ? (
+ <AppearanceContext.Provider value={{ value: augmentedAppearance }}>{cardBox}</AppearanceContext.Provider>
+ ) : (
+ cardBox
+ )}
  </>
  );
 });