[DataGrid] Describe column and action in sort button labels by minwookshin · Pull Request #23755 · mui/mui-x

minwookshin · 2026-10-03T06:25:03Z

Give each column sort button a unique, localized accessible name. The name contains the column name and the action of the next click, for example "Sort Brand in ascending order", "Sort Brand in descending order", or "Remove sorting from Brand".

Changes

Add the columnHeaderSortIconAriaLabel(columnName, direction) locale key. direction is the sort direction that the next click applies.
Add an optional columnName prop to GridColumnHeaderSortIcon. The column header passes headerName ?? field, so the label updates after a new columns prop or updateColumns(). A custom sort icon slot without this prop uses field.
Pivot panel: the sort button gets the name from the initial column definitions, so derived fields such as "Shipped (Year)" have the correct name while pivoting is off. The click now follows sortingOrder, so the click and the label always agree.
Add translations for deDE, esES, frFR, itIT, jaJP, koKR, nlNL, ptBR, ptPT, thTH, zhCN, and zhTW. The other locales show the English text until someone translates the key.

Behavior changes

columnHeaderSortIconLabel now sets only the tooltip. Before this change, it also set the accessible name of the sort button. Apps with a custom translation of columnHeaderSortIconLabel must also translate columnHeaderSortIconAriaLabel. An explicit aria-label in slotProps.columnHeaderSortIcon still overrides the accessible name.
The pivot panel sort button now follows the sortingOrder prop. Before this change, it always used ascending, descending, then no sort. With the default sortingOrder, the behavior does not change.
I have followed (at least) the PR section of the contributing guide.

code-infra-dashboard · 2026-10-03T06:28:51Z

Deploy preview

docs/data/data-grid/localization/data.json

Bundle size

Bundle	Parsed size	Gzip size
@mui/x-data-grid	🔺+312B^(+0.07%)	🔺+119B^(+0.09%)
@mui/x-data-grid-pro	🔺+312B^(+0.05%)	🔺+117B^(+0.07%)
@mui/x-data-grid-premium	🔺+343B^(+0.04%)	🔺+121B^(+0.05%)
@mui/x-charts	0B^(0.00%)	0B^(0.00%)
@mui/x-charts-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-charts-premium	0B^(0.00%)	0B^(0.00%)
@mui/x-date-pickers	0B^(0.00%)	0B^(0.00%)
@mui/x-date-pickers-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-tree-view	0B^(0.00%)	0B^(0.00%)
@mui/x-tree-view-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-scheduler	0B^(0.00%)	0B^(0.00%)
@mui/x-scheduler-premium	0B^(0.00%)	0B^(0.00%)
@mui/x-chat	0B^(0.00%)	0B^(0.00%)
@mui/x-license	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Check out the code infra dashboard for more information about this PR.

minwookshin · 2026-10-03T07:03:44Z

Updated the keyboard test to use the column-specific sort label. All three Data Grid browser suites pass locally (2,585 tests).

github-actions · 2026-10-14T12:15:32Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

minwookshin · 2026-10-17T17:56:05Z

The type-label check is failing here and on #23756 because both PRs are missing a type label. Could a maintainer add type: bug to both? I do not have permission to apply repository labels.

github-actions · 2026-10-19T11:42:52Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

minwookshin · 2026-10-20T23:52:49Z

Merged the latest master and regenerated the localization report, keeping the new Turkish translations. Data Grid unit tests, the 106 Chromium sorting/keyboard tests, type checks and lint pass.

LukasTy

Thank you for your contribution. 🙏

Combined Claude Opus and GPT Astra findings

The approach is correct and follows the columnMenuAriaLabel precedent. The column name and the next direction need fixes before merge.

Wrong column name in the label (GridColumnSortButton.tsx:83): the button gets the name from apiRef.current.getColumn() during render. This gives a wrong name in two cases:
- Grid header: GridColumnHeaderSortIcon is React.memo and gets only field/direction/sortingOrder, so a headerName change does not re-render it. Repro: change headerName from 'Brand' to 'Maker' with updateColumns() or a new columns prop. The title shows "Maker", but the button says "Sort Brand in ascending order".
- Pivot panel: derived fields are only in gridPivotInitialColumnsSelector while pivoting is off, so getColumn() returns undefined. Repro: put date-year in the pivot columns with pivoting off. The panel shows "Shipped (Year)", but the button says "Sort date-year in ascending order".
- Fix for both: let the caller pass the column name. GridColumnHeaderItem has colDef (as ColumnHeaderMenuIcon does), and the pivot panel has its initial columns. Add a test for the headerName change.
Pivot panel label can contradict the action (GridPivotPanelField.tsx:394): the button computes the next direction from rootProps.sortingOrder, but handleSort (line 307) always cycles asc -> desc -> none. Repro: with sortingOrder={['desc', 'asc']}, the unsorted "Sales region" field says "Sort Sales region in descending order", and a click sets sort: 'asc'. Fix: make handleSort use getNextGridSortDirection(rootProps.sortingOrder, currentSort).
Localized grids now announce English (localeTextConstants.ts:152): the 43 non-English locales translate columnHeaderSortIconLabel ('Sortieren', 'Trier', ...), which was the aria-label. The new key is commented out in all of them, so these grids now announce "Sort Brand in ascending order" in English. Apps that override columnHeaderSortIconLabel also lose control of the aria-label (it now sets only the tooltip). This is the same trade-off as #16796. Please add translations where possible and state the behavior change in the PR body.

