Skip to content

Conversation

@alexcarpenter
Copy link
Member

@alexcarpenter alexcarpenter commented Nov 25, 2025

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

  • 🐛 Bug fix
  • 🌟 New feature
  • 🔨 Breaking change
  • 📖 Refactoring / dependency upgrade / documentation
  • other:
@changeset-bot
Copy link

changeset-bot bot commented Nov 25, 2025

🦋 Changeset detected

Latest commit: fa6ef65

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
Copy link

vercel bot commented Nov 25, 2025

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

1 Skipped Deployment
Project Deployment Review Updated (UTC)
clerk-js-sandbox Skipped Skipped Dec 17, 2025 2:15pm
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Nov 25, 2025

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
Copy link
Member Author

!snapshot

@clerk-cookie
Copy link
Collaborator

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
Copy link
Member Author

!snapshot

@clerk-cookie
Copy link
Collaborator

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
Copy link
Member Author

!snapshot

@clerk-cookie
Copy link
Collaborator

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/agent-toolkit@0.2.6-snapshot.v20251125180024 --save-exact

@clerk/astro

npm i @clerk/astro@2.16.4-snapshot.v20251125180024 --save-exact

@clerk/backend

npm i @clerk/backend@2.24.1-snapshot.v20251125180024 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@2.8.7-snapshot.v20251125180024 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.111.1-snapshot.v20251125180024 --save-exact

@clerk/elements

npm i @clerk/elements@0.23.87-snapshot.v20251125180024 --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@2.19.7-snapshot.v20251125180024 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@0.4.23-snapshot.v20251125180024 --save-exact

@clerk/express

npm i @clerk/express@1.7.54-snapshot.v20251125180024 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.6.6-snapshot.v20251125180024 --save-exact

@clerk/localizations

npm i @clerk/localizations@3.28.6-snapshot.v20251125180024 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@6.35.6-snapshot.v20251125180024 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@1.13.4-snapshot.v20251125180024 --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.57.1-snapshot.v20251125180024 --save-exact

@clerk/react-router

npm i @clerk/react-router@2.3.1-snapshot.v20251125180024 --save-exact

@clerk/remix

npm i @clerk/remix@4.13.21-snapshot.v20251125180024 --save-exact

@clerk/shared

npm i @clerk/shared@3.36.1-snapshot.v20251125180024 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@0.27.6-snapshot.v20251125180024 --save-exact

@clerk/testing

npm i @clerk/testing@1.13.20-snapshot.v20251125180024 --save-exact

@clerk/themes

npm i @clerk/themes@2.4.41-snapshot.v20251125180024 --save-exact

@clerk/types

npm i @clerk/types@4.101.4-snapshot.v20251125180024 --save-exact

@clerk/vue

npm i @clerk/vue@1.17.1-snapshot.v20251125180024 --save-exact
@alexcarpenter
Copy link
Member Author

!snapshot

@clerk-cookie
Copy link
Collaborator

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/agent-toolkit@0.2.9-snapshot.v20251215203425 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.0-snapshot.v20251215203425 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.0-snapshot.v20251215203425 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.0-snapshot.v20251215203425 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.0-snapshot.v20251215203425 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@1.0.0-snapshot.v20251215203425 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.0-snapshot.v20251215203425 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.0-snapshot.v20251215203425 --save-exact

@clerk/express

npm i @clerk/express@2.0.0-snapshot.v20251215203425 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.6.9-snapshot.v20251215203425 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.0-snapshot.v20251215203425 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.0-snapshot.v20251215203425 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.0-snapshot.v20251215203425 --save-exact

@clerk/react

npm i @clerk/react@6.0.0-snapshot.v20251215203425 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.0-snapshot.v20251215203425 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.0-snapshot.v20251215203425 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20251215203425 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.0-snapshot.v20251215203425 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.0-snapshot.v20251215203425 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.0-snapshot.v20251215203425 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.0-snapshot.v20251215203425 --save-exact
@alexcarpenter
Copy link
Member Author

!snapshot

@clerk-cookie
Copy link
Collaborator

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/agent-toolkit@0.2.9-snapshot.v20251215210631 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.0-snapshot.v20251215210631 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.0-snapshot.v20251215210631 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.0-snapshot.v20251215210631 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.0-snapshot.v20251215210631 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@1.0.0-snapshot.v20251215210631 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.0-snapshot.v20251215210631 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.0-snapshot.v20251215210631 --save-exact

@clerk/express

npm i @clerk/express@2.0.0-snapshot.v20251215210631 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.6.9-snapshot.v20251215210631 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.0-snapshot.v20251215210631 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.0-snapshot.v20251215210631 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.0-snapshot.v20251215210631 --save-exact

@clerk/react

npm i @clerk/react@6.0.0-snapshot.v20251215210631 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.0-snapshot.v20251215210631 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.0-snapshot.v20251215210631 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20251215210631 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.0-snapshot.v20251215210631 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.0-snapshot.v20251215210631 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.0-snapshot.v20251215210631 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.0-snapshot.v20251215210631 --save-exact
@alexcarpenter
Copy link
Member Author

!snapshot

@clerk-cookie
Copy link
Collaborator

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/agent-toolkit@0.2.9-snapshot.v20251215212157 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.0-snapshot.v20251215212157 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.0-snapshot.v20251215212157 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.0-snapshot.v20251215212157 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.0-snapshot.v20251215212157 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@1.0.0-snapshot.v20251215212157 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.0-snapshot.v20251215212157 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.0-snapshot.v20251215212157 --save-exact

@clerk/express

npm i @clerk/express@2.0.0-snapshot.v20251215212157 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.6.9-snapshot.v20251215212157 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.0-snapshot.v20251215212157 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.0-snapshot.v20251215212157 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.0-snapshot.v20251215212157 --save-exact

@clerk/react

npm i @clerk/react@6.0.0-snapshot.v20251215212157 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.0-snapshot.v20251215212157 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.0-snapshot.v20251215212157 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20251215212157 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.0-snapshot.v20251215212157 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.0-snapshot.v20251215212157 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.0-snapshot.v20251215212157 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.0-snapshot.v20251215212157 --save-exact
@alexcarpenter alexcarpenter changed the title feat(clerk-js): PortalProvider POC feat(clerk-js): Introduce UNSAFE_PortalProvider Dec 15, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment