Sorting

The comparator and sort transforms underneath sortableColumns.

Last updated November 3, 2026

sortRows and toggleColumnSort are the functions a grid sorts with — the first orders rows by a ColumnSortState, the second works out the state a header click leads to. The view pipeline and the controller call them for you; reach for them directly to sort rows outside a grid, or in a custom adapter.

A ColumnSortState is readonly ColumnSortEntry[], each entry { columnId, direction } with direction a SortDirection — "asc" or "desc" — in priority order: the first entry sorts, the second breaks its ties, and so on.

Functions#

Function	Type	Description
`sortRows(rows, sort, columns)`	`readonly ResolvedRow<Row>[]`	`rows` ordered by `sort`, each entry read against `columns` for its field and type, with `rowIndex` renumbered. Stable; a blank value sorts last in either direction. Returns `rows` itself for an empty sort, or one naming only absent columns.
`compareValues(a, b, type?)`	`number`	Compares two cell values as `type` says — numerically for the numeric types, chronologically for the date and time types, `false` before `true`, and as text otherwise or with no type. `null` and `undefined` sort after every value.
`toggleColumnSort(sort, columnId, options)`	`ColumnSortState`	`columnId` cycled to its next direction, none → ascending → descending → none. `{ stack: false }`, a plain click, sorts by that column alone; `{ stack: true }`, a `Shift`+click, cycles it in place and leaves the rest.
`sortDirectionFor(sort, columnId)`	`SortDirection \| null`	This column's direction in `sort`, or `null` when it does not sort.
`sortPriorityFor(sort, columnId)`	`number \| null`	This column's 1-based place in `sort`, or `null` when it does not sort — what a header's priority badge shows.

compareValues is also what grouping orders its group values with, what min and max aggregates compare by, and how a filter checklist orders its values.

import { sortRows, toggleColumnSort } from "@gridkitjs/core";

let sort = toggleColumnSort([], "Region", { stack: false }); // Region ascending
sort = toggleColumnSort(sort, "Amount", { stack: true }); // then Amount ascending

const sorted = sortRows(rows, sort, dataColumns);

rows are ResolvedRows and columns the width-free DataColumns resolveDataColumns returns — the shapes the view pipeline passes between its stages.

In the React grid#

sortableColumns turns the header's sort toggle on — see column sorting.

Edit this page on GitHub