feat(ui): Introduce ams claim handling in UserButton context and components

[thiskevinwang]

• Added ams claim type to JWT payload for session management.
• Integrated useAms hook to conditionally render the "Manage account" action in the UserButton based on the active session's ams claim.
• Updated UserButton context to filter out the "Manage account" menu item when the ams claim is active, preventing users from accessing unavailable actions.

Description

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, Comment	Apr 27, 2026 3:43pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: fd5b5a4

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 728bc3d1-7c03-4939-b3ca-10566e1a90f2

📥 Commits

Reviewing files that changed from the base of the PR and between 00f9ff9 and fd5b5a4.

📒 Files selected for processing (6)

• packages/shared/src/types/jwtv2.ts
• packages/ui/src/components/UserButton/SessionActions.tsx
• packages/ui/src/contexts/components/UserButton.ts
• packages/ui/src/hooks/__tests__/useAms.test.ts
• packages/ui/src/hooks/index.ts
• packages/ui/src/hooks/useAms.ts

---

📝 Walkthrough

Walkthrough

This pull request introduces support for the ams claim in JWT tokens. A new AmsClaim type (defined as unknown) is added to the JWT payload types. A new useAms React hook is created to detect whether the ams claim is present in the active session's JWT claims, returning { isActive: boolean }. This hook is then integrated into multiple UI components—specifically in SessionActions and UserButton context—to conditionally hide the "manageAccount" action when the ams claim is active. The hook includes test coverage verifying behavior for both present and absent ams claims.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: introducing ams claim handling in UserButton context and components, which is the core focus across all modified files.
Description check	✅ Passed	The description is directly related to the changeset, detailing the addition of ams claim type, the useAms hook integration, and conditional rendering logic in UserButton.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8380

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: fd5b5a4