feat(ui): connect the Mosaic UserButton and its custom UserProfile pages by alexcarpenter · Pull Request #9191 · clerk/javascript

alexcarpenter · 2026-07-17T16:00:30Z

Description

Stacked on #9185. Covers the connected UserButton through the real view and the real controller against a mocked Clerk, settles the popover behaviour that coverage exposed, and carries the app's own pages into the UserProfile the button opens.

One flow, one machine. The popover's open state and the one action in flight are the same flow: an action that ends the interaction closes the surface, so they settle together or not at all. user-button.machine.ts holds both instead of two useStates in the container. Re-entry, clearing busy, and closing on success stop being hand written there: RUN is simply unhandled while busy, and busy is only reachable from open. Dismissing the popover mid action now abandons the result rather than letting it land in a surface that is already gone.

The surface holds still while an action runs. The view renders the controller the action started from. setActive swaps the active organization while its promise is in flight, so the live controller would otherwise rearrange the popup under the pointer: the header renaming itself, the check jumping rows, Invite coming and going as the permission is re-read. The result lands in one step when the action settles.

The popover closes behind whatever it opens. A modal or another page takes over from there, so there is nothing left for the popover to show. Left up, it would sit over the very surface it just opened.

A failure leaves the popover open so the row can be clicked again. Nothing reports what went wrong yet; the error surface is its own change.

mode reaches the connected button. Organizations turned off at the instance leave nothing for an organization surface to lead with or to list, so the button is the account's whatever mode asked for. clerk-js withholds its own <OrganizationSwitcher> at the mount boundary, and nothing mounts this one, so the gate lives in the container.

Custom UserProfile pages

userProfileProps puts your own pages and links into the UserProfile the button opens, and orders that profile's navigation.

<UserButton
  userProfileProps={{
    customPages: [
      { label: 'Terms', path: 'terms', icon: <FileIcon />, content: <Terms /> },
      { label: 'Docs', path: 'docs', href: 'https://clerk.com/docs', icon: <BookIcon /> },
    ],
    pageOrder: ['account', 'terms', 'security', 'docs'],
  }}
/>

Plain objects rather than the <UserButton.UserProfilePage> children the pre-Mosaic button takes. Every entry has a path, which is what identifies it: with content it is a page inside the profile, with href it is a link out of it. icon is optional on both. pageOrder entries are ids: account, security, billing or apiKeys for a built-in page, or a custom entry's path.

Objects also drop the 'use client' requirement the children API carries. UserButton.UserProfilePage means dotting into a client module, which RSC forbids ("Cannot access UserProfilePage on the server"), so describing config forced the directive onto the consumer's file and pulled the page into the client bundle. A prop has nothing to dot into: this renders from a server component, and content can stay a server component too.

The profile still opens in clerk-js's own React root, which cannot render a node from the host app's tree, so useCustomPages bridges the two: each entry goes out as the mount/unmount pair clerk-js already takes, and the host tree portals the content into the element it hands back. The portals hang off the container rather than the popover, since they have to outlive whatever opened the profile. When a Mosaic UserProfile lands in-tree, the bridge goes and the props stay.

None of this is public surface. The experimental entry exports UserButton and UserButtonProps and nothing else, so the hooks and the page types stay internal.

Two things worth a look in review:

The icon callbacks go out whether or not there is an icon. clerk-js decides what an item is from which callbacks are present and drops one missing an icon pair as invalid, so without them, leaving icon off would silently cost you the page.
clerk-js puts every built-in page it was not asked to move ahead of everything it was, so pageOrder has to send the built-ins that were left out too, appended after the ones that were named. That means knowing which built-ins the instance actually shows, which is what useUserProfilePages computes, behind the same shared guards clerk-js uses. It cannot see shouldShowBilling (paid plans / past subscriptions, fetched inside the profile), so an instance with billing enabled but no visible plans gets one dev-only log and the page is dropped, which is what should happen to it anyway.

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

vercel · 2026-07-17T16:00:36Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 7, 2026 8:33pm
swingset	Ready	Preview	Aug 7, 2026 8:33pm

changeset-bot · 2026-07-17T16:00:39Z

🦋 Changeset detected

Latest commit: fb1eb38

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

coderabbitai · 2026-07-17T16:00:44Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 2a7f3fe3-0f9b-4531-87b3-6dfbb33b079e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

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

macroscopeapp · 2026-07-17T16:01:05Z

Approvability

Verdict: Approved

This PR adds integration tests for the AccountButton component with no production code changes. The empty changeset confirms no packages are affected, making this a low-risk test-only addition.

