Skip to content

fix(TableHeader): remove sort announcement props as no needed and update aria-sort handling#2291

Open
Bracciata wants to merge 8 commits intodevelopfrom
fix/table-header-sort-announcement
Open

fix(TableHeader): remove sort announcement props as no needed and update aria-sort handling#2291
Bracciata wants to merge 8 commits intodevelopfrom
fix/table-header-sort-announcement

Conversation

@Bracciata
Copy link
Copy Markdown
Contributor

@Bracciata Bracciata commented Mar 30, 2026

Summary

Fix NVDA screen reader announcing sort state on every table row cell.

Problem:
NVDA was reading "Rule sorted ascending" (or similar) for every cell in a sortable column, not just the column header.

For example:
row 2 RuleRule sorted ascending column 1 link and elements...
row 3 RuleRule sorted ascending column 1 link All page content...

Root cause:
TableHeader rendered an Offscreen live region
(role="status" aria-live="polite") inside the sort <button>. Because it
was inside the button, screen readers included the announcement text in the
column header's accessible name. NVDA then repeated that name for every cell
in the column.

Fix:
Removed the Offscreen live region entirely. Sort state is now
communicated solely via the aria-sort attribute on <th>, which is the
standard ARIA mechanism and is well-supported in modern screen readers (NVDA, JAWS, VoiceOver).

Changes

  • packages/react/src/components/Table/TableHeader.tsx — removed Offscreen
    live region from inside the sort button; marked sortAscendingAnnouncement
    and sortDescendingAnnouncement props as @deprecated for backwards compatibility

  • packages/react/src/components/Table/index.test.tsx — updated three tests
    to assert on aria-sort attribute instead of the removed live region content

Before / After (NVDA)

Before:
row 2 RuleRule sorted ascending column 1 link ...
row 3 RuleRule sorted ascending column 1 link ...

After:
row 1 column 1 sorted ascending Rule button
row 2 First Name column 1 Frank
row 3 First Name column 1 Jimmy

Closes: Walnut #13951

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adjusts the Table sorting announcement behavior so the sort live-region text is not included in the column header’s accessible name (preventing repeated announcements across cells in some screen readers).

Changes:

  • Moves the sort announcement live region out of the TableHeader render tree and into document.body.
  • Updates existing Table sort tests to align with the new live-region placement.
  • Adds a new test intended to ensure the announcement is not included in the header accessible name / table cells.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File Description
packages/react/src/components/Table/TableHeader.tsx Introduces a hook that appends an offscreen role="status" live region to document.body and updates its text as sort state changes.
packages/react/src/components/Table/index.test.tsx Removes icon-location assertions tied to the old DOM structure and adds a new test asserting the live region is outside the header/table.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread packages/react/src/components/Table/index.test.tsx Outdated
Comment thread packages/react/src/components/Table/TableHeader.tsx Outdated
Comment thread packages/react/src/components/Table/TableHeader.tsx Outdated
Comment thread packages/react/src/components/Table/index.test.tsx Outdated
Comment thread packages/react/src/components/Table/index.test.tsx Outdated
Comment thread packages/react/src/components/Table/index.test.tsx Outdated
@aws-amplify-us-east-1
Copy link
Copy Markdown

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2291.d15792l1n26ww3.amplifyapp.com

@Bracciata Bracciata changed the title fix: prevent every cell from announcing sort fix(Table): prevent every cell from announcing sort Mar 30, 2026
@Bracciata Bracciata marked this pull request as ready for review March 30, 2026 17:20
@Bracciata Bracciata requested a review from a team as a code owner March 30, 2026 17:20
Comment thread packages/react/src/components/Table/Table.tsx Outdated
Comment thread packages/react/src/components/Table/TableContext.tsx Outdated
Comment thread packages/react/src/components/Table/Table.tsx Outdated
Comment thread packages/react/src/components/Table/Table.tsx Outdated
Comment thread packages/react/src/components/Table/TableHeader.tsx Outdated
Comment thread packages/react/src/components/Table/index.test.tsx Outdated
Copy link
Copy Markdown
Contributor

@chornonoh-vova chornonoh-vova left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall looks good, left a couple of minor comments for your consideration.

chornonoh-vova
chornonoh-vova previously approved these changes Apr 1, 2026
Comment thread packages/react/src/components/Table/Table.tsx Outdated
Copy link
Copy Markdown
Contributor

@denysfedorov denysfedorov left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Just one small minor suggestion about contexts creation

Comment thread packages/react/src/components/Table/TableContext.tsx Outdated
@Bracciata Bracciata changed the title fix(Table): prevent every cell from announcing sort fix(TableHeader): remove sort announcement props as no needed and update aria-sort handling Apr 9, 2026
Replace the portal-based sort announcement approach with the simpler fix
from PR #2319: remove the Offscreen live region entirely and rely solely
on the aria-sort attribute on <th>. This prevents NVDA from repeating the
sort announcement text on every cell in the column.

- Remove SortAnnouncementPortal and related context from Table/TableContext
- Mark sortAscendingAnnouncement/sortDescendingAnnouncement as @deprecated
- Update tests to assert on aria-sort instead of live region content
@Bracciata Bracciata enabled auto-merge (squash) April 17, 2026 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants