feat(clerk-react,clerk-js, types,shared): Introduce Clerk.status

[panteliselef]

Description

Introduce useClerk().status, Clerk.status alongside <ClerkFailed/> and <ClerkDegraded/>.

useClerk().status

Possible values are:

• loading (initial state)
• error set when hotloading clerk-js failed or Clerk.load() failed
• ready set when Clerk is fully operational
• degraded set when Clerk is partially operational

useClerk().loaded is true when useClerk().status is either "ready" or "degraded".
useClerk().loaded is false when useClerk().status is "loading" or "error".

Important

🚨🚨 Clerk.status becomes loading upon instantiation not upon calling .load()

New APIs

const handler = (status)=> {}
window.Clerk.on('status', handler)
window.Clerk.off('status', handler)

on()

Calls handler on every status event with the new status as parameter

window.Clerk.on('status',(status)=>{})

Calls handler immediately with the last payload of the event.

window.Clerk.on('status',(status)=>{}, {notify:true})

off()

Accepts a handler to unregister from the specified event.

window.Clerk.off('status',handler)

Removes all handlers for the specified event.

window.Clerk.off('status')

New Components

<ClerkFailed/>

<ClerkLoaded>
  <MyCustomSignInForm/>
</ClerkLoaded>
<ClerkFailed>
  <ContactSupportBanner/>
</ClerkFailed>

<ClerkDegraded/>

<ClerkLoaded>
  <MyCustomPasskeyRegistration/>
  <ClerkDegraded>
    We are experiencing issues, registering a passkey might fail. 
  </ClerkDegraded>
</ClerkLoaded>

Clerk.status values

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[vercel]

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	Apr 18, 2025 0:08am

[changeset-bot]

🦋 Changeset detected

Latest commit: b04005d

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

This PR includes changesets to release 22 packages

Name	Type
@clerk/nextjs	Minor
@clerk/clerk-react	Minor
@clerk/clerk-js	Minor
@clerk/types	Minor
@clerk/chrome-extension	Patch
@clerk/elements	Patch
@clerk/clerk-expo	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/nuxt	Patch
@clerk/shared	Patch
@clerk/testing	Patch
@clerk/themes	Patch
@clerk/vue	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

[jacekradko]

!snapshot

[Copilot]

Pull Request Overview

This PR introduces a new status tracking property for Clerk, allowing developers to distinguish between different operational states ("loading", "error", "ready", and "degraded"). It updates the core Clerk implementation, React hooks, context providers, and UI components to leverage the new Clerk.status and adjust the computed loaded flag accordingly.

• Adds a new Clerk.status property with corresponding event handling.
• Refactors many loading checks across the SDK to use Clerk.status.
• Introduces new React components ( and ) and updates tests/documentation to support the new status logic.

Reviewed Changes

Copilot reviewed 20 out of 24 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/react/src/isomorphicClerk.ts	Introduces Clerk.status, replaces internal loaded checks
packages/react/src/hooks/utils.ts	Updates event listener to use Clerk.status
packages/react/src/contexts/ClerkContextProvider.tsx	Refactors context to derive state from Clerk.status
packages/react/src/components/*	Adjusts control components to render based on the new status
packages/nextjs/*	Updates Next.js integrations similarly
packages/clerk-js/src/core/*	Revises the core Clerk logic and error handling to emit proper status
integration/tests/*	Adds tests to verify correct status transitions
.changeset/*	Updates changesets to document the new status feature

Files not reviewed (4)

• .typedoc/tests/snapshots/file-structure.test.ts.snap: Language not supported
• packages/chrome-extension/src/tests/snapshots/exports.test.ts.snap: Language not supported
• packages/clerk-js/bundlewatch.config.json: Language not supported
• packages/react-router/src/tests/snapshots/exports.test.ts.snap: Language not supported