feat(ui): Expose profile sub components by alexcarpenter · Pull Request #8654 · clerk/javascript

alexcarpenter · 2026-05-26T20:13:44Z

Summary

Exposes UserProfile and OrganizationProfile as composable sub-components from @clerk/ui/experimental. Lets consumers render individual profile sections (Account, Security, Members, Billing, etc.) outside the full modal/page flow.

Approach

New composed/ directory — each profile gets a Provider that wires up the required context tree (appearance, environment, module manager, routing, flow metadata) so individual section components render standalone.
moduleManagerStore — module-level get/set because composed components mount outside the normal component tree and can't inherit ModuleManager via context from ClerkUI.init().
stubRouter — minimal RouteContext implementation delegating to clerk.navigate. Child components call useRouter() internally but composed pages don't do real routing.
StyleCacheProvider — moved document.querySelector from module scope into the component body; import-time access breaks SSR.
useSafeState — reset isMountedRef to true in effect body; StrictMode cleanup between double-invocation left it permanently false.
Animated — guard against StrictMode double-mount leaving animation refs stale.
Exported via @clerk/ui/experimental with 'use client' directive.

API

import { UserProfile, OrganizationProfile } from '@clerk/ui/experimental';

<UserProfile>
  <UserProfile.Account />
  <UserProfile.Security />
</UserProfile>

<OrganizationProfile>
  <OrganizationProfile.General />
  <OrganizationProfile.Members />
</OrganizationProfile>

Sub-components available: Account, Security, Billing, APIKeys (user); General, Members, Billing, APIKeys, ConfigureSSO (org). Fine-grained wrappers also exported (e.g. AccountProfile, SecurityPasskeys).

Test plan

Composed provider wiring tests verify context parity with full-flow mounts
Section-level render tests for both UserProfile and OrganizationProfile
StrictMode animation + state tests
Stub router limitation tests

🤖 Generated with Claude Code

changeset-bot · 2026-05-26T20:13:49Z

⚠️ No Changeset found

Latest commit: 40e270d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

vercel · 2026-05-26T20:13:50Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 2, 2026 6:33pm

alexcarpenter · 2026-05-26T21:54:42Z

!snapshot

alexcarpenter · 2026-05-27T13:28:18Z

!snapshot

alexcarpenter · 2026-05-27T13:47:21Z

!snapshot

alexcarpenter · 2026-05-27T15:29:02Z

!snapshot

alexcarpenter · 2026-05-27T16:15:09Z

!snapshot

github-actions · 2026-05-27T16:18:05Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/astro	3.3.0-snapshot.v20260527161602
@clerk/backend	3.4.12-snapshot.v20260527161602
@clerk/chrome-extension	3.1.29-snapshot.v20260527161602
@clerk/clerk-js	6.12.0-snapshot.v20260527161602
@clerk/dev-cli	0.1.1-snapshot.v20260527161602
@clerk/expo	3.2.15-snapshot.v20260527161602
@clerk/expo-passkeys	1.0.28-snapshot.v20260527161602
@clerk/express	2.1.20-snapshot.v20260527161602
@clerk/fastify	3.1.30-snapshot.v20260527161602
@clerk/hono	0.1.30-snapshot.v20260527161602
@clerk/localizations	4.6.7-snapshot.v20260527161602
@clerk/msw	0.0.28-snapshot.v20260527161602
@clerk/nextjs	7.4.0-snapshot.v20260527161602
@clerk/nuxt	2.5.0-snapshot.v20260527161602
@clerk/react	6.7.0-snapshot.v20260527161602
@clerk/react-router	3.3.0-snapshot.v20260527161602
@clerk/shared	4.13.0-snapshot.v20260527161602
@clerk/tanstack-react-start	1.3.0-snapshot.v20260527161602
@clerk/testing	2.0.32-snapshot.v20260527161602
@clerk/ui	1.13.0-snapshot.v20260527161602
@clerk/upgrade	2.0.3-snapshot.v20260527161602
@clerk/vue	2.3.0-snapshot.v20260527161602

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/astro

npm i @clerk/astro@3.3.0-snapshot.v20260527161602 --save-exact

@clerk/backend

npm i @clerk/backend@3.4.12-snapshot.v20260527161602 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.1.29-snapshot.v20260527161602 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.12.0-snapshot.v20260527161602 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@0.1.1-snapshot.v20260527161602 --save-exact

