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

BRKalow · 2024-12-05T20:33:02Z

Description

Introduces a new fallback prop to Clerk's components. This lets users render a placeholder while Clerk is loading and the component mounts. Use to avoid layout shift and improve the loading UX.

Usage:

<SignIn fallback={<>Loading...</>} />

fixes SDKI-795

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

changeset-bot · 2024-12-05T20:33:06Z

🦋 Changeset detected

Latest commit: 952b536

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@clerk/clerk-react	Minor
@clerk/chrome-extension	Patch
@clerk/elements	Patch
@clerk/clerk-expo	Patch
@clerk/nextjs	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/tanstack-start	Patch
@clerk/ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2024-12-05T20:33:06Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 20, 2024 7:38pm

…omponents exposed through clerk/nextjs

jacekradko · 2024-12-10T03:30:40Z

packages/nextjs/src/client-boundary/uiComponents.tsx

@@ -6,7 +6,7 @@ import {
  SignUp as BaseSignUp,
  UserProfile as BaseUserProfile,
 } from '@clerk/clerk-react';
-import type { OrganizationProfileProps, SignInProps, SignUpProps, UserProfileProps } from '@clerk/types';
+import type { ComponentProps } from 'react';


BRKalow · 2024-12-10T03:34:15Z

packages/react/src/utils/useWaitForComponentMount.ts

+          if (!elementToWatch && selector) {
+            elementToWatch = root?.querySelector(selector);
+          }


There's most definitely a smarter way to do this, it's not the most efficient to re-query on each observed mutation, but given that it's scoped to the time the component mounts to the time the clerk-js mount happens it shouldn't be running too many times...

BRKalow · 2024-12-10T03:35:29Z

packages/react/src/components/withClerk.tsx

+    if (!clerk.loaded && !options?.renderWhileLoading) {
      return null;
    }


I added rendering of the fallback here initially, instead of allowing the component to render, but the fallback element was then injected twice.

BRKalow · 2024-12-10T03:36:00Z

packages/react/src/components/ClerkHostRenderer.tsx

+ * Used to orchestrate mounting of Clerk components in a host React application.
+ * Components are rendered into a specific DOM node using mount/unmount methods provided by the Clerk class.
+ */
+export class ClerkHostRenderer extends React.PureComponent<


This is largely unchanged from the previous Portal component. I renamed it to avoid confusion with React's portal primitive.

BRKalow · 2024-12-10T03:37:28Z

packages/react/src/components/uiComponents.tsx

