Row Sorting
Click any sortable column header to sort. Click again to reverse. Hold Shift and click multiple headers to enable multi-column sort.
Enabling sorting
Sorting is opt-in per column. This grid opens unsorted — click a header once for ascending, again for descending, a third time to clear it.
Sorting is opt-in per column: set sortable: true on any column to show a sort icon
in its header and make it clickable. Each click cycles ascending → descending → unsorted.
{ key: 'salary', name: 'Salary ($)', prop: 'salary', sortable: true }
A column without it is inert — no icon, no cursor change, and a click does nothing. That is the usual reason a header "looks sortable but isn't": the grid-level option is on and the column flag is missing.
Initial sorts
The same grid, opened already sorted by salary, highest first. The sort rides the very first fetch — the server never sends an unsorted page that the reader then watches reorder.
config.initialSorts pre-sorts the grid on first load, without waiting for a click.
initialSorts: [{ key: 'salary', dir: 'desc' }]
It is included in the params of the first fetchRows() call, so the
server returns the first page already in order. Nothing arrives unsorted and then rearranges
under the reader.
Multi-column sort
Sorted by department, with salary ordering the rows inside each one — two sorts active at once. Hold Shift and click a third header to add to it; click one without Shift to drop back to a single sort.
A plain click sorts by that column alone and clears any other active sort. Hold Shift (or Ctrl/Cmd) and click to add a column instead. On the keyboard, Shift+Enter on a focused header does the same. Every sorted column keeps its own direction chevron, and once two or more are active each one also shows a small number: 1 is the primary sort, 2 breaks its ties, and so on.
An added column joins at the bottom of that list, so the first column you click keeps deciding the order and each extra click refines it — you build "by department, then by salary within it" in the order you would say it. Click a header without Shift at any point to drop back to sorting by that column alone.
Set the same thing in config with priority — 0 is the primary sort. The
grid below is ordered by department, with salary ordering the rows inside each one:
multiSortMode: 'modifier', // plain click = single, Shift/Ctrl+click = add
initialSorts: [
{ key: 'department', dir: 'asc', priority: 0 }, // primary
{ key: 'salary', dir: 'desc', priority: 1 }, // tie-break inside each department
]
Reading older code? priority is optional, and when no entry has it
the order comes from the array instead — with the last entry as the primary
sort, the opposite of SQL's ORDER BY. A header Shift+click does not follow that
reading: it always adds the column at the lowest priority, so the column you sorted first stays primary.
Both readings work and neither is going away; priority is simply the one that
cannot be misread — including by your server, which receives it on every request.
Try it here and the two-column sort above disappears on your first plain click — that is this mode doing exactly what it promises. The next example is the same grid with the other setting, where no key is needed.
Multi-column sort without a modifier
The same grid with multiSortMode set to click. Click Department, then Salary, then Status — every click adds instead of replacing, so no key is held down.
multiSortMode: 'click' drops the modifier: every plain click adds a
column to the sort instead of replacing it. Click Department, then Salary, then Status, and all
three stay on.
multiSortMode: 'click'
The trade is the other direction: getting back to a single column now takes clicking the others until each cycles through descending and off. Pick this when your readers sort by several columns most of the time; keep the default when a single sort is the common case.
Server vs client mode
The same columns with sortMode set to client. Sorting here reorders the rows already in the browser — no request goes out, and the header responds instantly.
sortMode decides where the work happens, and it is the one sorting option that
changes what your server sees.
-
'server'(default) — a sort click resets the grid and callsfetchRows()with the newsortsarray. Your data source applies it. The other three examples on this page are in this mode. -
'client'— the grid reorders the rows it already holds. NofetchRows()call is made on a sort change, and it passessorts: []so the server never double-sorts. Dot-notationproppaths,valueGetterand a customcomparatorall work here.
Client mode sorts the rows in the browser, not the dataset. This example loads 100 rows at a time so that distinction is visible; with a small page you would be reordering a fraction of the data while the header implies otherwise.
(sortChange) output
The (sortChange) output emits the full SortConfig[] array after every
sort update. Use it to sync sort state to a URL query parameter, send analytics events, or
update a "saved view" indicator.
Mouse & keyboard
| Interaction | Effect |
|---|---|
| Click header | Cycle ascending → descending → unsorted |
| Shift + click header | Add the column to a multi-column sort |
| Click a sorted header again | Reverse its direction. Without Shift this also clears the other sorts; with it, the column moves to the lowest priority |
In sortMode: 'server' every sort click resets the loaded rows and refetches from
offset 0. For large page sizes or slow endpoints, prefer 'client' mode when the
full dataset is already in memory — no network round-trip per click.
Sorting options
| Property | Type | Default | Description |
|---|---|---|---|
| column.sortable | boolean | false | Opt a column into sorting — shows the header sort icon and makes it clickable. |
| config.sortMode | 'server' | 'client' | 'server' | server refetches with params.sorts; client sorts loaded rows in memory with no fetch. |
| config.multiSortMode | 'modifier' | 'click' | 'modifier' | modifier: plain click = single sort, Shift/Ctrl+click adds. click: every plain click accumulates (legacy). |
| config.initialSorts | SortConfig[] | [] | Pre-sort on first load — included in the first fetchRows() call. |
| SortConfig.priority | number | — | Which sort wins: 0 is the primary sort, 1 the first tie-break. Omit it on every entry and the array order decides instead, with the last entry as primary. |
| column.comparator | (a, b, rowA, rowB) => number | — | Custom compare function for client-mode sorting. |
| column.valueGetter | (row) => unknown | — | Derives the sort value in client mode (also used for display and export). |
| (sortChange) | SortConfig[] | — | Output — emits the full sort state after every change. |