Implement accessibility fix for sortable DataTable headers

[rickyzhangca]

Related to github/accessibility#10272 and github/accessibility#10807

This pull request fixes the accessible names and descriptions of sortable DataTable column headers. The column header and sort button retain the concise rendered column name, while the button conveys the next sort action separately through an accessible description. The current sort state remains exposed through aria-sort on the column header, and consumer-provided ARIA attributes continue to pass through unchanged.

Keyboard sorting behavior is unchanged, and this focused fix does not introduce DataTable grouping behavior.

Before

CleanShot.2026-09-02.at.8.04.09.AM.mp4

After

CleanShot.2026-09-02.at.8.04.46.AM.mp4

Changelog

New

None.

Changed

• DataTable sortable column headers now keep the column name separate from the next sort action.
• Sort buttons expose the next action as an accessible description while column headers continue to expose the current state through aria-sort.
• Consumer-provided aria-label and aria-labelledby attributes are preserved.

Removed

None.

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Automated validation:

• npm test -- packages/react/src/DataTable/__tests__/DataTable.test.tsx packages/react/src/DataTable/__tests__/Table.test.tsx — 69 tests passed
• npm run type-check -w @primer/react
• npm run build -w @primer/react
• ESLint and Prettier checks for the changed source and test files
• git diff --check

The focused tests verify:

• Concise column header and sort button accessible names
• Next-action accessible descriptions for unsorted, ascending, and descending states
• aria-sort state transitions on the column header
• Keyboard operation of the sort button
• Preservation of consumer-provided aria-label and aria-labelledby attributes

There is no visual styling change. Reviewers can compare the before/after recordings above or inspect the Experimental/Components/DataTable/Features / WithSorting story in the browser accessibility tree.

[changeset-bot]

🦋 Changeset detected

Latest commit: 5a5864d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

[Copilot]

Copilot review overview

🟡 Changes recommended

TableSortHeader currently applies a derived aria-label to the <th> by default (overriding consumer aria-labelledby) and doesn’t ensure an icon-only sort button gets an accessible name when a consumer provides aria-label.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review tier: Lite
Findings: 1

New issues introduced by this change (1)

Severity	Finding
	packages/​react/​src/​DataTable/​Table.tsx — TableSortHeader currently sets an aria-label on the <th> even when the consumer did not…

What changed in this PR

This PR updates Primer React’s DataTable sortable column headers to improve accessibility by keeping the header/button accessible name concise (column text) while moving the “next sort action” announcement into an accessible description, and adds regression tests plus a changeset.

Changes:

• Updated TableSortHeader to remove the hidden “sort ascending” text from the name and instead set the next action via aria-description.
• Added/updated tests to assert accessible name/description behavior across sort state transitions and for consumer-provided labels.
• Added a patch changeset documenting the accessibility behavior change.

File	Description
packages/​react/​src/​DataTable/​Table.tsx	Adjusts sortable header ARIA behavior (name vs. description) for better screen reader output.
packages/​react/​src/​DataTable/​__tests__/​Table.test.tsx	Adds a regression test covering consumer-provided aria-label handling for TableSortHeader.
packages/​react/​src/​DataTable/​__tests__/​DataTable.test.tsx	Adds a regression test for button accessible description across sort transitions; updates a prior assertion to match the new naming.
.changeset/​friendly-tables-sort.md	Documents the accessibility change as a patch release.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.