@clerk/expo

npm i @clerk/expo@3.2.15-snapshot.v20260527161602 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.28-snapshot.v20260527161602 --save-exact

@clerk/express

npm i @clerk/express@2.1.20-snapshot.v20260527161602 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.1.30-snapshot.v20260527161602 --save-exact

@clerk/hono

npm i @clerk/hono@0.1.30-snapshot.v20260527161602 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.6.7-snapshot.v20260527161602 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.28-snapshot.v20260527161602 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.4.0-snapshot.v20260527161602 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.5.0-snapshot.v20260527161602 --save-exact

@clerk/react

npm i @clerk/react@6.7.0-snapshot.v20260527161602 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.3.0-snapshot.v20260527161602 --save-exact

@clerk/shared

npm i @clerk/shared@4.13.0-snapshot.v20260527161602 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.3.0-snapshot.v20260527161602 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.32-snapshot.v20260527161602 --save-exact

@clerk/ui

npm i @clerk/ui@1.13.0-snapshot.v20260527161602 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.3-snapshot.v20260527161602 --save-exact

@clerk/vue

npm i @clerk/vue@2.3.0-snapshot.v20260527161602 --save-exact

Annotate every exported composed component with a ReactNode return type so the generated .d.ts files are compatible with both React 18 and React 19 consumers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Export UserProfile and OrganizationProfile as function components with static properties (via Object.assign) instead of plain objects. This matches the existing UserButton pattern and is compatible with React Server Components client references, which support property access on function exports but not on plain object exports. The provider is now the root component itself — consumers write <UserProfile> instead of <UserProfile.Provider>. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The spy returned undefined in jsdom, causing autoAnimate's MutationObserver callback to crash on .addEventListener. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jacekradko · 2026-06-01T16:19:59Z

I like this from a directional standpoint and I agree that exposing subcomponents makes sense for flexibility and customization. At a quick glance, though, this seems to duplicate/add another Profile component stack that then needs extra context plumbed into it to work. That expands our public/internal contract and likely increases the chance of drift and defects over time. Could we instead look at extracting the shared parts from the current Profile components so the existing implementation and the new subcomponent API compose the same internals differently? What do you think? Happy to collab on this if you want or drop a high level proposal for internals

alexcarpenter · 2026-06-01T17:56:22Z

@jacekradko here is an update with shared parts targeting this branch #8714

Ephem

I need to think more on the clerk-js/ui boundary, but I thought I'd leave some random thoughts.

Ephem · 2026-06-02T14:27:36Z

