Skip to content

[a11y] Focus guard sentinels are exposed as nameless buttons in WebKit (axe button-name violation) #5237

Open

Description

@QusayNaserFHS

Summary

The visually-hidden focus-guard sentinels Base UI renders around trapped popups —

<span data-type="inside" tabindex="0" role="button" data-base-ui-focus-guard="" data-base-ui-inert=""
      style="clip-path: inset(50%); overflow: hidden; white-space: nowrap; border: 0px; padding: 0px; width: 1px; height: 1px; margin: -1px; position: fixed; top: 0px; left: 0px;"></span>

— 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/react 1.6.0
  • Playwright 1.61.1 (webkit), axe-core 4.12.1 via @axe-core/playwright
  • Reproduces deterministically (not load/timing dependent), light theme, headless

Repro

  1. Render any focus-trapping surface (observed with a Dialog-based sheet/drawer and a command-palette dialog) in the open state.
  2. Run an axe scan in Playwright WebKit.
  3. 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.

Activity

  1. atomiks commented on Jul 15, 2026

    @atomiks
    Contributor

    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.

  2. added
    type: expected behaviorThe current behavior is already the one expected.
    and removed on Jul 15, 2026
  3. Carvalh0XYZ commented on Oct 10, 2026

    @Carvalh0XYZ

    Adding a Chromium data point for the same guards.

    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.

  4. dimitriknight commented on Nov 16, 2026

    @dimitriknight

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    type: expected behaviorThe current behavior is already the one expected.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions