feat(clerk-js): Introduce `UNSAFE_PortalProvider`

[alexcarpenter]

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 interactable.

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: https://github.com/clerk/clerk-docs/pull/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

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

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: fa6ef65a8fc66229d1b42e9dcfd3a10c9a86a890

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

This PR includes changesets to release 19 packages

Name	Type
@clerk/shared	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	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[bot]]

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

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Skipped		Dec 17, 2025 2:15pm

[coderabbitai[bot]]

[!IMPORTANT]

Review skipped

Draft detected.

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.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch alexcarpenter/portal-provider-3

---

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

[alexcarpenter]

!snapshot

[clerk-cookie]

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]

!snapshot

[clerk-cookie]

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]

!snapshot

[clerk-cookie]

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

[alexcarpenter]

!snapshot

[clerk-cookie]

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

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

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/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

[alexcarpenter]

!snapshot

[clerk-cookie]

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

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

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/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

[alexcarpenter]

!snapshot

[clerk-cookie]

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

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

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/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