feat(clerk-js): Introduce `UNSAFE_PortalProvider` #7310

alexcarpenter · 2025-11-25T16:48:38Z

Description

The <UNSAFE_PortalProvider> component allows you to specify a custom container for Clerk floating UI elements (popovers, modals, tooltips, etc.) that use portals. Only Clerk components within the provider will be affected, components outside the provider will continue to use the default document.body for portals.

This is particularly useful when using Clerk components inside external UI libraries like Radix Dialog or React Aria Components, where portaled elements need to render within the dialog's container to remain interact-able.

Example usage

'use client'

import { useRef } from 'react'
import * as Dialog from '@radix-ui/react-dialog'
import { UNSAFE_PortalProvider, UserButton } from '@clerk/nextjs'

export function UserDialog() {
  const containerRef = useRef<HTMLDivElement>(null)

  return (
    <Dialog.Root>
      <Dialog.Trigger>Open Dialog</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content ref={containerRef}>
          <UNSAFE_PortalProvider getContainer={() => containerRef.current}>
            <UserButton />
          </UNSAFE_PortalProvider>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  )
}

Docs: clerk/clerk-docs#2896

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

Summary by CodeRabbit

New Features
- Introduced UNSAFE_PortalProvider and usePortalRoot across frameworks; components can accept a getContainer to target custom portal containers.
UI
- Modals, popovers, tooltips, drawers, menus and lazy modal rendering now resolve and honor the specified portal container for consistent rendering.
Style
- Prevented menu item text wrapping for improved layout.
Tests
- Added extensive tests for portal provider/composable behavior and modal/portal rendering.
Chores
- Updated bundle size thresholds.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

changeset-bot · 2025-11-25T16:48:42Z

🦋 Changeset detected

Latest commit: aee4553

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@clerk/tanstack-react-start	Minor
@clerk/react-router	Minor
@clerk/nextjs	Minor
@clerk/shared	Minor
@clerk/astro	Minor
@clerk/react	Minor
@clerk/expo	Minor
@clerk/nuxt	Minor
@clerk/vue	Minor
@clerk/ui	Minor
@clerk/agent-toolkit	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/testing	Patch

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 · 2025-11-25T16:48:43Z

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

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 20, 2026 4:38pm

coderabbitai · 2025-11-25T16:48:44Z

📝 Walkthrough

Walkthrough

Introduces a portal provider system: adds UNSAFE_PortalProvider and usePortalRoot in shared React and Vue layers, plus a Vue PortalInjectionKey and composable. Components that render portals (modals, popovers, tooltips, drawers, lazy renderers, host renderers, organization/user flows) now obtain or accept a getContainer function. Multiple packages re-export the provider/hook, several modal prop types gained an optional getContainer, tests for React and Vue portal behavior were added, and UI components were updated to use the provider. Bundlewatch thresholds were adjusted.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main feature being introduced: a new component called UNSAFE_PortalProvider that allows custom portal containers for Clerk UI elements.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

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

alexcarpenter · 2025-11-25T16:50:24Z

!snapshot

clerk-cookie · 2025-11-25T16:52:37Z

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

Package	Version

Tip: Use the snippet copy button below to quickly install the required packages.

alexcarpenter · 2025-11-25T17:05:08Z

!snapshot

clerk-cookie · 2025-11-25T17:05:54Z

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

Package	Version

Tip: Use the snippet copy button below to quickly install the required packages.

.changeset/wet-phones-camp.md

alexcarpenter · 2025-11-25T17:59:48Z

!snapshot

clerk-cookie · 2025-11-25T18:02:22Z

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

