[EuiProgress][A11y] Announce determinate progress update to screen readers

[mgadewoll]

Summary

closes #8837

This PR updates EuiProgress to ensure that progress updates are announces to screen reader users. Previously users would only be able to know the current progress of the element by manually navigating to it in the DOM.

Changes

• adds a aria-live region in EuiProgress that mirrors the values of label and value, reading on progress update e.g. Loading 10%
  • ℹ️ Due to the native behavior of aria-live with aria-atomic the initial value will not be output, only updates will trigger an output. This is expected as we don't want the value to be read on mount but only on update. This means we can support static value display as well as loading states.
• removes the visible label and valueText output from the accessibility tree with aria-hidden:
  • because we're adding an aria-live region with the same text, we prevent duplicate content for screen reader users this way
• removes aria-hidden on the <progress> element:
  • ℹ️ aria-hidden was used here previously with the assumption that the <progress> element and valueText duplicate each other. This is true but having the <progress> element available in the DOM has a few benefits:
    • a) the element is perceivable in the DOM on user navigation and provides semantic information on demand next to the automatic updates
    • b) the available <progress> element can trigger update sounds (not reading it's value but providing a sound-icon indication of progress) when available
    • c) providing the label and progress aligns the screen reader experience closer with the visual output

Why are we making this change?

This update improves the accessibility of the EuiProgress component by ensuring that users are receiving updates directly without the need to manually focus the component in the DOM.

WCAG 4.1.3 Status Messages

Screenshots

AT	valueText={false}	valueText={true}	valueText={${value} steps}`
NVDA	Screen.Recording.2025-07-03.at.11.23.03.mov	Screen.Recording.2025-07-03.at.11.23.31.mov	Screen.Recording.2025-07-03.at.11.32.51.mov
JAWS

Impact to users

🟢 This PR does not contain breaking changes nor does it require updates on consumer side.

QA

• checkout this PR and open the newly added story `EuiProgress > Determinate Loading"
  • verify that the progress updates are correctly announced to the screen reader (NVDA/JAWS, VoiceOver)
  • verify that navigating the DOM with the screen reader will read the label/status and progress bar

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)
• 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)

[mgadewoll]

ℹ️ Removing aria-hidden is intentional but I'm open to opinions here.

The previous idea here was that the progress bar is not needed as it's a graphical representation of the valueText.
Why I chose to always have the <progress> element on the accessibility tree has a couple reasons:

• a) the element is perceivable in the DOM on user navigation and provides semantic information on demand next to the automatic updates (a user navigating to this element will hear it's semantic role and it's aria-valuetext e.g. "progressbar 10%`)
• b) the available <progress> element can trigger update sounds (not reading it's value but providing a sound-icon indication of progress) when available
• c) providing the label and progress aligns the semantic screen reader experience closer with the visual output

[weronikaolejniczak]

The description is 👨🏻‍🍳👌🏻 It made it super easy to understand the issue and what you're proposing. And thanks for applying my suggestions so quickly! 🐎

Having compared the current solution and the version from this PR, I agree with the decision. <progress> in the accessibility tree brings a11y benefits that cannot be easily replicated with custom code.

Announcing the progress seems to be in accordance with the SC 4.1.3, from Understanding WCAG "Status Message":

An application displays a progressbar to indicate the status of an upgrade. The element is assigned a suitable role. The screen reader provides intermittent announcements of the progress.

I have one doubt though that I'm not sure how we could resolve and if it's necessary (how many times is EuiProgress used for fast processes and / or with long labels?).

Testing notes

VoiceOver (MacOS + Safari)

🔉 valueText={false}

Screen.Recording.2025-07-04.at.13.56.48.mov

🔉 valueText={true}

Screen.Recording.2025-07-04.at.13.57.48.mov

🔉 custom valueText

Screen.Recording.2025-07-04.at.13.58.57.mov

NVDA (Win + Edge)

🔉 valueText={false}

Screen.Recording.2025-07-04.at.13.46.14.mov

🔉 valueText={true}

Screen.Recording.2025-07-04.at.13.48.26.mov

🔉 custom valueText

Screen.Recording.2025-07-04.at.13.50.39.mov

JAWS (Win + Edge)

🔉 valueText={false}

Screen.Recording.2025-07-04.at.14.07.02.mov

🔉 valueText={true}

Screen.Recording.2025-07-04.at.14.06.01.mov

🔉 custom valueText

Screen.Recording.2025-07-04.at.14.04.50.mov

---

Btw the JAWS screenshots in the description are uploaded to https://private-user-images.githubusercontent.com/ and so when I click on them to see the full image, it slaps me with 404 😞 I can sorta read the preview though.

[mgadewoll]

Btw the JAWS screenshots in the description are uploaded to https://private-user-images.githubusercontent.com/ and so when I click on them to see the full image, it slaps me with 404 😞 I can sorta read the preview though.

@weronikaolejniczak Thanks for mentioning it! Not sure why that's happening. I updated the links and I'm able to open them now, could you confirm?

[weronikaolejniczak]

@mgadewoll I can open the images now, thanks for updating them, Lene! 💚

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: d794c0b
• Documentation website

History

• 💚 Build #672 succeeded e8dd42b
• 💚 Build #668 succeeded fa71211
• 💚 Build #667 succeeded c18e230

cc @mgadewoll

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: d794c0b

History

• 💚 Build #4303 succeeded e8dd42b
• 💚 Build #4299 succeeded fa71211
• 💚 Build #4298 succeeded c18e230

cc @mgadewoll

[weronikaolejniczak]

Thanks for addressing all my concerns and suggestions, and adding some improvements yourself! This is a big a11y improvement IMO. Good job, Lene! 🟢

[mgadewoll]

@weronikaolejniczak Thank you for the great and detailed review 👏