Guard Clerk-dependent UI
A child component calls Clerk APIs or reads the global Clerk instance.
Clerk · Component
ClerkLoaded
ClerkLoaded renders its children after Clerk has loaded and makes the Clerk object available under window.Clerk. The loaded state includes ready and degraded statuses.
How it works
ClerkLoaded conditionally renders its children once Clerk has finished loading. At that point, the Clerk object is available through window.Clerk, and the loaded state includes both ready and degraded statuses, so it is useful for components that need Clerk access.
Syntax
<ClerkLoaded>...</ClerkLoaded>Returns
Renders its children after Clerk has loaded; otherwise renders no children.
Key points
- The component displays its children only after Clerk has completed loading.
- The loaded condition covers both ready and degraded Clerk statuses.
- After the condition is met, child code can access the Clerk object through the global window.Clerk property.
- Use the component around child UI that needs to interact with Clerk.
- Keep the boundary narrow instead of placing the component around the entire application.
Common mistakes
- Avoid wrapping the whole application; scope ClerkLoaded to components that actually need access to Clerk.
Example: Render content after Clerk loads
import { ClerkLoaded } from '@clerk/nextjs'
export default function Page() {
return (
<ClerkLoaded>
<p>Clerk is ready to use.</p>
</ClerkLoaded>
)
}Renders the paragraph only after Clerk has loaded.
When to use it
Delay dependent controls
An application needs to show authenticated-app controls only after Clerk initialization completes.
Protect custom flows
A page provides custom sign-in or sign-up flows that require Clerk to be initialized.
Interview questions
QWhat does ClerkLoaded do?
ClerkLoaded renders its children only after Clerk has loaded. The documented loaded condition includes both ready and degraded states, and the Clerk object is then available under window.Clerk.
Follow-up: What should be rendered while Clerk is still loading? Use ClerkLoading for content that should appear during the loading phase, then place the loaded content in ClerkLoaded.
QWhy use ClerkLoaded instead of checking window.Clerk manually?
It is a control component that gates child rendering based on Clerk's loading state. This lets child components use Clerk without separately checking whether the global Clerk object exists.
Follow-up: How should an application handle a degraded loaded state? Keep the loaded UI available through ClerkLoaded and optionally nest ClerkDegraded to show an issue-specific message.
QWhere should ClerkLoaded be placed in an application?
Import ClerkLoaded from the SDK package for the framework in use, such as @clerk/nextjs. Wrap only the UI that requires Clerk access rather than the entire app.
Follow-up: How can loading and failure states be represented alongside it? Pair ClerkLoaded with ClerkLoading for loading feedback and ClerkFailed for failures.
Related
ClerkLoadingClerkDegradedClerkFailed