# Row sorting
Sorting is a feature you opt into. Try it live - click any column
header to cycle `none → asc → desc → none`; shift-click adds the
column to the sort key list (multi-sort):
> Live demo: Sort, filter, paginate - https://svgrid.com/demos/02-sort-filter-paginate/
The examples on this page run against these rows:
```svelte
```
```svelte
```
Clicking a sortable header toggles `none → asc → desc → none`. Shift-click
adds the column to the sort key list (multi-sort).
## Sort functions
`sortFns` exposes the built-in comparators:
```ts
import { sortFns } from '@svgrid/grid'
// sortFns.auto - blanks, then numbers numerically, then text (default for unknown types)
// sortFns.number - numeric; blanks and non-numeric values ('n/a') first
// sortFns.date - Date-parsed; blanks and invalid dates first
```
All three sort blanks (`null`, `undefined`, `''`) first ascending and last
descending, and never return `NaN`, so a column with placeholder text still
sorts into a consistent order.
The grid picks the comparator based on the column's `editorType`:
| editorType | comparator |
| ---------- | ---------- |
| `'number'` | `sortFns.number` |
| `'date'` \| `'datetime'` | `sortFns.date` |
| anything else | `sortFns.auto` |
If your column has a non-trivial type, set `editorType` even if you do not
want inline editing - it is what tells sort and filter how to behave.
### Sort by a rank
A status column sorted as text puts "Done" before "To do". `sortValue` gives
the number to sort a value by instead, and grouped rows follow it too:
```ts
const STATUS = ['To do', 'In progress', 'Done']
const columns = [
{ field: 'status', header: 'Status', sortValue: (v: unknown) => STATUS.indexOf(String(v)) },
]
```
Blanks, and anything that is not a number, sort first ascending, as in a
number column.
### Your own comparator
`sortComparator` compares two of a column's values in place of the built-in
order. It also gets the direction being sorted, `desc`. The grid reverses your
result for a descending sort, so return the ascending order; `desc` is there
for a value you want held at one end both ways. `sortValue` wins when a column
sets both.
```ts
const columns = [
{ field: 'code', header: 'Code', sortComparator: (a, b) => String(a).length - String(b).length },
]
```
### Keep blanks at one end (Enterprise)
`@svgrid/enterprise` ships comparators that hold blank cells at the bottom or
the top in both directions, so tasks with no due date stay below the dated
ones whichever way Due runs. The other values sort as the grid sorts them
([setup](https://github.com/sv-grid/sv-grid/blob/main/docs/enterprise/README.md#grid-filter-and-sort-additions)):
```ts
// blanksLast is exported by @svgrid/enterprise
const columns = [
{ field: 'due', header: 'Due', cellDataType: 'dateString', sortComparator: blanksLast('date') },
]
```
`blanksFirst` holds them at the top. Pass `'number'`, `'date'` or `'auto'`
(the default) for how the other values compare.
## Programmatic sort
```ts
api.setSort('age', 'desc') // sort by age descending
api.setSort('age', null) // clear sort on this column
api.clearSort() // clear all sort
```
`setSort` replaces any existing sort with a single clause. For
multi-column sort, the user clicks the second column header with
**Shift** held (the in-grid affordance). A multi-sort setter on the API
is tracked in [Missing features](https://svgrid.com/docs/help/missing-features/).
To observe sort changes from outside the grid:
```svelte
(sorting = next)}
/>
```
## Disable sort per column
Not yet first-class - there is no `enableSorting: false` field. To
prevent a column from being sortable, omit `rowSortingFeature` from
`tableFeatures(...)`, or render a custom header via `header: () =>
renderSnippet(...)` that doesn't bind to the sort button.
## Sorting + server-side data
When sort happens on the backend, pair `externalSort={true}` with
`onSortingChange` and round-trip the sort clauses through your
fetcher. See the [`09-server-side` demo](https://svgrid.com/demos/09-server-side/).
## Multi-column sort
Shift-click a second header and the sort becomes ordered: department first,
then salary within it. The order you click is the order applied, which is why
the header shows a position number once more than one is active.
```svelte
```
## Reading the sort model
`onSortingChange` reports the model as an ordered array, which is exactly the
shape you persist to a URL or hand to a server.
```svelte
(model = JSON.stringify(s))}
/>
Sort model: {model}
```
## See also
- [Filter API](https://svgrid.com/docs/help/filtering/filter-api/)
- [Server-side guide](https://svgrid.com/docs/getting-started/#11-server-side-data)
---
SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/rows/row-sorting/ . All docs: https://svgrid.com/llms.txt