refactor(ui): Improve UserButton accessibility

[alexcarpenter]

Description

The UserButton popover was updated from role="menu" with role="menuitem" children to role="dialog" with role="group" sections. Focus management was fixed using floating-ui's
interaction system (useInteractions, useClick, useRole, useDismiss) instead of manual onClick/aria-* wiring.

Why dialog, not menu

The WAI-ARIA menu role is for a list of differing actions — like a right-click context menu or a menubar dropdown. Every child must be a menuitem, menuitemcheckbox, or
menuitemradio. The UserButton popover contains:

• A user profile preview (not an action)
• Account management buttons
• Session switcher cards
• A sign-out section
• A branded footer with links

This is mixed content, not a flat action list. Forcing menuitem on non-action elements (previews, footers) creates a misleading experience for screen reader users — they hear
"menu with 8 items" when only 3 are actionable. The dialog role correctly communicates that this is a container with varied, grouped content.

Key implementation details

• initialFocus={popoverRef} — Focuses the dialog container on open (screen reader announces "Account panel dialog"), not the first interactive child. Tab then moves to the first
  action.
• order={['content']} — Excludes the trigger from the popover's Tab cycle.
• useInteractions — Properly composes useClick, useDismiss, useRole through floating-ui instead of manual onClick={toggle} and hardcoded aria-* attributes.
• role="group" + aria-label on action sections — Groups related actions ("Account actions", "Active sessions") for screen reader navigation.
• role={undefined} on individual actions — Removes the inherited menuitem role since they're no longer inside a menu.
• Identity-first trigger label — "First Last - Open account panel" instead of generic "Open user menu", so screen readers announce who the button belongs to

Fixes USER-4842

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 15, 2026 10:49pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: bab5d9f

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