# Single and multiple sorting

Sorting changes display order without modifying data values. Single sorting uses one criterion; multiple sorting uses prioritized criteria.

Canonical: https://grid.syidax.com/docs/features/sorting/

<a id="understand"></a>

## How it works and when to use it

Numbers stored as strings may sort differently from numeric expectations. Handle display formatting in a formatter and prepare sorting for the actual data type.

In the code, grid is the Grid element prepared in the installation chapter. Check each example's data and settings, and implement the app functions and server endpoints for your project.

- [Installation and integration · Shared sample data](https://grid.syidax.com/docs/guides/getting-started.md)

<a id="example-1"></a>

## Example 1. Show the largest quantities first

Explicitly apply descending sorting to the quantity column.

```javascript
await grid.sortBy('quantity', 'desc');
console.log(await grid.getSortModel());
```

Verify the result: A descending quantity model is applied. Distinguish cycling without direction from explicitly setting desc.

<a id="example-2"></a>

## Example 2. Compare quantities within teams

Sort by team first, then compare quantities within each team.

```javascript
grid.multiSort = true;
await grid.setSortModel([{ field: 'team', direction: 'asc' }, { field: 'quantity', direction: 'desc' }]);
```

Verify the result: The first array entry has priority. Source row IDs and values remain unchanged; only display positions change.

<a id="example-3"></a>

## Example 3. Clear sorting and observe user changes

Return to the original order, then read the model when users click headers.

```javascript
await grid.setSortModel([]);
grid.addEventListener('sortChanged', event => console.log(event.detail));
```

Verify the result: An empty model clears sorting. To remove one of several criteria, distinguish sortBy with null from replacing the entire model.

<a id="pitfalls"></a>

## Combining features and troubleshooting

With remote models, the server must apply the same sorting rules. Browser-only sorting within each page can produce inconsistent ordering between pages.

For stable results when values are equal, manage source ordering or a server secondary key. Do not store business targets as rowIndex after sorting.

<a id="related-api"></a>

## APIs used by this feature

- [multiSort](https://grid.syidax.com/docs/options/multiSort.md) — Enables sorting by multiple columns. The sort model order defines priority.
- [enableMultiSort](https://grid.syidax.com/docs/options/enableMultiSort.md) — Compatibility alias for multiple sorting. Keep it consistent with multiSort.
- [sortable](https://grid.syidax.com/docs/columns/sortable.md) — Determines whether users can sort this column.
- [sort](https://grid.syidax.com/docs/columns/sort.md) — Initial ascending/descending sort or cleared sort for this column.
- [sortIndex](https://grid.syidax.com/docs/columns/sortIndex.md) — This column's priority among multiple initial sort criteria.
- [comparator](https://grid.syidax.com/docs/columns/comparator.md) — Compares two values and rows for sorting. Negative, zero, and positive results mean before, equal, and after.
- [sortBy](https://grid.syidax.com/docs/methods/sortBy.md) — Sets one column's sorting. Omitted direction cycles sorting; null clears that column. Use setSortModel for the full multi-column model.
- [setSortModel](https://grid.syidax.com/docs/methods/setSortModel.md) — Replaces sort criteria and priorities together. An empty array clears all sorting.
- [getSortModel](https://grid.syidax.com/docs/methods/getSortModel.md) — Reads current sort columns, directions, and priorities.
- [sortChanged](https://grid.syidax.com/docs/events/sortChanged.md) — Emitted when sorting changes. Reflect the current model in app query conditions or saved view state.

<a id="next"></a>

## Related reading

- [How rows, columns, and IDs relate](https://grid.syidax.com/docs/guides/concepts.md)
- [Connect results and events](https://grid.syidax.com/docs/guides/data-event-access.md)
- [Explore in Features](https://grid.syidax.com/grid/sorting) — The guide describes which interactions are available to try.