A few additional thoughts

Is there a reason not to use the same label for the tooltip?
If we reuse the same label, then we can deprecate columnHeaderSortIconLabel, or ship this only in the next major and swap the labels.

What are your thoughts about this @mui/grid?

minwookshin · 2026-10-21T21:07:02Z

Fixed both name cases by passing the name from the caller, and aligned the pivot click with getNextGridSortDirection. The four reported cases now have regression tests. I also added 11 locale translations and documented the new key and remaining English fallbacks in the PR body.

The tooltip still uses the existing key to keep that behavior compatible; I left deprecation to the API discussion. The 70 jsdom and 71 Chromium tests, all three Grid type checks, and lint pass.

LukasTy

Thanks for the updates. All earlier findings are fixed.

Header rename: the label updates after updateColumns() and after a new columns prop.
Pivot panel: with pivoting off, derived fields use the initial column name ("Shipped (Year)"). The click now follows sortingOrder, and the label matches the result for ['desc', 'asc'] and ['desc', 'asc', null].
Localization: 11 locales now have translations, and the PR body states the behavior change.

Translations: all 11 are grammatical and describe the correct next action. Some changes are recommended:

jaJP: the tooltip and the menu use "ソート" ('ソート', '昇順ソート', 'ソート解除'), but the new label uses "並べ替え". Use the same term: ${columnName}を昇順でソート, ${columnName}を降順でソート, ${columnName}のソートを解除.
ptPT: the menu uses "Classificar" ('Classificar por ordem crescente'), but the new label uses "Ordenar". Use the same term (see the string below).
frFR, itIT, esES, ptBR, ptPT: the column menu label in these locales says "the column X" ('Menu pour la colonne X', 'Menù della colonna X', 'Menú de la columna X', 'Menu da coluna X'). Use the same pattern here. It also fixes the French elision ("de Âge" must be "d'Âge") and the Italian "da X", which copies the English "from".
- frFR: Trier la colonne ${columnName} par ordre croissant / décroissant, Supprimer le tri de la colonne ${columnName}
- itIT: Ordina la colonna ${columnName} in ordine crescente / decrescente, Rimuovi l'ordinamento della colonna ${columnName}
- esES: Ordenar la columna ${columnName} de forma ascendente / descendente, Quitar la ordenación de la columna ${columnName}
- ptBR: Ordenar a coluna ${columnName} em ordem crescente / decrescente, Remover a ordenação da coluna ${columnName}
- ptPT: Classificar a coluna ${columnName} por ordem crescente / decrescente, Remover a classificação da coluna ${columnName}

Optional: columnName is now a required prop on the public GridColumnHeaderSortIconProps. Code that renders GridColumnHeaderSortIcon directly gets a type error, and without the prop the label reads "Sort undefined in ascending order". A GitHub code search finds no such usage outside forks, so the risk is low. You can make the prop optional with a field fallback to keep the type non-breaking.

I would still like to leave the approval right to the Grid team.
There is also the topic of reusing the same labels for the tooltip.

github-actions · 2026-10-22T18:00:42Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

minwookshin · 2026-10-22T18:04:51Z

Aligned the six locales with the existing menu wording and made columnName optional, with a field fallback and a regression test. The master conflict is resolved while preserving the new header-focus behavior. The sorting, header and keyboard suites pass in jsdom (114) and Chromium (126), along with all four Grid package type checks.

minwookshin · 2026-10-22T18:26:59Z

Netlify failed in next/font while parsing a Google font URL (loader.js:122). The previous preview passed with the same font setup and lockfile. Could a maintainer retry this deploy?

LukasTy

Thank you for the contribution. 🙏
LGTM, but I would still like a 2nd look from the Data Grid team.
I'd suggest deprecating the existing "Sort" label and using the same label for the <Tooltip /> title, but maybe it's just me, and others think otherwise for some reason. 🤷‍♂️

cherniavskii · 2026-10-23T14:55:48Z

I'd suggest deprecating the existing "Sort" label and using the same label for the title, but maybe it's just me, and others think otherwise for some reason. 🤷‍♂️

