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

[alexcarpenter]

Description

Adds userProfileProps to the experimental Mosaic UserButton, for putting your own pages and links into the UserProfile it opens, and for ordering 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.

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 1437c76

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 5, 2026 11:29pm
swingset	Ready	Preview	Aug 5, 2026 11:29pm