^{You can customize Macroscope's approvability policy. Learn more.}

Dismissing prior approval to re-evaluate 088fc5a

pkg-pr-new · 2026-08-05T16:10:07Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: fb1eb38

github-actions · 2026-08-05T16:13:56Z

API Changes Report

Generated by Break Check on 2026-08-07T20:36:12.752Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

_{Last ran on fb1eb38.}

Render the connected UserButton against stubbed Clerk hooks and drive it through the popover: organization selection, account switching, sign out, accepting invitations and suggestions, single-session mode, navigation actions, busy and loading states, and the paging sentinel.

Every other action — switching account, signing out of one, joining a suggested or invited workspace — now resolves back into an open popover so the result is visible where it happened. The swingset prototypes fake the round trip they make against Clerk, so the spinner and stood-down rows are demonstrable without a running app.

The sizes track the Icon scale (sm 14px, md 16px) so a spinner can stand in for the icon it replaces, and the UserButton's trailing column is now one slot the width of the menu button, so the spinner, the active check, and the menu all sit on the same centre line.

The trigger carried the avatar alone. It now names what is active beside it — the organization and its plan wherever one heads the trigger, the account otherwise — behind `showLabel`, which defaults on. Badge's `neutral` color was unreadable in both schemes: its fill is a 900 and its text token is a text color, not an on-fill one. It now rides the same black/white scrim the button's neutral fill does.

…ccount The trigger and the popup's header now always name the same workspace. `combined` carries both switchers, so `modePriority` picks which one it leads with: the active organization by default, the account with `modePriority="user"`. Both are still listed either way.

…onnected test

…ser fixture The controller now reads hasOrganizations off the user resource, so the mocked user needs the field the real one has.

`setActive` swaps the active organization while its promise is still in flight, so the popup rearranged mid-action: the header renamed itself, the check jumped rows, and Invite came and went as the permission was re-read. The connected component now snapshots the controller when an action starts and renders that until it settles, so the result lands in one step. Two smaller faults fell out of the same interaction: - The spinner waited out a delay window before appearing, and the check raced ahead of it. Every action here is a network round trip, so there is nothing to debounce: `useSpinDelay` takes `delay: 0` and shows the value in the same pass, with `minDuration` still steadying it. - A row going busy swapped its host element from `<button>` to `<div>`, remounting the subtree and dropping the avatar back to its initials for the length of the action. A row that stands down now stays the button it was, disabled, and `Avatar.Image` resolves a browser-cached `src` in a layout effect so neither a remount nor a swap flashes the fallback.

The popover stayed up behind the surface it opened. Managing, inviting, creating an organization, and adding an account now close it on the way out, whether they open a modal or navigate.

The connected test drives the real controller against a mocked Clerk, which is what makes it worth having and also what makes it slow. Cases that only ever asserted what the popover renders now sit in the view test, leaving the connected one to prove the layers compose. Also covers `hidePersonal` reaching the popover through the container.

UserButtonProps picked only modePriority off the root, so the connected component was hard-wired to the combined surface and the orgs/user modes were reachable only by composing UserButtonView directly.

Presses a custom row on the connected UserButton and checks the app's callback runs and the popover closes behind it.

An instance with organizations turned off has none to lead with or list, so the button is the account's whatever `mode` asked for — `orgs` would otherwise render an empty shell of a switcher. clerk-js withholds its own OrganizationSwitcher at the mount boundary, which an app importing this one never crosses, so the gate lives in the component.

The popover's open state and the one action in flight are the same flow, so they now live in one machine instead of two useStates. Re-entry, clearing busy, and closing on success stop being hand-written in the container: RUN is simply unhandled while busy, and busy is only reachable from open. Dismissing the popover mid-action now abandons the result rather than letting it land in a surface that is already gone.

Follows the view's rename of `'orgs'` to `'organization'`. Also corrects the integration suite's opening comment, which attributed close-on-success to the container and had the navigation case backwards.

Carries the app's own pages and links into the profile the UserButton opens, through useCustomPages and the built-in page list it orders them against.

github-actions Bot added the ui label Jul 17, 2026

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

macroscopeapp Bot previously approved these changes Jul 17, 2026

View reviewed changes

vercel Bot deployed to Preview – swingset July 17, 2026 16:02 View deployment

macroscopeapp Bot approved these changes Jul 17, 2026

View reviewed changes

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

vercel Bot deployed to Preview – swingset July 17, 2026 16:08 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox July 20, 2026 18:12 View deployment

vercel Bot deployed to Preview – swingset July 20, 2026 18:14 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox July 20, 2026 18:53 View deployment

vercel Bot deployed to Preview – swingset July 20, 2026 18:55 View deployment

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

vercel Bot deployed to Preview – swingset July 20, 2026 19:18 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox July 20, 2026 20:02 View deployment

vercel Bot deployed to Preview – swingset July 20, 2026 20:04 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox July 20, 2026 20:38 View deployment

vercel Bot had a problem deploying to Preview – swingset July 20, 2026 20:39 Failure

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

vercel Bot had a problem deploying to Preview – swingset July 20, 2026 21:17 Failure

vercel Bot temporarily deployed to Preview – clerk-js-sandbox July 20, 2026 21:20 Inactive

vercel Bot deployed to Preview – swingset July 20, 2026 21:23 View deployment

alexcarpenter force-pushed the carp/account-button-integration branch from 22e6748 to 4f890d8 Compare July 30, 2026 18:38

alexcarpenter changed the title ~~test(ui): add AccountButton connected integration test~~ test(ui): add UserButton connected integration test Jul 30, 2026

vercel Bot deployed to Preview – clerk-js-sandbox July 30, 2026 18:39 View deployment

vercel Bot deployed to Preview – swingset August 4, 2026 00:34 View deployment

alexcarpenter mentioned this pull request Aug 5, 2026

feat(nextjs): export Mosaic UserButton from an experimental subpath #9338

Open

9 tasks

alexcarpenter added 26 commits August 7, 2026 16:29

test(ui): query the account menu trigger as a button

638fed7

test(ui): follow the UserButton active-organization contract in the c…

c550253

…onnected test

test(ui): carry organizationMemberships on the connected UserButton u…

4b51890

…ser fixture The controller now reads hasOrganizations off the user resource, so the mocked user needs the field the real one has.

test(ui): cover the UserButton profile modals end to end

bbc6f47

feat(ui): close the UserButton popover behind whatever it opens

84c867c

The popover stayed up behind the surface it opened. Managing, inviting, creating an organization, and adding an account now close it on the way out, whether they open a modal or navigate.

test(ui): cover the UserButton personal workspace row end to end

541a577

test(ui): cover the named UserButton personal row end to end

09a9ef0

feat(ui): forward mode to the connected UserButton

898aa75

UserButtonProps picked only modePriority off the root, so the connected component was hard-wired to the combined surface and the orgs/user modes were reachable only by composing UserButtonView directly.

test(ui): cover the UserButton create-organization modal end to end

a789b74

test(ui): assert Invite opens the InviteMembers modal

b172109

test(ui): identify Alice's account row by her username

b99e8d7

test(ui): follow the join button's in-place spinner

7702921

test(ui): cover a custom menu item end to end

c1fe582

Presses a custom row on the connected UserButton and checks the app's callback runs and the popover closes behind it.

refactor(ui): drop comments the integration assertions already carry

cc5c149

refactor(ui): name the organization mode in full on the connected button

9effd1d

Follows the view's rename of `'orgs'` to `'organization'`. Also corrects the integration suite's opening comment, which attributed close-on-success to the container and had the navigation case backwards.

feat(ui): add custom UserProfile pages to the Mosaic UserButton

7372e46

Carries the app's own pages and links into the profile the UserButton opens, through useCustomPages and the built-in page list it orders them against.

chore(repo): consolidate the branch's changesets into one

fb1eb38

Navigation Menu

Uh oh!

feat(ui): connect the Mosaic UserButton and its custom UserProfile pages - #9191

feat(ui): connect the Mosaic UserButton and its custom UserProfile pages#9191
alexcarpenter wants to merge 26 commits into
carp/account-button-controllerfrom
carp/account-button-integration

alexcarpenter commented Jul 17, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 17, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jul 17, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 17, 2026

Review skipped

Uh oh!

macroscopeapp Bot commented Jul 17, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 5, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

alexcarpenter commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Custom UserProfile pages

Checklist

Type of change

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Jul 17, 2026

Review skipped

Uh oh!

macroscopeapp Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approvability

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

No API Changes Detected

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

alexcarpenter commented Jul 17, 2026 •

edited

Loading

vercel Bot commented Jul 17, 2026 •

edited

Loading

changeset-bot Bot commented Jul 17, 2026 •

edited

Loading

macroscopeapp Bot commented Jul 17, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 5, 2026 •

edited

Loading

github-actions Bot commented Aug 5, 2026 •

edited

Loading