Sorting
Sortable columns toggled from the header by mouse or keyboard, the sort kept by the grid, the rows ordered in memory or by your server.
The grid keeps which columns are sorted, in which direction and in which order, toggles them from
the header and shows them in ARIA and data-*. It never reorders the rows it is given: with your
rows in memory, one hook orders them; with a server, you send it
the sort.
Install sorting
Sorting is a feature: install sorting(), from the /sorting entry,
on the grid. Without it, no column sorts and the sort props do not compile.
import { sorting } from "@fragiola/data-grid-react/sorting";
const features = [sorting()];
<DataGrid.Root features={features} columns={columns} rows={people}>
{/* … */}
</DataGrid.Root>Sortable columns
A column with sortable: true sorts the grid. A group never does: its columns can.
const columns: Column<Person>[] = [
{ key: "name", name: "Name", width: 180, sortable: true },
{ key: "email", name: "Email", width: 260 },
{ key: "salary", name: "Salary", width: 130, sortable: true },
];The sort
The sort is a list of { columnKey, direction } (SortColumn, from the /sorting entry), the
first column first; direction is "ascending" or "descending", the values of aria-sort.
Like the active cell, it is controlled or not:
sortColumnswithonSortColumnsChange: a change is asked for, and only the prop applies it;defaultSortColumns: the grid starts from it, applies changes and tellsonSortColumnsChange.
In Vue they are attributes (:sort-columns, @sort-columns-change); in Angular,
DataGridSorting's [(sortColumns)], [defaultSortColumns] and (sortColumnsChange).
import { type SortColumn, sorting } from "@fragiola/data-grid-react/sorting";
const features = [sorting()];
// rows in memory: one hook orders the rows by the sort the root's model holds
const local = useLocalRows(people, columns, { features });
<DataGrid.Root features={features} columns={columns} {...local.props}>{/* … */}</DataGrid.Root>
// a server: the app keeps the sort and sends it
const [sortColumns, setSortColumns] = useState<readonly SortColumn[]>([]);
<DataGrid.Root
features={features}
columns={columns}
rows={pageFromServer}
sortColumns={sortColumns}
onSortColumnsChange={setSortColumns}
>
{/* … */}
</DataGrid.Root>A sort naming a column that is not sortable keeps the rest: the grid leaves that entry out and
tells onSortColumnsChange. When the columns change, a sorted column that is gone (or no longer
sortable) leaves the sort the same way.
From the header
A click on a sortable column's header cell, or Enter or Space while it is the active cell (with
navigation() installed: without it no cell is active, and only the
click sorts), toggles it: ascending, descending, not sorted. Alone, the column becomes the only sorted one;
with Ctrl (⌘ on a Mac), it is added last, or cycles in place, and the others stay.
The grid acts after your handlers, as for its keys: preventDefault in an onClick or
onKeyDown on the header cell, on Root or on its render element cancels the toggle. A click
or a key on a control inside the header cell (a button, a link, a menu trigger, a popover) is the
control's, never a sort; neither is a drag across the header's text, nor a held key repeating.
The same changes go through the model, for a toolbar or a menu of your own:
model.run("sort-columns.toggle", { columnKey: "name", multi: true }),
model.run("sort-columns.set", { sortColumns: [] }), reached with
useDataGrid() or a gridRef.
These keys are sorting's, so the model must be typed by the features:
useDataGrid<Person, typeof features>(), useDataGridRef<Person, typeof features>()
(injectDataGrid and createDataGridRef in Angular). model.get("sort-columns") reads the
sort. A middleware can refuse or rewrite them.
What it shows
| on a header cell | when |
|---|---|
data-sortable | its column is sortable |
data-sort | ascending or descending, while its column is sorted |
data-sort-priority | its column's place in the sort, 1-based |
aria-sort | on the first sorted column with a header cell of its own only |
ARIA 1.2 asks for aria-sort on one header at a time, so a sort on several columns announces
its first one; the others are in data-sort. A sorted column with no header cell of its own (a
collapsed group hides it, or a header cell
spans over it) still sorts and keeps its priority: the next
one carries aria-sort. Indicators are yours: draw an arrow from
data-sort in CSS, or from the header cell's state (sortable, sortDirection,
sortPriority) in a render function, as the example does. Without sorting installed, none of
these attributes is there, and those state fields are undefined.
sortColumnsOf(view), from the /sorting entry, reads the whole sort from the grid's view, to
show a priority only while several columns sort:
import { sortColumnsOf } from "@fragiola/data-grid-react/sorting";
const sortColumns = sortColumnsOf(useGridView());
// …
{sortColumns.length > 1 && state.sortPriority !== undefined && <span>{state.sortPriority}</span>}Rows stay yours
The grid shows the rows it is given, in that order: useLocalRows orders them in memory (see
Rows in memory for how values compare, and compare), and a
server orders them for you. The active cell keeps its position when the rows change
order: it stays on the same row index and column, not on the same record.