feat(clerk-react): Support for fallback prop (#4723)

brkalow · alexcarpenter · wobsoriano · commit 7fb63096a446 · 2025-02-07T16:17:22.000-08:00
Co-authored-by: Alex Carpenter &lt;alex.carpenter@clerk.dev&gt;
diff --git a/.changeset/serious-stingrays-learn.md b/.changeset/serious-stingrays-learn.md
@@ -0,0 +1,10 @@
+---
+'@clerk/clerk-react': minor
+---
+
+Adds support for a `fallback` prop on Clerk's components. This allows rendering of a placeholder element while Clerk's components are mounting. Use this to help mitigate layout shift when using Clerk's components. Example usage:
+
+
+```tsx
+<SignIn fallback={<LoadingSkeleton />} />
+```
diff --git a/integration/templates/next-app-router/src/app/create-organization/page.tsx b/integration/templates/next-app-router/src/app/create-organization/page.tsx
@@ -0,0 +1,9 @@
+import { CreateOrganization } from '@clerk/nextjs';
+
+export default function Page() {
+  return (
+    <div>
+      <CreateOrganization fallback={<>Loading create organization</>} />
+    </div>
+  );
+}
diff --git a/integration/templates/next-app-router/src/app/organization-list/page.tsx b/integration/templates/next-app-router/src/app/organization-list/page.tsx
@@ -0,0 +1,9 @@
+import { OrganizationList } from '@clerk/nextjs';
+
+export default function Page() {
+  return (
+    <div>
+      <OrganizationList fallback={<>Loading organization list</>} />
+    </div>
+  );
+}
diff --git a/integration/templates/next-app-router/src/app/organization-profile/page.tsx b/integration/templates/next-app-router/src/app/organization-profile/page.tsx
@@ -0,0 +1,12 @@
+import { OrganizationProfile } from '@clerk/nextjs';
+
+export default function Page() {
+  return (
+    <div>
+      <OrganizationProfile
+        routing='hash'
+        fallback={<>Loading organization profile</>}
+      />
+    </div>
+  );
+}
diff --git a/integration/templates/next-app-router/src/app/page.tsx b/integration/templates/next-app-router/src/app/page.tsx
@@ -1,11 +1,12 @@
-import { SignedIn, SignedOut, SignIn, UserButton, Protect } from '@clerk/nextjs';
+import { SignedIn, SignedOut, SignIn, UserButton, Protect, OrganizationSwitcher } from '@clerk/nextjs';
 import Link from 'next/link';
 import { ClientId } from './client-id';
 
 export default function Home() {
   return (
     <main>
-      <UserButton />
+      <UserButton fallback={<>Loading user button</>} />
+      <OrganizationSwitcher fallback={<>Loading organization switcher</>} />
       <ClientId />
       <SignedIn>SignedIn</SignedIn>
       <SignedOut>SignedOut</SignedOut>
diff --git a/integration/templates/next-app-router/src/app/sign-in/[[...catchall]]/page.tsx b/integration/templates/next-app-router/src/app/sign-in/[[...catchall]]/page.tsx
@@ -7,6 +7,7 @@ export default function Page() {
         routing={'path'}
         path={'/sign-in'}
         signUpUrl={'/sign-up'}
+        fallback={<>Loading sign in</>}
         __experimental={{
           combinedProps: {},
         }}
diff --git a/integration/templates/next-app-router/src/app/sign-up/[[...catchall]]/page.tsx b/integration/templates/next-app-router/src/app/sign-up/[[...catchall]]/page.tsx
@@ -7,6 +7,7 @@ export default function Page() {
         routing={'path'}
         path={'/sign-up'}
         signInUrl={'/sign-in'}
+        fallback={<>Loading sign up</>}
       />
     </div>
   );
diff --git a/integration/templates/next-app-router/src/app/switcher/page.tsx b/integration/templates/next-app-router/src/app/switcher/page.tsx
@@ -1,5 +1,10 @@
 import { OrganizationSwitcher } from '@clerk/nextjs';
 
 export default function Page() {
-  return <OrganizationSwitcher hidePersonal={true} />;
+  return (
+    <OrganizationSwitcher
+      hidePersonal={true}
+      fallback={<>Loading organization switcher</>}
+    />
+  );
 }
diff --git a/integration/templates/next-app-router/src/app/user-button/page.tsx b/integration/templates/next-app-router/src/app/user-button/page.tsx
@@ -0,0 +1,9 @@
+import { UserButton } from '@clerk/nextjs';
+
+export default function Page() {
+  return (
+    <div>
+      <UserButton fallback={<>Loading user button</>} />
+    </div>
+  );
+}
diff --git a/integration/templates/next-app-router/src/app/user/[[...catchall]]/page.tsx b/integration/templates/next-app-router/src/app/user/[[...catchall]]/page.tsx
@@ -3,7 +3,7 @@ import { UserProfile } from '@clerk/nextjs';
 export default function Page() {
   return (
     <div>
-      <UserProfile />
+      <UserProfile fallback={<>Loading user profile</>} />
     </div>
   );
 }
diff --git a/integration/templates/next-app-router/src/app/waitlist/page.tsx b/integration/templates/next-app-router/src/app/waitlist/page.tsx
@@ -0,0 +1,9 @@
+import { Waitlist } from '@clerk/nextjs';
+
+export default function Page() {
+  return (
+    <div>
+      <Waitlist fallback={<>Loading waitlist</>} />
+    </div>
+  );
+}
diff --git a/integration/templates/react-vite/src/App.tsx b/integration/templates/react-vite/src/App.tsx
@@ -6,7 +6,7 @@ function App() {
   return (
     <main>
       <UserButton afterSignOutUrl={'/'} />
-      <OrganizationSwitcher />
+      <OrganizationSwitcher fallback={<>Loading organization switcher</>} />
       <ClientId />
       <SignedOut>SignedOut</SignedOut>
       <SignedIn>SignedIn</SignedIn>
diff --git a/integration/templates/react-vite/src/create-organization/index.tsx b/integration/templates/react-vite/src/create-organization/index.tsx
@@ -0,0 +1,9 @@
+import { CreateOrganization } from '@clerk/clerk-react';
+
+export default function Page() {
+  return (
+    <div>
+      <CreateOrganization fallback={<>Loading create organization</>} />
+    </div>
+  );
+}
diff --git a/integration/templates/react-vite/src/custom-user-button/index.tsx b/integration/templates/react-vite/src/custom-user-button/index.tsx
@@ -22,7 +22,7 @@ function Page1() {
 export default function Page() {
   return (
     <PageContextProvider>
-      <UserButton>
+      <UserButton fallback={<>Loading user button</>}>
         <UserButton.UserProfilePage
           label={'Page 1'}
           labelIcon={<p data-label-icon={'page-1'}>🙃</p>}
diff --git a/integration/templates/react-vite/src/custom-user-profile/index.tsx b/integration/templates/react-vite/src/custom-user-profile/index.tsx
@@ -22,7 +22,10 @@ function Page1() {
 export default function Page() {
   return (
     <PageContextProvider>
-      <UserProfile path={'/custom-user-profile'}>
+      <UserProfile
+        fallback={<>Loading user profile</>}
+        path={'/custom-user-profile'}
+      >
         <UserProfile.Page
           label={'Page 1'}
           labelIcon={<p data-label-icon={'page-1'}>🙃</p>}
diff --git a/integration/templates/react-vite/src/main.tsx b/integration/templates/react-vite/src/main.tsx
@@ -11,6 +11,11 @@ import UserProfile from './user';
 import UserProfileCustom from './custom-user-profile';
 import UserButtonCustom from './custom-user-button';
 import UserButtonCustomTrigger from './custom-user-button-trigger';
+import UserButton from './user-button';
+import Waitlist from './waitlist';
+import OrganizationProfile from './organization-profile';
+import OrganizationList from './organization-list';
+import CreateOrganization from './create-organization';
 
 const Root = () => {
   const navigate = useNavigate();
@@ -53,6 +58,10 @@ const router = createBrowserRouter([
         path: '/user/*',
         element: <UserProfile />,
       },
+      {
+        path: '/user-button',
+        element: <UserButton />,
+      },
       {
         path: '/protected',
         element: <Protected />,
@@ -69,6 +78,22 @@ const router = createBrowserRouter([
         path: '/custom-user-button-trigger',
         element: <UserButtonCustomTrigger />,
       },
+      {
+        path: '/waitlist',
+        element: <Waitlist />,
+      },
+      {
+        path: '/organization-profile',
+        element: <OrganizationProfile />,
+      },
+      {
+        path: '/organization-list',
+        element: <OrganizationList />,
+      },
+      {
+        path: '/create-organization',
+        element: <CreateOrganization />,
+      },
     ],
   },
 ]);
diff --git a/integration/templates/react-vite/src/organization-list/index.tsx b/integration/templates/react-vite/src/organization-list/index.tsx
@@ -0,0 +1,9 @@
+import { OrganizationList } from '@clerk/clerk-react';
+
+export default function Page() {
+  return (
+    <div>
+      <OrganizationList fallback={<>Loading organization list</>} />
+    </div>
+  );
+}
diff --git a/integration/templates/react-vite/src/organization-profile/index.tsx b/integration/templates/react-vite/src/organization-profile/index.tsx
@@ -0,0 +1,12 @@
+import { OrganizationProfile } from '@clerk/clerk-react';
+
+export default function Page() {
+  return (
+    <div>
+      <OrganizationProfile
+        routing='hash'
+        fallback={<>Loading organization profile</>}
+      />
+    </div>
+  );
+}
diff --git a/integration/templates/react-vite/src/sign-in/index.tsx b/integration/templates/react-vite/src/sign-in/index.tsx
@@ -6,6 +6,7 @@ export default function Page() {
       <SignIn
         path={'/sign-in'}
         signUpUrl={'/sign-up'}
+        fallback={<>Loading sign in</>}
       />
     </div>
   );
diff --git a/integration/templates/react-vite/src/sign-up/index.tsx b/integration/templates/react-vite/src/sign-up/index.tsx
@@ -6,6 +6,7 @@ export default function Page() {
       <SignUp
         path={'/sign-up'}
         signInUrl={'/sign-in'}
+        fallback={<>Loading sign up</>}
       />
     </div>
   );
diff --git a/integration/templates/react-vite/src/user-button/index.tsx b/integration/templates/react-vite/src/user-button/index.tsx
@@ -0,0 +1,9 @@
+import { UserButton } from '@clerk/clerk-react';
+
+export default function Page() {
+  return (
+    <div>
+      <UserButton fallback={<>Loading user button</>} />
+    </div>
+  );
+}
diff --git a/integration/templates/react-vite/src/user/index.tsx b/integration/templates/react-vite/src/user/index.tsx
@@ -3,7 +3,10 @@ import { UserProfile } from '@clerk/clerk-react';
 export default function Page() {
   return (
     <div>
-      <UserProfile path={'/user'} />
+      <UserProfile
+        path={'/user'}
+        fallback={<>Loading user profile</>}
+      />
     </div>
   );
 }
diff --git a/integration/templates/react-vite/src/waitlist/index.tsx b/integration/templates/react-vite/src/waitlist/index.tsx
@@ -0,0 +1,9 @@
+import { Waitlist } from '@clerk/clerk-react';
+
+export default function Page() {
+  return (
+    <div>
+      <Waitlist fallback={<>Loading waitlist</>} />
+    </div>
+  );
+}
diff --git a/integration/testUtils/appPageObject.ts b/integration/testUtils/appPageObject.ts
@@ -13,7 +13,7 @@ export const createAppPageObject = (testArgs: { page: Page }, app: Application)
         // do not fail the test if interstitial is returned (401)
       }
     },
-    goToRelative: (path: string, opts: { searchParams?: URLSearchParams; timeout?: number } = {}) => {
+    goToRelative: (path: string, opts: { waitUntil?: any; searchParams?: URLSearchParams; timeout?: number } = {}) => {
       let url: URL;
 
       try {
@@ -35,7 +35,7 @@ export const createAppPageObject = (testArgs: { page: Page }, app: Application)
       if (opts.searchParams) {
         url.search = opts.searchParams.toString();
       }
-      return page.goto(url.toString(), { timeout: opts.timeout ?? 20000 });
+      return page.goto(url.toString(), { timeout: opts.timeout ?? 20000, waitUntil: opts.waitUntil });
     },
     waitForClerkJsLoaded: async () => {
       return page.waitForFunction(() => {
diff --git a/integration/tests/components.test.ts b/integration/tests/components.test.ts
diff --git a/packages/nextjs/src/client-boundary/uiComponents.tsx b/packages/nextjs/src/client-boundary/uiComponents.tsx
diff --git a/packages/react/src/components/ClerkHostRenderer.tsx b/packages/react/src/components/ClerkHostRenderer.tsx
diff --git a/packages/react/src/components/uiComponents.tsx b/packages/react/src/components/uiComponents.tsx
diff --git a/packages/react/src/components/withClerk.tsx b/packages/react/src/components/withClerk.tsx
diff --git a/packages/react/src/errors/messages.ts b/packages/react/src/errors/messages.ts
diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts
diff --git a/packages/react/src/utils/useWaitForComponentMount.ts b/packages/react/src/utils/useWaitForComponentMount.ts

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@ import { UserProfile } from '@clerk/nextjs';`
`3`	`3`	`export default function Page() {`
`4`	`4`	`return (`
`5`	`5`	`<div>`
`6`		`- <UserProfile />`
	`6`	`+ <UserProfile fallback={<>Loading user profile</>} />`
`7`	`7`	`</div>`
`8`	`8`	`);`
`9`	`9`	`}`