Instead of deprecation, how about extending current columnHeaderSortIconLabel to a union?

columnHeaderSortIconLabel: string | (columnName: string, direction: GridSortDirection) => string;

LukasTy · 2026-10-23T15:13:33Z

Instead of deprecation, how about extending current columnHeaderSortIconLabel to a union?

That's also a very nice option. 👍
However, the main question is if we want the tooltip title to also change and reflect what aria-label tells.

cherniavskii · 2026-10-26T09:49:28Z

However, the main question is if we want the tooltip title to also change and reflect what aria-label tells.

Sorry, I missed that part. I'm leaning a bit more towards showing simple "Sort" or "Sort asc/Sort desc/Unsort" labels in the tooltip, but no strong preference here.

minwookshin · 2026-10-26T15:54:11Z

I've kept the short tooltip separate from the column/action text in the accessible label. Please let me know if you'd prefer the union API. The Thai translation is in; sorting tests pass in jsdom and Chromium (38 each), along with all four Grid package type checks.

github-actions · 2026-10-27T16:50:18Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

LukasTy · 2026-10-28T16:08:16Z

@minwookshin, could you merge master and resolve the conflicts?

minwookshin · 2026-10-28T18:35:49Z

Merged master and regenerated the localization report. Sorting/pivot tests pass in jsdom (62) and Chromium (63), along with grid types, lint and builds. Argos reports one changed screenshot; could you review the comparison?

[DataGrid] Describe column and action in sort button labels

b19fd93

[DataGrid] Update keyboard test for sort button label

ef43763

zannager added the scope: data grid Changes related to the data grid. label Oct 6, 2026

github-actions Bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 14, 2026

Merge master into fix-grid-sort-button-labels

23ea82e

github-actions Bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 15, 2026

github-actions Bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 19, 2026

chore: merge master and regenerate localization report

155d4bc

github-actions Bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 20, 2026

LukasTy added accessibility a11y type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. labels Oct 21, 2026

LukasTy reviewed Oct 21, 2026

View reviewed changes

LukasTy requested a review from a team October 21, 2026 09:32

[DataGrid] Keep sort labels aligned with names and actions

ec6b091

LukasTy reviewed Oct 22, 2026

View reviewed changes

[DataGrid] Refine sort labels and preserve sort icon compatibility

3058d94

github-actions Bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 22, 2026

Merge master and preserve sort icon focus handling

290b4f3

github-actions Bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 22, 2026

LukasTy approved these changes Oct 23, 2026

View reviewed changes

siriwatknp reviewed Oct 26, 2026

View reviewed changes

Comment thread packages/x-data-grid/src/locales/thTH.ts Resolved

fix(data-grid): Add Thai sort button labels

04669c0

github-actions Bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 27, 2026

Merge master into fix-grid-sort-button-labels

005d7dd

github-actions Bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Oct 28, 2026

Merge branch 'master' into fix-grid-sort-button-labels

6cd98b7

LukasTy merged commit a9a823b into mui:master Oct 30, 2026
22 checks passed

martastn mentioned this pull request Nov 5, 2026

build(deps): bump @mui/x-data-grid from 9.14.0 to 9.17.0 yaptide/ui#2484

Merged

Conversation

minwookshin commented Oct 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Behavior changes

Uh oh!

code-infra-dashboard Bot commented Oct 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploy preview

Bundle size

Uh oh!

minwookshin commented Oct 3, 2026

Uh oh!

github-actions Bot commented Oct 14, 2026

Uh oh!

minwookshin commented Oct 17, 2026

Uh oh!

github-actions Bot commented Oct 19, 2026

Uh oh!

minwookshin commented Oct 20, 2026

Uh oh!

LukasTy left a comment

Choose a reason for hiding this comment

Combined Claude Opus and GPT Astra findings

A few additional thoughts

Uh oh!

minwookshin commented Oct 21, 2026

Uh oh!

LukasTy left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 22, 2026

Uh oh!

minwookshin commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

minwookshin commented Oct 22, 2026

Uh oh!

LukasTy left a comment

Choose a reason for hiding this comment

Uh oh!

cherniavskii commented Oct 23, 2026

Uh oh!

LukasTy commented Oct 23, 2026

Uh oh!

Uh oh!

cherniavskii commented Oct 26, 2026

Uh oh!

minwookshin commented Oct 26, 2026

Uh oh!

github-actions Bot commented Oct 27, 2026

Uh oh!

LukasTy commented Oct 28, 2026

Uh oh!

minwookshin commented Oct 28, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

minwookshin commented Oct 3, 2026 •

edited

Loading

code-infra-dashboard Bot commented Oct 3, 2026 •

edited

Loading

minwookshin commented Oct 22, 2026 •

edited

Loading