feat(ui): add multiSessionStart prop to SignIn (render in place)

[djgould]

Description

Alternative to #9651 (and #9683) that renders the switcher in place instead of redirecting to it. Same feature, no router replace option needed.

Adds a multiSessionStart prop to <SignIn />. With multiSessionStart="switcher", a signed-in user on a multi-session instance sees the account switcher on the sign-in start screen instead of the sign-in form. The default "form" keeps today's behavior. The prop is ignored in single-session mode.

Why. FAPI sends OAuth consent requests through signInUrl?redirect_url=… and expects the sign-in UI to forward users who are already signed in. That only happens in single-session mode. On multi-session instances (for example clerk auth login against the dashboard) a signed-in user has to sign in again.

How it works

• The start screen renders <SignInAccountSwitcher /> when the prop is set, sessions exist, and __clerk_add_account is not in the URL. No redirect, no history entry, so Back goes to the previous page. The choose route still exists for deep links and for clerk-js after a single sign-out.
• The "is anyone signed in" check runs once when the screen mounts. Signing in on the form adds a session before the after-sign-in redirect runs, and a live check would swap the form for the switcher mid-flow.
• "Add account" on the switcher navigates within the router to the start screen with __clerk_add_account=true. The start screen shows the form when it is set. The router keeps it across internal navigation and the OAuth / email-link callback, so a failed attempt comes back to the form with its error. This also works inside a modal.
• "Add account" from <UserButton /> and the Mosaic user button adds the same flag to the sign-in URL, so they land on the form instead of the switcher.
• "Add account" from the switcher keeps the current redirect_url.
• Hash router fix: navigating to the index route with a query produced #?x, which the router does not read as a fragment URL. It now produces #/?x.

Compared to #9651: no replace plumbing (drops #9683 as a dependency), the switcher's "Add account" is an in-app navigation instead of a full page load, and the modal shows the form instead of leaving the page. Cost: the switcher takes an addAccountPath prop because it is mounted both in place (.) and on the choose route (..).

Prior art: #9583.

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:

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 10, 2026 1:44pm UTC
swingset	Error		Sep 10, 2026 1:44pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 023b8a5

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/ui	Minor
@clerk/shared	Minor
@clerk/astro	Patch
@clerk/chrome-extension	Patch
@clerk/react	Patch
@clerk/swingset	Patch
@clerk/vue	Patch
@clerk/backend	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	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

[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: ASSERTIVE

Plan: Team

Run ID: 8298ee50-19f0-441b-8217-bb33b63cb42e

📥 Commits

Reviewing files that changed from the base of the PR and between 3037d91 and 023b8a5.

📒 Files selected for processing (16)

• .changeset/signin-multisession-start.md
• packages/shared/src/internal/clerk-js/constants.ts
• packages/shared/src/internal/clerk-js/url.ts
• packages/shared/src/types/clerk.ts
• packages/ui/src/components/SignIn/SignInAccountSwitcher.tsx
• packages/ui/src/components/SignIn/SignInStart.tsx
• packages/ui/src/components/SignIn/__tests__/SignInAccountSwitcher.test.tsx
• packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx
• packages/ui/src/components/UserButton/__tests__/UserButton.test.tsx
• packages/ui/src/components/UserButton/useMultisessionActions.tsx
• packages/ui/src/contexts/components/SignIn.ts
• packages/ui/src/mosaic/user-button/__tests__/user-button.model.test.tsx
• packages/ui/src/mosaic/user-button/user-button.model.tsx
• packages/ui/src/router/HashRouter.tsx
• packages/ui/src/router/__tests__/BaseRouter.test.tsx
• packages/ui/src/router/__tests__/HashRouter.test.tsx

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)

Included review availability: 9 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

---

📝 Walkthrough

Walkthrough

Adds the multiSessionStart option to select the initial sign-in view. Multi-session sign-in can render an account switcher when signed-in sessions exist. Add-account navigation now uses __clerk_add_account=true, preserves the marker through OAuth and email-link flows, and supports custom paths. UserButton and mosaic UserButton use the same URL builder. Hash routing now normalizes query-only index routes.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Suggested reviewers: alexcarpenter

Merge Risk: ⚪ Minimal · up to 023b8

This adds an opt-in account-switcher entry for multi-session sign-in while preserving the default form flow and carrying add-account navigation through supported paths. No concrete merge-blocking risk is identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 15 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: adding the multiSessionStart prop to <SignIn /> and rendering the switcher in place.
Description check	✅ Passed	The description directly explains the new multiSessionStart feature, its behavior, routing changes, and related add-account flows.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 15 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

Warning

Linked repositories: Your configuration references 7 linked repositories, but your current plan allows 5. Analyzed clerk/clerk_go, clerk/dashboard, clerk/accounts, clerk/backoffice, clerk/clerk, skipped clerk/clerk-docs, clerk/cloudflare-workers.

---

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