Documentation
Concepts

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.

Sorting
Gallery

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.

people.tsx
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.

columns.tsx
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:

  • sortColumns with onSortColumnsChange: a change is asked for, and only the prop applies it;
  • defaultSortColumns: the grid starts from it, applies changes and tells onSortColumnsChange.

In Vue they are attributes (:sort-columns, @sort-columns-change); in Angular, DataGridSorting's [(sortColumns)], [defaultSortColumns] and (sortColumnsChange).

people.tsx
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 cellwhen
data-sortableits column is sortable
data-sortascending or descending, while its column is sorted
data-sort-priorityits column's place in the sort, 1-based
aria-sorton 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:

header-cell.tsx
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.