+} from './sectionWrappers';
+import { ConfigureSSO } from './ConfigureSSO';
+
+export const OrganizationProfile = Object.assign(OrganizationProfileProvider, {


Same comment as here: #8474 (comment)

These are meant to be publicly exported, so do we optimize for treeshaking early even though that's annoying for compound components?

Ephem · 2026-06-02T15:20:49Z

+
+export const APIKeys = (): ReactNode => (
+  <CardStateProvider>
+    <Suspense fallback={''}>


The <Suspense> fallbacks are interesting. 🤔 I think designing the loading and error experience should be front and center here.

At what levels do we handle it? (Page, section, component?) How do we make it good out of the box, while also allowing devs to tweak fallbacks?

This is tricky since we really only use Suspense for the initialState now, so maybe the thinking and right move is to just do '' for now? Maybe we don't allow for tweaking loading states besides CSS in the first iteration?

It would be interesting to figure out the best possible long term DX here even if we don't implement it right away. I think that's Suspense+Error boundaries for everything, so the user can control it.

Just thinking out loud, but maybe that's also composable? Also maybe they want a top level loading state for their entire page/section of the page where Clerk is a small part, and that loading state lives far away from the Clerk code? They don't want the rest of the page to reveal first, show Clerk loading state, reveal Clerk, they want to wait for everything to load before revealing, including Clerk? Especially now that they can compose together their UI.

This of course means we can't render the components in their own React application, it needs to compose together with the host app, but I don't think this PR is doing the standalone render right?

Ephem · 2026-06-02T15:53:57Z

+
+type UserProfileProviderProps = React.PropsWithChildren<{
+  appearance?: Appearance;
+  additionalOAuthScopes?: Partial<Record<OAuthProvider, OAuthScope[]>>;


If these components keep rendering inside the host app, as opposed to as a separate React app, maybe SSR becomes as "easy" as passing in an initialState prop here, which we put on a context the hooks read from further down? 🤔

Possibility! I think @jacekradko is looking at bringing these back under the same runtime here #8718

I was looking at that, and if I understood it correctly, the components were still rendering as part of the host app, and not as a separate app?

github-actions Bot added the ui label May 26, 2026

vercel Bot deployed to Preview May 26, 2026 20:14 View deployment

This comment has been minimized.

Sign in to view

vercel Bot deployed to Preview May 27, 2026 13:24 View deployment

This comment has been minimized.

Sign in to view

vercel Bot deployed to Preview May 27, 2026 13:38 View deployment

vercel Bot deployed to Preview May 27, 2026 13:45 View deployment

This comment has been minimized.

Sign in to view

vercel Bot deployed to Preview May 27, 2026 15:21 View deployment

This comment has been minimized.

Sign in to view

vercel Bot deployed to Preview May 27, 2026 15:47 View deployment

alexcarpenter force-pushed the carp/profile-section-components branch from e47d56e to 4c41b6b Compare May 28, 2026 13:49

vercel Bot had a problem deploying to Preview May 28, 2026 13:50 Failure

github-actions Bot added clerk-js nextjs react actions backend fastify localizations expo chrome-extension labels May 28, 2026

alexcarpenter and others added 12 commits May 29, 2026 12:55

fix: add explicit ReactNode return types to all composed exports

56799af

Annotate every exported composed component with a ReactNode return type so the generated .d.ts files are compatible with both React 18 and React 19 consumers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix Animated in react strict mode usage

2708119

fix: globalAppearance usage

29b67d8

feat(ui): add OrganizationProfile.ConfigureSSO composed export

0593362

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

add AppearanceOverrides

c91f7ac

use AppearanceOverrides

f9d608e

remove playground app

08f26f4

cleanup

716d04e

Update pnpm-workspace.yaml

9188aca

Update pnpm-lock.yaml

1e0df16

fix(ui): skip Web3 composed test that requires real moduleManager

3a89eb3

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

alexcarpenter force-pushed the carp/profile-section-components branch from c6528a9 to 3a89eb3 Compare May 29, 2026 17:02

vercel Bot deployed to Preview May 29, 2026 17:03 View deployment

fix(ui): guard autoAnimate init against missing element.animate (jsdom)

a1310a1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 29, 2026 17:22 View deployment

fix(ui): mock Element.animate return value in auto-animate tests

44dac2e

The spy returned undefined in jsdom, causing autoAnimate's MutationObserver callback to crash on .addEventListener. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 29, 2026 17:33 View deployment

expose moduleManager via clerk

d961ccf

vercel Bot deployed to Preview May 29, 2026 22:51 View deployment

Update isomorphicClerk.ts

e137e73

vercel Bot deployed to Preview June 1, 2026 17:23 View deployment

Update clerk.ts

a9db995

vercel Bot deployed to Preview June 1, 2026 17:44 View deployment

Ephem mentioned this pull request Jun 2, 2026

feat(headless): add package foundation with Dialog primitive #8474

Open

3 tasks

Ephem reviewed Jun 2, 2026

View reviewed changes

tackle feedback

40e270d

vercel Bot deployed to Preview June 2, 2026 18:33 View deployment

Conversation

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

Uh oh!

Summary

Approach

API

Test plan

Uh oh!

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

Uh oh!

⚠️ No Changeset found

Uh oh!

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

Uh oh!

Uh oh!

alexcarpenter commented May 26, 2026

Uh oh!

This comment has been minimized.

alexcarpenter commented May 27, 2026

Uh oh!

This comment has been minimized.

alexcarpenter commented May 27, 2026

Uh oh!

This comment has been minimized.

alexcarpenter commented May 27, 2026

Uh oh!

This comment has been minimized.

alexcarpenter commented May 27, 2026

Uh oh!

github-actions Bot commented May 27, 2026

Uh oh!

jacekradko commented Jun 1, 2026

Uh oh!

alexcarpenter commented Jun 1, 2026

Uh oh!

Ephem left a comment

Choose a reason for hiding this comment

Uh oh!

Ephem Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Ephem Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Ephem Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

alexcarpenter Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Ephem Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexcarpenter commented May 26, 2026 •

edited

Loading

changeset-bot Bot commented May 26, 2026 •

edited

Loading

vercel Bot commented May 26, 2026 •

edited

Loading