Live region messages
Look up what the grid live region reads and the label that sets each message, from row moves and checks to stale views, refused saves, and load results.
The core adds one role="status" live region with aria-live="polite".
Row moves, checked rows, and result counts
A live region cannot sit inside role="grid", so the grid places it in <body>. These changes read in the region:
- A row move, for example "Row 3 moved to position 4 of 8" (
labels.markers.reorderAnnouncement). - The number of checked rows after a check, an uncheck, or Escape, and after Ctrl/Cmd+A clears them, for example "3 rows checked" (
labels.grid.rowsChecked). The count includes hidden checked rows. Under "all matching", it counts the result minus the unchecked rows. - "All matching rows checked" after select all matching on a result of unknown size (
labels.grid.allMatchingChecked).
The region waits 500 ms after the last change. A marker range drag gets one reading, with its final count. A repeated change reads its text again.
With announceResults, the region also reads the number of rows of the view after a client filter or sort change, for example "42 rows" (labels.grid.resultsCount). A filter change that keeps the same rows in the same order stays quiet. Every sort change announces. A mount stays quiet. In scroll mode, while some rows have not arrived, the region counts the loaded rows only, for example "42 loaded rows" (labels.grid.resultsCountLoaded). With client pagination, the count covers every page, like the footer.
A server sort or filter change announces nothing. With announceResults, the region reads the result when the next load ends. A load that began with zero rows also reads its result count. See Load result. A client filter announces under sortMode="server". With announceResults in a server grid, a new numeric totalRowCount becomes the result count.
announceResults is a boolean grid prop with the default false. Checked rows lists it.
Messages with a label
The table lists each message and its labels.grid entry. Set the text of a message in the labels prop:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Task = { id: string; title: string };
const columns = defineColumns<Task>()([
{ id: "title", header: "Title", accessorKey: "title" },
] as const);
const getRowId = (task: Task) => task.id;
const labels = {
grid: {
saveRejected: (count: number) => `Could not save ${count} rows`,
},
};
export function Tasks({ tasks }: { tasks: Task[] }) {
return (
<DataGrid
data={tasks}
columns={columns}
getRowId={getRowId}
labels={labels}
/>
);
}| Message | Label | Reads when |
|---|---|---|
| Stale view | labels.grid.viewStale | A write changes a value that the sort or filter reads: an edit, a paste, a fill, a clear, or a push. It reads once when the view turns stale, and at most once every 30 seconds, in every data mode. |
| Refused save | labels.grid.saveRejected | The server refuses rows of a save. It reads the row count, for example "2 rows not saved". |
Undo or redo, rows not loaded (needs data-grid-history) | labels.grid.historyRowsNotLoaded | An undo or redo needs rows that are not loaded. |
| Undo or redo, rows gone | labels.grid.historyRowsGone | An undo or redo needs rows that do not exist. |
| Load result | labels.grid.resultsCount, resultsCountLoaded, or noResults | A load ends with announceResults on. The server spec or count changed, the load before failed, or a load from zero rows changed the count. |
Stale view
A stale row carries data-row-stale and no ARIA state. The live region carries the message, so the row needs no extra state.
Refused save
The message reads once for each settled change, also on a readOnly grid. The grid announces only the refusals that it read: a rejected onSave promise, or a rejected list in the answer. A row with a save in flight carries aria-busy="true" and data-save-status="saving". See Handle refused saves.
Load result
A load ends when loading goes from true to false. With announceResults, the region then reads the result if one of these holds:
- The server-evaluated filters, sort, search, or
totalRowCountchanged since the last load ended. - The load before it failed.
- The load began with zero rows and the result count changed. A refetch of an unchanged empty result stays quiet.
A block fill in scroll mode and a page change with the same count stay quiet. A server grid reads totalRowCount when it is a number, for example "1,234 rows". Otherwise it reads the loaded rows. When the view also holds unloaded rows, the text says so, for example "40 loaded rows" (labels.grid.resultsCountLoaded). Without unloaded rows, a count of 0 reads "No results" (labels.grid.noResults).
A load that ends with an error stays silent here, because the error bar has role="alert". The region waits 500 ms for the last announcement, so a run of fast refreshes while the user types is read once.
Add-on live regions
Add-ons bring their own live regions:
- The toolbar search reads its match count.
- The filter menu and the sort list read each reorder, for example "Name filter moved to position 2 of 3" (
labels.toolbar.filterReorderAnnouncement,labels.sort.sortReorderAnnouncement). - The find and replace panel and the status bar read their status text.
- The header filter and the value list of an
isAnyOffilter read their status text.
Read the message in code
useDataGridLiveAnnouncement() returns the current announcement as { kind, count, seq, partial? }, or null before the first one. Use it to mirror the message in your own UI.
Related
- Screen reader support: roles, counts, and focus rules
- Labels and i18n: translate the messages
- Stream updates: the pushes that make a view stale