Sorting

The Sorting plugin provides single and multi-column sorting through header click interactions. It manages the sort model state and cycles through configurable sort directions (ascending, descending, unsorted).

Installation

npm install @gridstorm/plugin-sorting

Setup

import { createGrid } from '@gridstorm/core';
import { SortingPlugin } from '@gridstorm/plugin-sorting';

const grid = createGrid({
  columns: [
    { colId: 'name', field: 'name', headerName: 'Name', sortable: true },
    { colId: 'age', field: 'age', headerName: 'Age', sortable: true },
    { colId: 'email', field: 'email', headerName: 'Email', sortable: true },
  ],
  rowData: [],
  plugins: [
    SortingPlugin({
      multiSort: true,
      maxSortColumns: 3,
      sortCycle: ['asc', 'desc', null],
      autoApply: true,
    }),
  ],
});

:::example{title="Live Sorting Demo" href="/cookbook/#sorting-basic"} Try sorting with single and multi-column configurations. Click column headers to sort ascending, descending, or unsorted. :::

Plugin Options

Name Type Default Description
multiSort boolean true Allow multiple columns to be sorted simultaneously.
maxSortColumns number Infinity Maximum number of columns allowed in multi-sort.
sortCycle SortDirection[] ['asc', 'desc', null] Sort cycle order. Each click advances to the next direction. null removes the sort.
autoApply boolean true Trigger row reprocessing after a sort change.

Usage Examples

Single-Column Sort

Toggle sorting on a column by dispatching the sort:toggle command. When multiSort is disabled or the user clicks without holding a modifier key, only one column is sorted at a time.

// Sort by the "name" column
grid.commandBus.dispatch('sort:toggle', { colId: 'name' });

// Clicking again cycles to the next direction (desc)
grid.commandBus.dispatch('sort:toggle', { colId: 'name' });

// A third click removes the sort (null in the cycle)
grid.commandBus.dispatch('sort:toggle', { colId: 'name' });

Multi-Column Sort

Pass multiSort: true in the payload to add a column to the existing sort model without replacing it. This mirrors the behavior of holding Shift and clicking a header.

// Sort by name first
grid.commandBus.dispatch('sort:toggle', { colId: 'name' });

// Then add age as a secondary sort
grid.commandBus.dispatch('sort:toggle', { colId: 'age', multiSort: true });

When maxSortColumns is reached, the oldest sort entry is removed to make room for the new one.

Clear All Sorting

grid.commandBus.dispatch('sort:clear', {});

Commands

Name Payload Description
sort:toggle { colId: string; multiSort?: boolean } Toggle the sort direction on a column. Pass multiSort: true to add to the existing sort model instead of replacing it. Only sorts columns with sortable: true.
sort:clear {} Remove all sort entries and revert to the original row order.

Events

Name Payload Description
column:sort:changed { sortModel: SortModelItem[] } Emitted by the core API after the sort model is updated via api.setSortModel().

React Integration

import { GridStorm, useGridApi } from '@gridstorm/react';
import { SortingPlugin } from '@gridstorm/plugin-sorting';

function SortableGrid({ rowData, columns }) {
  const apiRef = useGridApi();

  const clearSort = () => {
    apiRef.current?.commandBus.dispatch('sort:clear', {});
  };

  return (
    <>
      <button onClick={clearSort}>Clear Sort</button>
      <GridStorm
        rowData={rowData}
        columns={columns}
        plugins={[SortingPlugin({ multiSort: true, maxSortColumns: 3 })]}
      />
    </>
  );
}

Next Steps