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 10, 2025 11:38am

[changeset-bot]

🦋 Changeset detected

Latest commit: 55da252

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

[LekoArts]

Overall LGTM, some smaller comments

My comments were addressed, so no reason to block this