[EuiButton] Support focusable disabled behavior with hasAriaDisabled prop

[mgadewoll]

Summary

closes #9098

This PR introduces custom disabled behavior for all base button components (EuiButton, EuiButtonEmpty, EuiButtonIcon, EuiButtonGroup, EuiFilterButton) via a new prop hasAriaDisabled.

Important

The new custom disabled behavior via hasAriaDisabled will be added as opt-in Beta feature and we will monitor usages and adjust/fix the functionality as needed.

If hasAriaDisabled=true is added, the buttons render with the aria-disabled attribute instead of the native disabled attribute. The main purpose for this is to preserve focusability of buttons while also keeping them semantically and functionally disabled. This is useful when wanting to add tooltips on disabled buttons provide additional information about the state.

aria-disabled provides the same semantic state as disabled but besides that does not prevent any events from firing.
This PR introduces a hook for handling disabled behavior that's used under the hood in the updated button components.

The hook ensures that:

• either aria-disabled or disabled are returned
• react event handlers are unset when disabled (e.g. onClick)
• programmatic events are prevented (e.g. .click())
• native DOM events are prevented when disabled (e.g. via dispatchEvent)
• focus, blur and required keyboard events are preserved

API changes

These apply to EuiButton, EuiButtonEmpty, EuiButtonIcon, EuiButtonGroup and EuiFilterButton.

new prop	type	default value	description
hasAriaDisabled	boolean	false	Changes the native disabled attribute to aria-disabled to preserve focusability. This results in a semantically disabled button with a custom disabled state behavior instead of the default browser one.

Additional changes

Because usages with hasAriaDisabled render aria-disabled instead of disabled, there are additional considerations for its usage:

• CSS selectors relying on :disabled won't work
• disabled test framework matchers won't work

To support the usage of hasAriaDisabled, this PR adds the following:

• euiDisabledSelector - variable that provides the combined CSS disabled selectors :disabled, [aria-disabled="true"]
• custom test matchers for the test frameworks used in EUI/Kibana
  • adds .toBeEuiDisabled for react-testing-library
  • adds .toHaveEuiDisabledProp for enzyme
  • adds should('be.euiDisabled) for Cypress

Why are we making this change?

💪 Usability: The update provides an enhanced disabled behavior that preserves focusability and supports consumer requests to allow adding tooltips on disabled buttons.

Screenshots #

Screen.Recording.2025-11-10.at.18.15.56.mov

Impact to users

🟢 There are no immediate updates needed on consumer side. The added functionality is in beta state and opt-in only.

Note

The changes have been run as pre-release in Kibana CI here)

ℹ️ Consumers that want to start using hasAriaDisabled on buttons, will need to update the following if used:

• test assertions checking for disabled attribute -> use the new EUI test helpers instead
• style selectors using :disabled pseudo-selector -> use euiDisabledSelector in CSS-in-JS/JS or :disabled, [aria-disabled="true"] in CSS instead

Note

Examples of test updates for RTL, Enzyme, Cypress, FTR and Playwright on Kibana have been prepared here.

QA

Note

It's suggested to review changes commit by commit.

🧪 Testing Story
📖 Documentation:

• EuiButton
• EuiButtonGroup

View added documentation screenshots

• test the updated button components and:
  • verify regular disabled state with hasAriaDisabled=false has no regressions with production
  • verify hasAriaDisabled={true} supports focus, blur and Tab and Escape key events
  • verify focus is preserved on a button that changes isDisabled state
  • verify hasAriaDisabled={true} prevents any mouse/pointer/touch event as well as any other keyboard event (not Tab or Escape key)
• review the added documentation and confirm it's clear and complete
• run yarn build and verify that the added test helpers are correctly bundled in @elastic/eui/lib/test

General checklist

• Browser QA
  • Checked in both light and dark modes
  • Checked in both MacOS and Windows high contrast modes
    • (emulate forced colors if you do not have access to a Windows machine.)
  • Checked in mobile
  • Checked in Chrome, Safari, Edge, and Firefox
  • Checked for accessibility including keyboard-only and screenreader modes
• Docs site QA
  • Added documentation
  • Props have proper autodocs (using @default if default values are missing) and playground toggles
  • Checked Code Sandbox works for any docs examples
• Code quality checklist
  • Added or updated jest and cypress tests
  • Updated visual regression tests
• Release checklist
  • A changelog entry exists and is marked appropriately
  • If applicable, added the breaking change issue label (and filled out the breaking change checklist)
  • If the changes unblock an issue in a different repo, smoke tested carefully (see Testing EUI features in Kibana ahead of time)
• Designer checklist
  • If applicable, file an issue to update EUI's Figma library with any corresponding UI changes. (This is an internal repo, if you are external to Elastic, ask a maintainer to submit this request)

ToDo

• add note about Beta component in Deprecations/Beta document [Meta] Deprecation and Beta schedule #1469
• add Beta tracking issue: [BETA] hasAriaDisabled for button components #9214

[acstll]

Not approving yet but shared mostly nits and non-blocking suggestions (would like to know what you think). I really like how this turned out and how the featured has been implemented.

I went through the suggested QA steps and it's all working as expected. I also thought (again) about naming of test helpers and they seem just right.

Amazing work ✨

[acstll]

🟢 Thanks for addressing my comments. The only thing left is reverting the TESTING_EXAMPLE story. Again, awesome work!

[mgadewoll]

@acstll Thanks for the thorough review and suggestions! ❤️

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: cd47a4f
• Documentation website
• Storybook

History

• 💚 Build #1926 succeeded 2fddd0c
• 💚 Build #1898 succeeded d9f31e8
• 💚 Build #1896 succeeded 9e283de
• 💚 Build #1886 succeeded c0d44e2
• 💚 Build #1885 succeeded 347efc9
• 💚 Build #1882 succeeded fd4b8bc

cc @mgadewoll

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: cd47a4f

History

• 💚 Build #5213 succeeded 2fddd0c
• 💚 Build #5190 succeeded d9f31e8
• 💚 Build #5188 succeeded 9e283de
• 💚 Build #5180 succeeded c0d44e2
• 💚 Build #5179 succeeded 347efc9
• 💚 Build #5177 succeeded fd4b8bc

cc @mgadewoll