feat(ui): Add MFA section + flow by austincalvelage · Pull Request #9802 · clerk/javascript

austincalvelage · 2026-09-16T23:22:31Z

Description

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

changeset-bot · 2026-09-16T23:22:36Z

🦋 Changeset detected

Latest commit: 572907f

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

vercel · 2026-09-16T23:22:37Z

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

Project	Deployment	Actions	Updated
swingset	Ready	Preview	Sep 18, 2026 10:55pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
clerk-js-sandbox	Skipped		Sep 18, 2026 10:55pm UTC

coderabbitai · 2026-09-16T23:22:39Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Added reusable MFA enrollment views and dialogs for SMS, authenticator apps, and backup codes. Shared phone steps replaced duplicated phone-dialog logic. Added MFA method management, localization, styles, exports, SwingSet fixtures, stories, and extensive Mosaic and fixture tests. Added SwingSet Vitest configuration and package scripts.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: 🟡 Moderate · up to d407b

The added MFA test can fail because prior clipboard calls remain recorded, and authenticator-only users receive inaccurate backup-code recovery guidance. Resolve these localized defects before merging.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 36 functions across 44 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	❓ Inconclusive	The description contains only the pull request template and checklist. It does not provide a meaningful summary of the MFA changes or testing instructions.	Add a brief description of the MFA section and flow, including the main user-facing changes and the tests or commands used to validate them.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding the MFA section and flow to the UI.
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 5.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 36 functions across 44 files. (2 skipped: 2 unsupported.)

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

pkg-pr-new · 2026-09-16T23:26:23Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9802

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9802

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9802

@clerk/expo

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

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9802

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@9802

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 572907f

maxyinger

Everything looks good. This is a big boi, so in favor of just getting it in and doing polish followups.

Main question on this one is do we plan on using these dialogs anywhere?

user-profile-add-authenticator.dialog.tsx
user-profile-add-sms.dialog.tsx
user-profile-backup-codes.dialog.tsx

Outside of that only thing that doesn't feel quite right is the copy banner in the authenticator setup view, but feels like something new we should discuss with design

Nice work!

maxyinger · 2026-09-18T19:54:41Z

