refactor(ui): Menu interaction and accessibility improvements

[alexcarpenter]

Description

Improve Menu keyboard navigation and accessibility. Menus now support Enter/Space to open from the trigger, ArrowDown/ArrowUp/Home/End to move focus, Escape to close and return focus to the trigger, and skip disabled items during arrow-key navigation. Menus no longer mark the rest of the page as aria-hidden while open, so assistive technologies can still reach surrounding content.

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]

🦋 Changeset detected

Latest commit: ab8f5aa

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

This PR includes changesets to release 2 packages

Name	Type
@clerk/ui	Patch
@clerk/chrome-extension	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 19, 2026 1:20am

[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: 3795d99e-0515-474e-a99e-39e04abb2c7f

📥 Commits

Reviewing files that changed from the base of the PR and between b643f14 and ab8f5aa.

📒 Files selected for processing (1)

• .changeset/menu-keyboard-a11y.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/menu-keyboard-a11y.md

---

📝 Walkthrough

Walkthrough

The PR refactors Menu to provide Floating UI interaction handlers (getReferenceProps, getFloatingProps, getItemProps), activeIndex, and elementsRef; replaces custom trigger/toggle and keyboard logic with Floating UI utilities (FloatingList, useListItem, useMergeRefs); and changes MenuTrigger prop arialLabel → ariaLabel. Popover gains an optional modal?: boolean prop passed to FloatingFocusManager. Tests: added a comprehensive Menu test suite and an animations-disabled test wrapper for ConnectedAccountsSection. A changeset documents Menu accessibility updates and removal of page-wide aria-hidden while a menu is open.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• clerk/javascript#8328: Overlapping work on Menu Floating UI integration and ariaLabel rename.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: refactoring Menu components with keyboard navigation and accessibility improvements as the primary focus.
Description check	✅ Passed	The description is directly related to the changeset, detailing the specific keyboard interaction improvements and accessibility enhancements implemented in the Menu components.
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.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/ui/src/elements/Menu.tsx`:
- Around line 96-103: The prop rename from arialLabel to ariaLabel in
MenuTrigger/MenuTriggerProps is a breaking change; restore backward
compatibility by accepting both names: update MenuTriggerProps to allow
ariaLabel?: string | ((open: boolean) => string) and a deprecated arialLabel?:
string | ((open: boolean) => string), then in MenuTrigger compute the effective
label by preferring ariaLabel when present and falling back to arialLabel (e.g.,
derive normalizedAriaLabel from ariaLabel if defined, otherwise arialLabel), and
document/mark arialLabel as deprecated so consumers have a compatibility window;
ensure getReferenceProps/usage uses the normalized value.
- Around line 65-71: Add a regression test that renders the Menu component using
the same composition that wires useListNavigation and SimpleButton (i.e., Menu
with three items where the middle item has isDisabled) and assert keyboard arrow
navigation skips the disabled item: simulate focus on the first item, send
ArrowDown (and ArrowUp) key events, and verify focus moves from the first item
directly to the third item (and vice versa) rather than landing on the disabled
SimpleButton; reference the Menu component, useListNavigation, SimpleButton and
the isDisabled prop when locating code to test.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 9e51c4b4-043b-46d4-8292-2788f995a779

📥 Commits

Reviewing files that changed from the base of the PR and between 45b773a and cf5437f.

📒 Files selected for processing (6)

• .changeset/menu-keyboard-a11y.md
• packages/ui/src/components/UserProfile/__tests__/ConnectedAccountsSection.test.tsx
• packages/ui/src/elements/Menu.tsx
• packages/ui/src/elements/Popover.tsx
• packages/ui/src/elements/ThreeDotsMenu.tsx
• packages/ui/src/elements/__tests__/Menu.test.tsx

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: ab8f5aa