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

Merged
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages
Aug 6, 2026
Merged

feat(ui): add custom UserProfile pages to the Mosaic UserButton#9343
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages

Conversation

@alexcarpenter

@alexcarpenteralexcarpenter commented Aug 5, 2026

Copy link
Copy Markdown
Member

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.

<UserButtonuserProfileProps={{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-botBot commented Aug 5, 2026

Copy link
Copy Markdown

🦋 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

vercelBot commented Aug 5, 2026

Copy link
Copy Markdown

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

ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreviewAug 5, 2026 11:29pm
swingsetReadyReadyPreviewAug 5, 2026 11:29pm

Request Review

Ordering keyed on href for links; path is now required on every entry and is the pageOrder key.
@alexcarpenter
alexcarpenter merged commit 8eb59e5 into carp/account-button-experimental-exportAug 6, 2026
13 checks passed
@alexcarpenter
alexcarpenter deleted the carp/mosaic-user-button-custom-pages branch August 6, 2026 13:28
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@alexcarpenter
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Skip to content

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

Merged
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages
Aug 6, 2026
Merged

feat(ui): add custom UserProfile pages to the Mosaic UserButton#9343
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages

Conversation

@alexcarpenter

@alexcarpenteralexcarpenter commented Aug 5, 2026

Copy link
Copy Markdown
Member

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.

<UserButtonuserProfileProps={{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-botBot commented Aug 5, 2026

Copy link
Copy Markdown

🦋 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

vercelBot commented Aug 5, 2026

Copy link
Copy Markdown

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

ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreviewAug 5, 2026 11:29pm
swingsetReadyReadyPreviewAug 5, 2026 11:29pm

Request Review

Ordering keyed on href for links; path is now required on every entry and is the pageOrder key.
@alexcarpenter
alexcarpenter merged commit 8eb59e5 into carp/account-button-experimental-exportAug 6, 2026
13 checks passed
@alexcarpenter
alexcarpenter deleted the carp/mosaic-user-button-custom-pages branch August 6, 2026 13:28
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@alexcarpenter
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix"); } } catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

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

Merged
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages
Aug 6, 2026
Merged

feat(ui): add custom UserProfile pages to the Mosaic UserButton#9343
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages

Conversation

@alexcarpenter

@alexcarpenteralexcarpenter commented Aug 5, 2026

Copy link
Copy Markdown
Member

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.

<UserButtonuserProfileProps={{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-botBot commented Aug 5, 2026

Copy link
Copy Markdown

🦋 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

vercelBot commented Aug 5, 2026

Copy link
Copy Markdown

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

ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreviewAug 5, 2026 11:29pm
swingsetReadyReadyPreviewAug 5, 2026 11:29pm

Request Review

Ordering keyed on href for links; path is now required on every entry and is the pageOrder key.
@alexcarpenter
alexcarpenter merged commit 8eb59e5 into carp/account-button-experimental-exportAug 6, 2026
13 checks passed
@alexcarpenter
alexcarpenter deleted the carp/mosaic-user-button-custom-pages branch August 6, 2026 13:28
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@alexcarpenter
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms"); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

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

Merged
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages
Aug 6, 2026
Merged

feat(ui): add custom UserProfile pages to the Mosaic UserButton#9343
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages

Conversation

@alexcarpenter

@alexcarpenteralexcarpenter commented Aug 5, 2026

Copy link
Copy Markdown
Member

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.

<UserButtonuserProfileProps={{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-botBot commented Aug 5, 2026

Copy link
Copy Markdown

🦋 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

vercelBot commented Aug 5, 2026

Copy link
Copy Markdown

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

ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreviewAug 5, 2026 11:29pm
swingsetReadyReadyPreviewAug 5, 2026 11:29pm

Request Review

Ordering keyed on href for links; path is now required on every entry and is the pageOrder key.
@alexcarpenter
alexcarpenter merged commit 8eb59e5 into carp/account-button-experimental-exportAug 6, 2026
13 checks passed
@alexcarpenter
alexcarpenter deleted the carp/mosaic-user-button-custom-pages branch August 6, 2026 13:28
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@alexcarpenter
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links"); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + '
Skip to content

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

Merged
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages
Aug 6, 2026
Merged

feat(ui): add custom UserProfile pages to the Mosaic UserButton#9343
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages

Conversation

@alexcarpenter

@alexcarpenteralexcarpenter commented Aug 5, 2026

Copy link
Copy Markdown
Member

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.

<UserButtonuserProfileProps={{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-botBot commented Aug 5, 2026

Copy link
Copy Markdown

🦋 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

vercelBot commented Aug 5, 2026

Copy link
Copy Markdown

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

ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreviewAug 5, 2026 11:29pm
swingsetReadyReadyPreviewAug 5, 2026 11:29pm

Request Review

Ordering keyed on href for links; path is now required on every entry and is the pageOrder key.
@alexcarpenter
alexcarpenter merged commit 8eb59e5 into carp/account-button-experimental-exportAug 6, 2026
13 checks passed
@alexcarpenter
alexcarpenter deleted the carp/mosaic-user-button-custom-pages branch August 6, 2026 13:28
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@alexcarpenter
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default"); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

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

Merged
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages
Aug 6, 2026
Merged

feat(ui): add custom UserProfile pages to the Mosaic UserButton#9343
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages

Conversation

@alexcarpenter

@alexcarpenteralexcarpenter commented Aug 5, 2026

Copy link
Copy Markdown
Member

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.

<UserButtonuserProfileProps={{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-botBot commented Aug 5, 2026

Copy link
Copy Markdown

🦋 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

vercelBot commented Aug 5, 2026

Copy link
Copy Markdown

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

ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreviewAug 5, 2026 11:29pm
swingsetReadyReadyPreviewAug 5, 2026 11:29pm

Request Review

Ordering keyed on href for links; path is now required on every entry and is the pageOrder key.
@alexcarpenter
alexcarpenter merged commit 8eb59e5 into carp/account-button-experimental-exportAug 6, 2026
13 checks passed
@alexcarpenter
alexcarpenter deleted the carp/mosaic-user-button-custom-pages branch August 6, 2026 13:28
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@alexcarpenter
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers"); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

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

Merged
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages
Aug 6, 2026
Merged

feat(ui): add custom UserProfile pages to the Mosaic UserButton#9343
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages

Conversation

@alexcarpenter

@alexcarpenteralexcarpenter commented Aug 5, 2026

Copy link
Copy Markdown
Member

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.

<UserButtonuserProfileProps={{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-botBot commented Aug 5, 2026

Copy link
Copy Markdown

🦋 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

vercelBot commented Aug 5, 2026

Copy link
Copy Markdown

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

ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreviewAug 5, 2026 11:29pm
swingsetReadyReadyPreviewAug 5, 2026 11:29pm

Request Review

Ordering keyed on href for links; path is now required on every entry and is the pageOrder key.
@alexcarpenter
alexcarpenter merged commit 8eb59e5 into carp/account-button-experimental-exportAug 6, 2026
13 checks passed
@alexcarpenter
alexcarpenter deleted the carp/mosaic-user-button-custom-pages branch August 6, 2026 13:28
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@alexcarpenter
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode"); } } catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); } })(); })();
Skip to content

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

Merged
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages
Aug 6, 2026
Merged

feat(ui): add custom UserProfile pages to the Mosaic UserButton#9343
alexcarpenter merged 2 commits into
carp/account-button-experimental-exportfrom
carp/mosaic-user-button-custom-pages

Conversation

@alexcarpenter

@alexcarpenteralexcarpenter commented Aug 5, 2026

Copy link
Copy Markdown
Member

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.

<UserButtonuserProfileProps={{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-botBot commented Aug 5, 2026

Copy link
Copy Markdown

🦋 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

vercelBot commented Aug 5, 2026

Copy link
Copy Markdown

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

ProjectDeploymentActionsUpdated (UTC)
clerk-js-sandboxReadyReadyPreviewAug 5, 2026 11:29pm
swingsetReadyReadyPreviewAug 5, 2026 11:29pm

Request Review

Ordering keyed on href for links; path is now required on every entry and is the pageOrder key.
@alexcarpenter
alexcarpenter merged commit 8eb59e5 into carp/account-button-experimental-exportAug 6, 2026
13 checks passed
@alexcarpenter
alexcarpenter deleted the carp/mosaic-user-button-custom-pages branch August 6, 2026 13:28
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@alexcarpenter