Custom loading UI
An application needs branded or contextual feedback while authentication initializes.
Clerk · Component
ClerkLoading
ClerkLoading renders its children while Clerk initializes. Use it to show custom loading feedback before Clerk becomes available.
How it works
ClerkLoading conditionally renders its children during Clerk initialization, allowing a custom loading UI. Pair it with ClerkLoaded for the content that should appear after Clerk becomes available, and scope it to components that need Clerk rather than wrapping the entire application.
Syntax
<ClerkLoading>{children}</ClerkLoading>Returns
Conditionally renders its children while Clerk is loading.
Key points
- Its child elements are visible during Clerk initialization.
- Use it to provide application-specific loading feedback.
- In Next.js, import the control component from the @clerk/nextjs package.
Common mistakes
- Do not wrap the whole application; limit the component to UI that requires access to Clerk.
- A narrow scope avoids making unrelated application content depend on Clerk's loading state.
Example: Show a loading state
import { ClerkLoaded, ClerkLoading } from '@clerk/nextjs'
export default function Page() {
return (
<>
<ClerkLoading>
<p>Loading authentication…</p>
</ClerkLoading>
<ClerkLoaded>
<p>Authentication is ready.</p>
</ClerkLoaded>
</>
)
}Displays a temporary message while Clerk initializes, then renders the loaded-state content.
When to use it
Loading and ready state transitions
A page must separate initialization content from post-initialization content.
Scoped Clerk-dependent rendering
Only a small section of the interface depends on Clerk becoming available.
Interview questions
QWhat does ClerkLoading render, and when?
ClerkLoading renders its children while Clerk is loading, so it is useful for a custom authentication loading state. Once Clerk is ready, that content is replaced by the corresponding loaded-state UI.
Follow-up: How would you render both transitional and ready states? Use ClerkLoading for the temporary UI and ClerkLoaded for the post-initialization content.
QHow is ClerkLoading used in a Next.js component?
Import ClerkLoading from the SDK package used by the application, such as @clerk/nextjs. Place the component around the loading content that should be visible during Clerk initialization.
Follow-up: What should determine its scope? Only components that need access to the Clerk object should be wrapped.
QWhy would an application use ClerkLoading?
The component is intended for custom loading feedback rather than for providing authentication controls itself. It conditionally displays its children during Clerk's loading phase.
Follow-up: What complementary control component handles the opposite state? ClerkLoaded renders content after Clerk has loaded.
Related
ClerkLoadedClerkDegradedClerkFailed