-    />
-  );
-}, 'SignIn');
+export const SignIn = withClerk(


The diff for each component is mostly identical. I might take a pass at trying to DRY this up, but defaulting to avoiding too much abstraction.

BRKalow · 2024-12-10T03:39:03Z

packages/react/src/utils/useWaitForComponentMount.ts

+/**
+ * Used to detect when a Clerk component has been added to the DOM.
+ */
+function waitForElementChildren(options: { selector?: string; root?: HTMLElement | null; timeout?: number }) {


This is somewhat of a brutce-force way of detecting when one of our components mounts. Instead of trying to plumb through some sort of event or callback to internal clerk-js components, I'm instead using a MutationObserver here to detect changes to the DOM. When the root element of the renderer has children (injected by clerk-js) we can assume the component has mounted.

BRKalow · 2024-12-10T03:40:43Z

packages/react/src/components/uiComponents.tsx

+    const rendererRootProps = {
+      ...(shouldShowFallback && fallback && { style: { display: 'none' } }),
+    };


ClerkHostRenderer always has to render, which is why we can't use Suspense, so to ensure the fallback and the component aren't mounted at the same time, we apply display: none to the renderer while the fallback is loading.

alexcarpenter

Looking good to me so far!

alexcarpenter · 2024-12-10T15:36:01Z

packages/react/src/components/uiComponents.tsx

    const { customPages, customPagesPortals } = useUserProfileCustomPages(props.children);
    return (
-      <Portal
+      <ClerkHostRenderer


Missing the rendering of fallback here for UserProfile

✅ 67e8e2e

panteliselef · 2024-12-10T15:51:41Z

packages/react/src/components/uiComponents.tsx

    );
  },
-  'UserProfile',
+  { component: 'UserProfile', renderWhileLoading: true },


In which scenario do we want this to be false ?

The existing behavior is for withClerk() to not render its children until Clerk has loaded. We use it for most other components, so this lets us retain existing behavior without making a larger refactor.

I do think it's worth dropping the option in the future, we'll just need to update all usages 👍

panteliselef · 2024-12-10T15:54:37Z

packages/react/src/components/uiComponents.tsx

+    const shouldShowFallback = mountingStatus === 'rendering' || !clerk.loaded;
+
+    const rendererRootProps = {
+      ...(shouldShowFallback && fallback && { style: { display: 'none' } }),


for accessibility reasons maybe we should go with <div hidden> instead of a css rule ?

@panteliselef whats the reasoning? Wouldn't hidden be equivalent since the browsers default style for hidden is display: none?

styling wise yes, it's kind of nitpicking tbh, but afiak screen readers don't respect display:none; but respect hidden.

Got it, I think it should be alright, since its just hiding the container for the components to be rendered into until the components have loaded. The loading text sits outside of it, so it is accessible to users.

panteliselef · 2024-12-10T16:00:03Z

packages/react/src/utils/useWaitForComponentMount.ts

+      watcherRef.current = waitForElementChildren({ selector: `[data-clerk-component="${component}"]` })
+        .then(() => {
+          setStatus('rendered');
+        })
+        .catch(() => {
+          setStatus('error');
+        });
+    }


I'm sure this works, but do you think we should something on cleanup and disconnect the observer or don't update the state ?

Support for fallback prop

8441ba5

clerk-cookie added the react label Dec 5, 2024

vercel bot deployed to Preview December 5, 2024 20:34 View deployment

panteliselef mentioned this pull request Dec 5, 2024

experiment(nextjs): Suspended SignIn Component #4668

Closed

9 tasks

Refactor implementation to live outside of ClerkHostRenderer

d78aa6b

vercel bot deployed to Preview December 9, 2024 21:03 View deployment

Adds fallback prop to remaining components

ec8fa36

vercel bot deployed to Preview December 10, 2024 02:03 View deployment

Adds changeset

c2f8a49

vercel bot deployed to Preview December 10, 2024 03:02 View deployment

Adds simple tests for sign in fallback, and cleans up prop types of c…

e10c5e4

…omponents exposed through clerk/nextjs

clerk-cookie added nextjs integration labels Dec 10, 2024

vercel bot deployed to Preview December 10, 2024 03:27 View deployment

jacekradko reviewed Dec 10, 2024

View reviewed changes

BRKalow commented Dec 10, 2024

View reviewed changes

BRKalow requested a review from a team December 10, 2024 03:43

alexcarpenter reviewed Dec 10, 2024

View reviewed changes

alexcarpenter requested a review from a team December 10, 2024 15:37

render UserProfile fallback

67e8e2e

vercel bot deployed to Preview December 10, 2024 15:47 View deployment

panteliselef reviewed Dec 10, 2024

View reviewed changes

vercel bot deployed to Preview December 17, 2024 03:24 View deployment

clerk-cookie added expo chrome-extension themes elements express testing tanstack labels Dec 20, 2024

vercel bot deployed to Preview December 20, 2024 05:36 View deployment

Expand component test suite

87495b6

BRKalow force-pushed the brk.feat/fallback-prop branch from b10ec6c to 87495b6 Compare December 20, 2024 05:38

clerk-cookie removed types clerk-js remix backend fastify localizations sdk-node expo chrome-extension themes elements express testing tanstack labels Dec 20, 2024

vercel bot deployed to Preview December 20, 2024 05:40 View deployment

Merge branch 'main' into brk.feat/fallback-prop

952b536

vercel bot deployed to Preview December 20, 2024 19:38 View deployment

BRKalow merged commit b5eb15b into main Dec 20, 2024
28 of 29 checks passed

BRKalow deleted the brk.feat/fallback-prop branch December 20, 2024 19:45

clerk-cookie mentioned this pull request Dec 20, 2024

ci(repo): Version packages #4814

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

BRKalow commented Dec 5, 2024 •

edited

Loading

changeset-bot bot commented Dec 5, 2024 •

edited

Loading

vercel bot commented Dec 5, 2024 •

edited

Loading

jacekradko Dec 10, 2024

BRKalow Dec 10, 2024

BRKalow Dec 10, 2024

BRKalow Dec 10, 2024

BRKalow Dec 10, 2024

BRKalow Dec 10, 2024

BRKalow Dec 10, 2024

alexcarpenter left a comment

alexcarpenter Dec 10, 2024

alexcarpenter Dec 10, 2024

panteliselef Dec 10, 2024

BRKalow Dec 17, 2024

panteliselef Dec 10, 2024

alexcarpenter Dec 10, 2024 •

edited

Loading

panteliselef Dec 10, 2024

alexcarpenter Dec 10, 2024

panteliselef Dec 10, 2024

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

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

Conversation

BRKalow commented Dec 5, 2024 • edited Loading

Description

Checklist

Type of change

changeset-bot bot commented Dec 5, 2024 • edited Loading

🦋 Changeset detected

vercel bot commented Dec 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexcarpenter left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexcarpenter Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BRKalow commented Dec 5, 2024 •

edited

Loading

changeset-bot bot commented Dec 5, 2024 •

edited

Loading

vercel bot commented Dec 5, 2024 •

edited

Loading

alexcarpenter Dec 10, 2024 •

edited

Loading