gridcn2.0.0
Sort, filter, and search

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.

Name
Email
Role
Score
Silent Tiger
user0@example.com
Viewer
4
Quick Lion
user1@example.com
Viewer
89
Swift Wolf
user2@example.com
Manager
80
Eager Lion
user3@example.com
User
51
Eager Tiger
user4@example.com
Viewer
83
Silent Wolf
user5@example.com
User
15
Swift Lion
user6@example.com
Viewer
62
Eager Lion
user7@example.com
Manager
42
Eager Eagle
user8@example.com
Editor
35
Bold Tiger
user9@example.com
Editor
52
Bold Bear
user10@example.com
User
28
Swift Wolf
user11@example.com
Manager
9
Swift Bear
user12@example.com
Viewer
45
Eager Wolf
user13@example.com
Editor
44
Swift Eagle
user14@example.com
Viewer
51
Quick Lion
user15@example.com
Manager
28
Bold Wolf
user16@example.com
Editor
76
Swift Eagle
user17@example.com
Admin
26
Eager Eagle
user18@example.com
Manager
70
Eager Bear
user19@example.com
Editor
67
Silent Lion
user20@example.com
Manager
89
Silent Tiger
user21@example.com
Manager
40
Eager Tiger
user22@example.com
Manager
82
Silent Lion
user23@example.com
Admin
16
Bold Eagle
user24@example.com
Admin
38
Bold Lion
user25@example.com
Viewer
3
Quick Tiger
user26@example.com
Viewer
41
Bold Eagle
user27@example.com
Editor
10
Swift Tiger
user28@example.com
Editor
6
Silent Lion
user29@example.com
Viewer
42
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:

  1. The column sortCompare(rowA, rowB). A result of 0, NaN, or a thrown error passes the pair to the text compare.
  2. The compare of the column's declared cell type. Numbers sort by value, dates in date order, and select columns by choice label. The text, longText, and url types use the text compare of the next step.
  3. A text compare that ignores case and accents and reads digit runs as numbers, so item2 comes before item10. A column that omits type uses 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.

PropTypeDefaultDescription
allColumnsbooleanfalseOffers hidden columns for new sorts.
classNamestringnoneClasses for the button.

Keyboard & accessibility

KeyAction
TabMoves through a row: column select, direction select, remove button, drag handle.
ArrowUp / ArrowDown on the drag handleMoves the sort one place and keeps focus on the handle.
Backspace / Delete on the drag handleRemoves 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.

On this page