Sorting
Order rows by one or more columns from the headers or from a toolbar sort list, and hand the sort to your server in server mode.
Users order rows by one column or by several. Every grid sorts its data by sortState. With headerClickBehavior="sort", a header click sets that state. The data-grid-sort-list add-on adds a toolbar button with a popover that adds, removes, and reorders sorts without the headers.
pnpm dlx shadcn@latest add @gridcn/data-grid-sort-list
The sample below also uses DataGridToolbar. Install the toolbar add-on as well.
This grid sorts from the headers, from the sort list, and from a seeded sort:
"use client";
import {
DataGridBody,
DataGridHeader,
DataGridProvider,
DataGridRoot,
defineColumns,
} from "@/components/data-grid/data-grid";
import {
DataGridSortList,
} from "@/components/data-grid-sort-list/data-grid-sort-list";
import {
DataGridToolbar,
} from "@/components/data-grid-toolbar/data-grid-toolbar";
type Person = { id: string; name: string; age: number };
const columns = defineColumns<Person>()([
{ id: "name", header: "Name", accessorKey: "name" },
{ id: "age", header: "Age", accessorKey: "age", type: "number" },
]);
export function PeopleGrid({ rows }: { rows: Person[] }) {
return (
<DataGridProvider
defaultData={rows}
columns={columns}
headerClickBehavior="sort"
defaultSortState={[{ columnId: "age", direction: "desc" }]}
>
<DataGridToolbar>
<DataGridSortList />
</DataGridToolbar>
<DataGridRoot className="h-96">
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridProvider>
);
}Sort from the headers
The default headerClickBehavior is "select", so a header click selects the column. With "sort", a plain click cycles the column: ascending first, then descending, then no sort. Shift+click adds the column to the sort. A new column joins at the end, so the first sort stays primary. Another Shift+click cycles that column in place.
A string header shows a sort arrow on every sorted column, whatever headerClickBehavior says. A sort from the sort list, the URL, or code shows the arrow too.
sortable: false on a column removes it from the header click and from the sort list. Code can still sort it with actions.setSorts(), and the header then shows the arrow and aria-sort. Read the sorts with useDataGridSortState().
Sort order
The first sort is primary. Each later sort orders only the rows that the earlier sorts leave tied. Rows that tie on every sort keep their original order.
A column compares two rows with the first of these that applies:
- The column
sortCompare(rowA, rowB). A result of0,NaN, or a thrown error passes the pair to the text compare. - The
compareof the column's declared cell type. Numbers sort by value, dates in date order, andselectcolumns by choice label. Thetext,longText, andurltypes use the text compare of the next step. - A text compare that ignores case and accents and reads digit runs as numbers, so
item2comes beforeitem10. A column that omitstypeuses it for text.
A column without type sorts numbers by value and puts them before any text. In development, a column that holds both numbers and text warns once. Set type: "number" to also get the number editor, alignment, and filters.
The direction applies to all three. Empty cells sort last in both directions.
sortLocale sets the language of every text compare. It covers the text, longText, url, select, and lookup types and columns without a type. It also orders the value lists of the header filter and the filter menu. It decides the text range filters (gt, gte, lt, lte, isBetween) too, so it changes which rows such a filter keeps. The default is the locale prop, then "en-US", so a server and a browser order rows alike. To format in one language and sort in another, set both: locale="de-DE" sortLocale="en-US".
A tag that is malformed or that the runtime does not support falls back to "en-US" with one development warning. A sortCompare or a custom compare orders by its own rule.
To follow the browser language, read navigator.language after mount and pass it. Code that sorts outside the grid compares with sortCollator(locale) from data-grid-sdk. withSortLocale(locale, run) sets the locale for a synchronous run only. Work after an await sorts with "en-US", so pass the locale to sortCollator there.
Sort list
DataGridSortList belongs in a DataGridToolbar. The button shows a count badge once a sort is active. Each row of the popover has a column select, a direction select, a remove button, and a drag handle. A column appears in one row only, and sortable: false columns do not appear. The popover also has "Add sort" and "Clear all" buttons.
The list reads and writes the same state as the headers, so both stay in step. The order of the rows is the sort precedence.
| Prop | Type | Default | Description |
|---|---|---|---|
allColumns | boolean | false | Offers hidden columns for new sorts. |
className | string | none | Classes for the button. |
Keyboard & accessibility
| Key | Action |
|---|---|
| Tab | Moves through a row: column select, direction select, remove button, drag handle. |
| ArrowUp / ArrowDown on the drag handle | Moves the sort one place and keeps focus on the handle. |
| Backspace / Delete on the drag handle | Removes the sort. Focus moves to the next row's handle, then the previous one, then "Add sort". |
Each move announces the new place through a polite live region. Set the text with labels.sort.sortReorderAnnouncement.
Controlled and initial sort
defaultSortState seeds the sort once, and later changes to it have no effect. sortState makes the prop the source of truth. onSortChange(next) fires on every user change in both cases. A controlled grid reorders its rows only after the sortState prop changes.
Server mode
If your server orders the rows, set sortMode="server". The grid tracks the sort spec and never reorders data. The header cycle, aria-sort, the sort arrow, the sort list, and onSortChange all work as in client mode.
A grid with a totalRowCount prop defaults sortMode to "server", because its data holds only part of the result. To sort the rows in data in the browser, set sortMode="client".
The request is the SortSpec[] that onSortChange receives. The answer is the rows, already in that order. sortLocale and locale do not reach the server: your server picks the collation of its own sort. The grid still uses sortLocale for the value lists of the header filter and the filter menu, and for text range filters under filterMode="client".
useDataGridServerRows sets sortMode, filterMode, and the controlled sort for you. It passes each fetch the spec as request.spec.sorts. Make that order total, because the hook keeps only the first row of a repeated row id. See Query server rows for the full flow.
Related
- Sort list options: the full prop list
- Filtering: hide rows by value
- Sort and filter events:
onSortChangeand its siblings - Query server rows: the server flow