+        <UserProfileAuthenticatorSetupView
+          {...setup}
+          onCopy={onCopy}
+          copyStatus={copyStatus}
+          copyErrorMessage={copyErrorMessage}
+        />
+      ) : (
+        <>
+          <Card.Header>
+            <Card.Title>{setupMessages.title}</Card.Title>
+          </Card.Header>


Polish follow up, but these two being just slightly different heights makes me either want to either:

be able to temporarily disable the height animation from inside a flow

or force them to be the same height

Asked Preston here about restructuring in away they maintain the same height. https://www.figma.com/design/yt5qKlfNyIIdaKaMoav1v2/Clerk-Mosaic-2.0?node-id=9578-28439#1933135188

If not we can look into disabling height animations within the flow.

Combobox tests this

into austin/mfa-section

github-actions Bot added the ui label Sep 16, 2026

vercel Bot deployed to Preview – swingset September 16, 2026 23:24 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox September 17, 2026 00:18 View deployment

vercel Bot deployed to Preview – swingset September 17, 2026 00:21 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox September 17, 2026 15:52 View deployment

vercel Bot deployed to Preview – swingset September 17, 2026 15:54 View deployment

austincalvelage force-pushed the austin/mfa-section branch from 1ab3e68 to 424fbf1 Compare September 17, 2026 16:19

github-actions Bot added the mosaic label Sep 17, 2026

vercel Bot deployed to Preview – clerk-js-sandbox September 17, 2026 16:20 View deployment

vercel Bot deployed to Preview – swingset September 17, 2026 16:22 View deployment

vercel Bot temporarily deployed to Preview – clerk-js-sandbox September 17, 2026 16:35 Inactive

vercel Bot deployed to Preview – swingset September 17, 2026 16:37 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox September 17, 2026 17:48 View deployment

vercel Bot deployed to Preview – swingset September 17, 2026 17:49 View deployment

vercel Bot temporarily deployed to Preview – clerk-js-sandbox September 17, 2026 17:58 Inactive

vercel Bot deployed to Preview – swingset September 17, 2026 18:01 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox September 17, 2026 21:59 View deployment

vercel Bot deployed to Preview – swingset September 17, 2026 22:00 View deployment

austincalvelage force-pushed the austin/mfa-section branch from 50b2384 to 8ddc9a8 Compare September 17, 2026 22:16

vercel Bot deployed to Preview – clerk-js-sandbox September 17, 2026 22:17 View deployment

vercel Bot deployed to Preview – swingset September 17, 2026 22:18 View deployment

austincalvelage force-pushed the austin/mfa-section branch from 8ddc9a8 to 4f34242 Compare September 17, 2026 22:20

vercel Bot deployed to Preview – clerk-js-sandbox September 17, 2026 22:21 View deployment

vercel Bot deployed to Preview – swingset September 17, 2026 22:23 View deployment

austincalvelage requested a review from maxyinger September 17, 2026 22:27

austincalvelage marked this pull request as ready for review September 17, 2026 22:27

austincalvelage added 7 commits September 18, 2026 13:30

test(mosaic): remove redundant MFA coverage and unused fixture

fb3ba18

refactor(mosaic): align MFA default action with phone and email

e0acbdf

fix(mosaic): localize MFA views

e718268

fix(mosaic): focus primary backup code actions

a0ec923

chore(mosaic): account for MFA localization in bundle budget

66370ea

refactor(mosaic): share MFA setup flow and simplify dialog examples

9672458

test(mosaic): isolate MFA picker interaction in security panel

bdecd18

austincalvelage force-pushed the austin/mfa-section branch from c66edcf to bdecd18 Compare September 18, 2026 19:31

vercel Bot deployed to Preview – clerk-js-sandbox September 18, 2026 19:32 View deployment

vercel Bot deployed to Preview – swingset September 18, 2026 19:33 View deployment

maxyinger approved these changes Sep 18, 2026

View reviewed changes

austincalvelage added 4 commits September 18, 2026 14:16

fix(test):Remove redundant phone input check

0bba99d

Combobox tests this

refactor(mosaic): remove standalone MFA dialogs

687514d

fix(mosaic): focus authenticator code when setup is ready

9684fd7

fix(mosaic): return MFA setup to method picker on Back

ea6c3b1

vercel Bot temporarily deployed to Preview – clerk-js-sandbox September 18, 2026 21:07 Inactive

fix(mosaic): use pulse easing token and preview backup-code loading

0d78404

vercel Bot deployed to Preview – swingset September 18, 2026 21:30 View deployment

austincalvelage added 3 commits September 18, 2026 15:35

fix(mosaic): keep authenticator copy feedback within each field

c556e04

fix(mosaic): make backup-code recovery wording method-neutral

40eb4be

Merge branch 'main' into austin/mfa-section

c959bcc

austincalvelage enabled auto-merge (squash) September 18, 2026 21:45

vercel Bot deployed to Preview – clerk-js-sandbox September 18, 2026 21:58 View deployment

vercel Bot deployed to Preview – swingset September 18, 2026 22:01 View deployment

austincalvelage added 2 commits September 18, 2026 16:52

Merge branch 'main' into austin/mfa-section

0473adc

Merge branch 'austin/mfa-section' of https://github.com/clerk/javascript

572907f

into austin/mfa-section

vercel Bot temporarily deployed to Preview – clerk-js-sandbox September 18, 2026 22:53 Inactive

vercel Bot deployed to Preview – swingset September 18, 2026 22:55 View deployment

austincalvelage merged commit 4ff463a into main Sep 18, 2026
145 of 148 checks passed

austincalvelage deleted the austin/mfa-section branch September 18, 2026 23:56

Navigation Menu

feat(ui): Add MFA section + flow - #9802

feat(ui): Add MFA section + flow#9802
austincalvelage merged 41 commits into
mainfrom
austin/mfa-section

austincalvelage commented Sep 16, 2026

Uh oh!

changeset-bot Bot commented Sep 16, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 16, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 16, 2026 •

edited

Loading

Reviews paused

Walkthrough

❌ Failed checks (1 warning, 1 inconclusive)

Uh oh!

pkg-pr-new Bot commented Sep 16, 2026 •

edited

Loading

Uh oh!

maxyinger left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maxyinger Sep 18, 2026

Uh oh!

austincalvelage Sep 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

austincalvelage commented Sep 16, 2026

Description

Checklist

Type of change

Uh oh!

changeset-bot Bot commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

❌ Failed checks (1 warning, 1 inconclusive)

Uh oh!

pkg-pr-new Bot commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maxyinger left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maxyinger Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

austincalvelage Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Sep 16, 2026 •

edited

Loading

vercel Bot commented Sep 16, 2026 •

edited

Loading

coderabbitai Bot commented Sep 16, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 16, 2026 •

edited

Loading