Package	Version
@clerk/agent-toolkit	0.2.6-snapshot.v20251125180024
@clerk/astro	2.16.4-snapshot.v20251125180024
@clerk/backend	2.24.1-snapshot.v20251125180024
@clerk/chrome-extension	2.8.7-snapshot.v20251125180024
@clerk/clerk-js	5.111.1-snapshot.v20251125180024
@clerk/elements	0.23.87-snapshot.v20251125180024
@clerk/clerk-expo	2.19.7-snapshot.v20251125180024
@clerk/expo-passkeys	0.4.23-snapshot.v20251125180024
@clerk/express	1.7.54-snapshot.v20251125180024
@clerk/fastify	2.6.6-snapshot.v20251125180024
@clerk/localizations	3.28.6-snapshot.v20251125180024
@clerk/nextjs	6.35.6-snapshot.v20251125180024
@clerk/nuxt	1.13.4-snapshot.v20251125180024
@clerk/clerk-react	5.57.1-snapshot.v20251125180024
@clerk/react-router	2.3.1-snapshot.v20251125180024
@clerk/remix	4.13.21-snapshot.v20251125180024
@clerk/shared	3.36.1-snapshot.v20251125180024
@clerk/tanstack-react-start	0.27.6-snapshot.v20251125180024
@clerk/testing	1.13.20-snapshot.v20251125180024
@clerk/themes	2.4.41-snapshot.v20251125180024
@clerk/types	4.101.4-snapshot.v20251125180024
@clerk/vue	1.17.1-snapshot.v20251125180024

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

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/elements

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/clerk-react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/themes

npm i @clerk/[email protected] --save-exact

@clerk/types

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

…vascript into alexcarpenter/portal-provider-3

clerk-cookie · 2026-01-09T19:49:36Z

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

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260109194807
@clerk/astro	3.0.0-snapshot.v20260109194807
@clerk/backend	3.0.0-snapshot.v20260109194807
@clerk/chrome-extension	3.0.0-snapshot.v20260109194807
@clerk/clerk-js	6.0.0-snapshot.v20260109194807
@clerk/dev-cli	1.0.0-snapshot.v20260109194807
@clerk/expo	3.0.0-snapshot.v20260109194807
@clerk/expo-passkeys	1.0.0-snapshot.v20260109194807
@clerk/express	2.0.0-snapshot.v20260109194807
@clerk/fastify	2.6.9-snapshot.v20260109194807
@clerk/localizations	4.0.0-snapshot.v20260109194807
@clerk/msw	0.0.1-snapshot.v20260109194807
@clerk/nextjs	7.0.0-snapshot.v20260109194807
@clerk/nuxt	2.0.0-snapshot.v20260109194807
@clerk/react	6.0.0-snapshot.v20260109194807
@clerk/react-router	3.0.0-snapshot.v20260109194807
@clerk/shared	4.0.0-snapshot.v20260109194807
@clerk/tanstack-react-start	1.0.0-snapshot.v20260109194807
@clerk/testing	2.0.0-snapshot.v20260109194807
@clerk/ui	1.0.0-snapshot.v20260109194807
@clerk/upgrade	2.0.0-snapshot.v20260109194807
@clerk/vue	2.0.0-snapshot.v20260109194807

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

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

wobsoriano

Looks good! Test it locally with the React and Vue SDKs:

React using shadcn + Dialog component

React_Unsafe_PortalProvider.mov

Vue using shadcn-vue + Dialog component

Vue_Unsafe_PortalProvider.mov

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In
`@packages/ui/src/components/OrganizationSwitcher/__tests__/OrganizationSwitcher.test.tsx`:
- Around line 641-661: The test fails because the user fixture lacks
create_organization_enabled, so update the setup in the createFixtures callback
(the call to f.withUser) to include create_organization_enabled: true (e.g.,
f.withUser({ email_addresses: ['[email protected]'], create_organization_enabled:
true })) so the "Create organization" menu item is rendered; keep the rest of
the test that wraps OrganizationSwitcher with UNSAFE_PortalProvider
(getContainer) and asserts fixtures.clerk.openCreateOrganization was called with
expect.objectContaining({ getContainer }).
- Around line 619-639: The test fails because no organization_memberships are
set up, so the "Manage Organization" menu item never appears; update the fixture
setup inside the createFixtures callback (the function passed to createFixtures
and its fixture builder f) to include an organization membership for the user by
calling the fixture method that creates memberships (e.g.,
f.withOrganizationMemberships(...) or the project’s equivalent) after
f.withOrganizations() so the user is a member of the created organization and
the OrganizationSwitcher test can find and click "Manage Organization".

packages/ui/src/components/OrganizationSwitcher/__tests__/OrganizationSwitcher.test.tsx

init

71ff27a

clerk-cookie added clerk-js nextjs react labels Nov 25, 2025

vercel bot deployed to Preview November 25, 2025 16:50 View deployment

Create wet-phones-camp.md

922010b

vercel bot deployed to Preview November 25, 2025 16:59 View deployment

