You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[a11y] Focus guard sentinels are exposed as nameless buttons in WebKit (axe button-name violation) #5237
— are focusable (tabindex="0"), carry role="button", and have no accessible name. In Chromium and Firefox they are excluded from the accessibility tree, so axe passes. In WebKit they are exposed, and axe flags button-name (serious) on every guard.
Environment
@base-ui/react1.6.0
Playwright 1.61.1 (webkit), axe-core4.12.1 via @axe-core/playwright
Render any focus-trapping surface (observed with a Dialog-based sheet/drawer and a command-palette dialog) in the open state.
Run an axe scan in Playwright WebKit.
button-name violations are reported against the [data-base-ui-focus-guard] spans (selector observed: span[data-type="inside"][data-base-ui-focus-guard=""][role="button"]). The same scan passes in Chromium and Firefox.
Expected
Focus guards should be invisible to assistive technology — e.g. aria-hidden="true" on the sentinels (they are focus plumbing, not actionable controls), or an accessible name if they are intentionally exposed.
Impact
Safari/VoiceOver users can land on an unnamed "button" at popup boundaries.
Cross-engine axe gates (CI a11y suites running the WebKit engine) fail on every story/page with an open trapped popup, with no workaround available from userland — the guards are re-rendered by Base UI on focus changes, so consumer-side DOM patching is not durable.
Happy to provide a minimal repro repository if useful.
Thanks for the report - this is intentional: Safari/VoiceOver needs the guard exposed as a button so swiping triggers focus, which is then redirected into the popup. Adding aria-hidden would break that behavior. Axe supports excluding these implementation elements with .exclude('[data-base-ui-focus-guard]').
That said, I haven't checked recently if role=button could be replaced with an alternative. This was manual testing on my behalf done several years ago.
In Chromium, they render with aria-hidden="true" and tabindex="0". In our tests with portaled Select, Combobox and Menu popups open, axe reported aria-hidden-focus. Results varied between "needs review" and a violation; one violation occurred with a Select near the bottom of a scrolled page.
We tried removing aria-hidden from the guards. That exposed a submenu's outside guards to accessibility checks within the parent role="menu", and axe reported aria-required-children. Those guards render at the Portal's original location, outside the portaled content.
It also changed keyboard behavior: with an open modal Menu, Tab closed the menu and moved focus to the next control, while with the guards unchanged focus stayed in the menu. Removing aria-hidden was the only difference between the two runs.
We reverted the workaround and now exclude [data-base-ui-focus-guard] from axe, following your suggestion. A note in the accessibility docs about this exclusion would help consumers who run into either rule.
Environment: @base-ui/react 1.8.0, Chromium 153.0.8010.12, axe-core 4.12. The FocusGuard.mjs implementation is identical in 1.9.0.
We see the same in VoiceOver on macOS with 1.6.0: the guard reads as a button with no name. As a local workaround, FocusGuard sets aria-label when it has a role (we use "Focus boundary"), unless the caller passes one.
Activity
atomiks commentedon Jul 15, 2026
Thanks for the report - this is intentional: Safari/VoiceOver needs the guard exposed as a button so swiping triggers focus, which is then redirected into the popup. Adding aria-hidden would break that behavior. Axe supports excluding these implementation elements with .exclude('[data-base-ui-focus-guard]').
That said, I haven't checked recently if role=button could be replaced with an alternative. This was manual testing on my behalf done several years ago.
test: accept Base UI focus guards in WebKit with a decision (INNO-1184)
test: accept Base UI focus guards in WebKit with a decision (INNO-118…
Carvalh0XYZ commentedon Oct 10, 2026
Adding a Chromium data point for the same guards.
In Chromium, they render with
aria-hidden="true"andtabindex="0". In our tests with portaled Select, Combobox and Menu popups open, axe reportedaria-hidden-focus. Results varied between "needs review" and a violation; one violation occurred with a Select near the bottom of a scrolled page.We tried removing
aria-hiddenfrom the guards. That exposed a submenu's outside guards to accessibility checks within the parentrole="menu", and axe reportedaria-required-children. Those guards render at the Portal's original location, outside the portaled content.It also changed keyboard behavior: with an open modal Menu, Tab closed the menu and moved focus to the next control, while with the guards unchanged focus stayed in the menu. Removing
aria-hiddenwas the only difference between the two runs.We reverted the workaround and now exclude
[data-base-ui-focus-guard]from axe, following your suggestion. A note in the accessibility docs about this exclusion would help consumers who run into either rule.Environment:
@base-ui/react1.8.0, Chromium 153.0.8010.12, axe-core 4.12. TheFocusGuard.mjsimplementation is identical in 1.9.0.dimitriknight commentedon Nov 16, 2026
We see the same in VoiceOver on macOS with 1.6.0: the guard reads as a button with no name. As a local workaround,
FocusGuardsetsaria-labelwhen it has arole(we use "Focus boundary"), unless the caller passes one.