docs(repo): Revise and clarify isLoaded description and tab title

[SarahSoutoul]

Description

Linear ticket: https://linear.app/clerk/issue/DOCS-11007/revise-and-clarify-isloaded-description-and-tab-title

This PR updates the description of isLoaded across hooks (useAuth, useUser, useSession, etc.) to better reflect its actual behavior.

Previously, the docs described isLoaded as:

“Initially false, becomes true once Clerk loads.”

This wording implies a one-time initialization phase. In practice, isLoaded represents whether the current authentication state is resolved, and can temporarily revert to false during auth updates (e.g. when switching organizations via setActive).

Here are the changes I applied:

• Updated isLoaded descriptions to clarify that:
  • It starts as false and becomes true once loaded BUT may temporarily return to false while auth state is updating
  • Replaced “initialization” language with “current authentication state” for better accuracy
  • Added a concrete example (switching organizations) to make this behaviour clearer

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 GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Apr 21, 2026 3:18pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 2370534

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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

[Ephem]

Much clearer, thank you!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 49eb4500-a0ed-4a2b-bc47-be763468909d

📥 Commits

Reviewing files that changed from the base of the PR and between 69a8258 and 2370534.

📒 Files selected for processing (3)

• packages/shared/src/react/hooks/useOrganization.tsx
• packages/shared/src/react/hooks/useOrganizationList.tsx
• packages/shared/src/types/hooks.ts

✅ Files skipped from review due to trivial changes (2)

• packages/shared/src/react/hooks/useOrganizationList.tsx
• packages/shared/src/types/hooks.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/shared/src/react/hooks/useOrganization.tsx

---

📝 Walkthrough

Walkthrough

Updated JSDoc for the isLoaded property across multiple hook return types in the shared package: useOrganization, useOrganizationList, and several types in packages/shared/src/types/hooks.ts (including UseAuthReturn, UseSessionReturn, UseUserReturn, UseSignInReturn, UseSignUpReturn, UseSessionListReturn). The documentation now clarifies that isLoaded indicates whether Clerk has loaded the current authentication state and may temporarily revert to false during auth state transitions (e.g., switching organizations). No runtime logic, type signatures, or exported APIs were changed. A new empty .changeset file was added.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: revising and clarifying the isLoaded description across the codebase, which is the core objective of this PR.
Description check	✅ Passed	The description clearly explains the motivation, previous wording, new wording, and specific changes made to isLoaded JSDoc comments across multiple hooks.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8336

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8336

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8336

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8336

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8336

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8336

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8336

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8336

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8336

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8336

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8336

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8336

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8336

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8336

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8336

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8336

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8336

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8336

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8336

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8336

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8336

commit: 2370534

[manovotny]

Pushed some refinements directly in 2370534.

• useAuth, useSession, useUser, useOrganization, useOrganizationList — kept the revised "loaded the current authentication state" + transient-revert wording, but polished: "revert to false" (matches your PR description and Fredrik's Linear comment) and a concrete setActive() reference for the example.
• useOrganizationList specifically — restored the "and there is an authenticated user" / "once Clerk loads with a user" language. The implementation is !!(clerk.loaded && user) (packages/shared/src/react/hooks/useOrganizationList.tsx:312), so without that clause the docs imply signed-out consumers will eventually see isLoaded: true, which they won't.
• useSignIn, useSignUp, useSessionList — reverted these three to the previous "completed initialization" wording. These hooks are client-side (they check if (!client) in packages/react/src/hooks/legacy/useSignIn.ts:60, useSignUp.ts:60, and packages/shared/src/react/hooks/useSessionList.ts:59), and Clerk.#setTransitiveState (packages/clerk-js/src/core/clerk.ts:3242) clears session/user/organization but not client. So these three don't flip back to isLoaded: false during setActive() / org switching — the org-switch example was inaccurate for them.

LMK if any of this feels wrong to you.

[manovotny]

Separate thread: the PR title mentions "and tab title" and the Linear ticket specifically calls out "Initialization" being misleading, but the @unionReturnHeadings arrays are untouched — so the tab label users see on https://clerk.com/docs hasn't changed.

Current labels:

• packages/react/src/hooks/useAuth.ts:36 — ["Initialization", "Signed out", "Signed in (no active organization)", "Signed in (with active organization)"]
• packages/shared/src/react/hooks/useUser.ts:11 — ["Initialization", "Signed out", "Signed in"]
• packages/shared/src/react/hooks/useSession.ts:13 — ["Initialization", "Signed out", "Signed in"]
• packages/react/src/hooks/legacy/useSignIn.ts:12 — ["Initialization", "Loaded"]
• packages/react/src/hooks/legacy/useSignUp.ts:12 — ["Initialization", "Loaded"]
• packages/shared/src/react/hooks/useSessionList.ts:11 — ["Initialization", "Loaded"]

"Loading" would be my suggestion — maps directly to isLoaded, reads naturally alongside "Signed in" / "Signed out" / "Loaded", and unlike "Initialization" it's accurate both at startup and during the transient setActive flip (for the hooks that actually have that flip). For the three client-backed hooks it's still accurate as a startup label.