Sean/fix custom page unmount

[seanperez29]

Description

This PR improves custom user profile pages in @clerk/expo and adds support for push-only custom destinations.

Changes

• Preserves embedded user profile navigation when switching tabs on iOS.
• Keeps React Native custom page content mounted while another custom destination is pushed on top, preserving local React state.
• Correctly unmounts custom pages when they are actually removed from the navigation stack.
• Invalidates retained navigation when:
  • the active user changes;
  • any retained custom route is removed or renamed.
• Uses the custom page label as the native iOS navigation title.
• Adds customDestinations to UserProfileView and UserButton.
  • Destinations can be opened with useUserProfileCustomPageNavigation().push(path).
  • Destinations do not create rows on the root profile screen.
  • Existing customPages behavior remains unchanged.
• Rejects duplicate paths across custom pages and destinations.
• Adds a changeset and lifecycle regression coverage for these behaviors.

Testing

The change can be tested with a profile containing a visible custom page and a push-only destination:

1. Open the visible custom page.
2. Update some local state on that page.
3. Push the custom destination using push(path).
4. Confirm the destination has a native title and back button on iOS.
5. Navigate back and confirm the original page and its local state are preserved.
6. Switch to another Expo Router tab and return to the profile.
7. Confirm the current profile route and React state are still preserved.
8. Remove an earlier custom route while a later destination is open.
9. Confirm the profile returns to its root without displaying an empty or orphaned destination.
10. Confirm push-only destinations do not appear as rows on the profile root.

Validation performed:

• All 189 @clerk/expo tests pass.
• Type declaration generation passes.
• The full monorepo build passes.
• The native iOS app builds and the navigation lifecycle was verified in the Expo quickstart.
• Android Kotlin compilation passes.

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:

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 16, 2026 3:13am
swingset	Ready	Preview	Aug 16, 2026 3:13am

[changeset-bot]

🦋 Changeset detected

Latest commit: 4d5cc08

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

This PR includes changesets to release 1 package

Name	Type
@clerk/expo	Minor

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9463

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9463

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9463

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9463

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9463

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9463

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9463

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9463

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9463

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9463

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9463

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9463

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9463

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9463

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9463

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9463

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9463

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9463

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9463

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9463

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9463

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9463

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9463

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9463

commit: 4d5cc08