alexcarpenter commented Nov 25, 2025

View reviewed changes

.changeset/wet-phones-camp.md Show resolved Hide resolved

Apply suggestion from @alexcarpenter

3d5f3bd

vercel bot deployed to Preview November 25, 2025 17:59 View deployment

alexcarpenter added 2 commits November 25, 2025 13:40

wip

e9b66d5

Merge branch 'alexcarpenter/portal-provider-3' of github.com:clerk/ja…

af3e86b

…vascript into alexcarpenter/portal-provider-3

vercel bot deployed to Preview November 25, 2025 18:41 View deployment

wip

2423766

vercel bot deployed to Preview December 1, 2025 18:03 View deployment

Merge branch 'main' into alexcarpenter/portal-provider-3

66ae887

github-actions bot added the core-3 label Dec 15, 2025

vercel bot deployed to Preview December 15, 2025 19:38 View deployment

expand portalprovider usage

44854e1

github-actions bot added expo tanstack labels Dec 15, 2025

Update exports.test.ts.snap

f3045f7

vercel bot temporarily deployed to Preview January 9, 2026 20:36 Inactive

Update exports.test.ts.snap

f80e145

vercel bot temporarily deployed to Preview January 9, 2026 22:04 Inactive

sort

a3a64e9

vercel bot deployed to Preview January 9, 2026 22:10 View deployment

update expo export

9814d4b

vercel bot deployed to Preview January 16, 2026 20:22 View deployment

Merge branch 'main' into alexcarpenter/portal-provider-3

01126b7

vercel bot deployed to Preview January 16, 2026 23:47 View deployment

wobsoriano approved these changes Jan 17, 2026

View reviewed changes

fix: filter getContainer from props

ddec780

vercel bot deployed to Preview January 20, 2026 14:33 View deployment

add displayName

0477ac0

vercel bot deployed to Preview January 20, 2026 15:22 View deployment

Update bundlewatch.config.json

5363de6

vercel bot deployed to Preview January 20, 2026 15:26 View deployment

fix imports

23d9d1b

vercel bot deployed to Preview January 20, 2026 15:42 View deployment

coderabbitai bot reviewed Jan 20, 2026

View reviewed changes

packages/ui/src/components/OrganizationSwitcher/__tests__/OrganizationSwitcher.test.tsx Show resolved Hide resolved

packages/ui/src/components/OrganizationSwitcher/__tests__/OrganizationSwitcher.test.tsx Show resolved Hide resolved

fix tests

2aac9e8

vercel bot deployed to Preview January 20, 2026 16:21 View deployment

Merge branch 'main' into alexcarpenter/portal-provider-3

5d1407b

vercel bot deployed to Preview January 20, 2026 16:31 View deployment

Merge branch 'main' into alexcarpenter/portal-provider-3

aee4553

vercel bot deployed to Preview January 20, 2026 16:38 View deployment

alexcarpenter merged commit 79e2622 into main Jan 20, 2026
38 checks passed

alexcarpenter deleted the alexcarpenter/portal-provider-3 branch January 20, 2026 16:56

alexcarpenter mentioned this pull request Jan 20, 2026

chore: Add <UNSAFE_PortalProvider> docs clerk/clerk-docs#2985

Open

feat(clerk-js): Introduce UNSAFE_PortalProvider #7310

feat(clerk-js): Introduce UNSAFE_PortalProvider #7310

Conversation

alexcarpenter commented Nov 25, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Example usage

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

alexcarpenter commented Nov 25, 2025

Uh oh!

clerk-cookie commented Nov 25, 2025

Uh oh!

alexcarpenter commented Nov 25, 2025

Uh oh!

clerk-cookie commented Nov 25, 2025

Uh oh!

Uh oh!

alexcarpenter commented Nov 25, 2025

Uh oh!

clerk-cookie commented Nov 25, 2025

Uh oh!

clerk-cookie commented Jan 9, 2026

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

feat(clerk-js): Introduce `UNSAFE_PortalProvider` #7310

feat(clerk-js): Introduce `UNSAFE_PortalProvider` #7310

alexcarpenter commented Nov 25, 2025 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Nov 25, 2025 •

edited

Loading

vercel bot commented Nov 25, 2025 •

edited

Loading

coderabbitai bot commented Nov 25, 2025 •

edited

Loading