Multi-Sort Plugin

The Multi-Sort plugin enables sorting by multiple columns at once—hold Shift and click additional column headers to build up a sort stack. Priority badges show the sort order, so users always know which column takes precedence.

Installation

import '@toolbox-web/grid/features/multi-sort';

Basic Usage

Mark columns as sortable: true and enable the feature. Users Shift+click to add columns to the sort stack, and regular click to reset to single-column sort.

Vanilla JS

import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name', sortable: true },
    { field: 'department', header: 'Department', sortable: true },
    { field: 'salary', header: 'Salary', type: 'number', sortable: true },
    { field: 'startDate', header: 'Start Date', type: 'date', sortable: true },
  ],
  features: {
    multiSort: {
      maxSortColumns: 3,
      showSortIndex: true,
    },
  },
};

// Listen for sort changes
grid.on('sort-change', ({ sortModel }) => {
  console.log('Active sorts:', sortModel);
});

React

import '@toolbox-web/grid-react/features/multi-sort';
import { DataGrid, useGrid, useGridEvent } from '@toolbox-web/grid-react';

function SortableGrid({ data }) {
  const { ref } = useGrid();

  useGridEvent(ref, 'sort-change', (e) => {
    console.log('Sort changed:', e.detail.sortModel);
  });

  return (
    <DataGrid
      ref={ref}
      rows={data}
      columns={[
        { field: 'name', header: 'Name', sortable: true },
        { field: 'department', header: 'Department', sortable: true },
        { field: 'salary', header: 'Salary', type: 'number', sortable: true },
      ]}
      multiSort={{ maxSortColumns: 3 }}
    />
  );
}

Vue

<script setup>
import '@toolbox-web/grid-vue/features/multi-sort';
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';

const data = [
  { name: 'Alice', department: 'Engineering', salary: 95000 },
  { name: 'Bob', department: 'Marketing', salary: 75000 },
];

const onSortChange = (e) => {
  console.log('Sort changed:', e.detail.sortModel);
};
</script>

<template>
  <TbwGrid
    :rows="data"
    :multi-sort="{ maxSortColumns: 3 }"
    @sort-change="onSortChange"
  >
    <TbwGridColumn field="name" header="Name" sortable />
    <TbwGridColumn field="department" header="Department" sortable />
    <TbwGridColumn field="salary" header="Salary" type="number" sortable />
  </TbwGrid>
</template>

Angular

// Feature import - enables the [multiSort] input
import '@toolbox-web/grid-angular/features/multi-sort';

import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { ColumnConfig } from '@toolbox-web/grid';

@Component({
  selector: 'app-sortable-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="rows"
      [columns]="columns"
      [multiSort]="{ maxSortColumns: 3 }"
      (sort-change)="onSortChange($event)"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class SortableGridComponent {
  rows = [
    { name: 'Alice', department: 'Engineering', salary: 95000 },
    { name: 'Bob', department: 'Marketing', salary: 75000 },
  ];

  columns: ColumnConfig[] = [
    { field: 'name', header: 'Name', sortable: true },
    { field: 'department', header: 'Department', sortable: true },
    { field: 'salary', header: 'Salary', type: 'number', sortable: true },
  ];

  onSortChange(e: CustomEvent) {
    console.log('Sort changed:', e.detail.sortModel);
  }
}

Demo

Use the controls to explore different multi-sort configurations: adjust the maximum number of sort levels, toggle priority badges, or apply an initial sort.

SORT

Max sort columns Maximum number of sort levels

3

Show sort index Display sort priority number on headers

Apply initial sort Pre-sort by Department ↑ then Salary ↓

Show source

Hold Shift and click column headers to add columns to the sort stack. Set Max sort columns to 1 for single-column-only sorting.

Configuration Options

See MultiSortConfig for the full list of options and their defaults.

Initial Sort

Use setSortModel() to set a pre-configured sort order after the grid initializes:

const plugin = grid.getPluginByName('multiSort');
plugin.setSortModel([
  { field: 'department', direction: 'asc' },
  { field: 'salary', direction: 'desc' },
]);

Events

Hold Shift and click column headers to add sort levels.

Event Log: Clear

The grid fires a sort-change event whenever the sort model changes:

grid.on('sort-change', ({ sortModel }) => {
  console.log('Sort model:', sortModel);
  // [{ field: 'name', direction: 'asc' }, { field: 'salary', direction: 'desc' }]
});

Programmatic API

See MultiSortPlugin for the full list of methods.

const plugin = grid.getPluginByName('multiSort');

plugin.setSortModel([{ field: 'department', direction: 'asc' }]);
plugin.getSortModel();               // SortModel[]
plugin.clearSort();
plugin.getSortDirection('salary');    // 'asc' | 'desc' | undefined
plugin.getSortIndex('salary');        // number | undefined

Keyboard Shortcuts

Shortcut	Action
Click header	Sort by column (clears other sorts)
Shift + Click	Add column to multi-sort

Styling

The grid uses Light DOM, so standard CSS selectors work for styling sort indicators:

/* Sort indicator icon */
tbw-grid .sort-indicator {
  margin-left: 4px;
}

/* Sort priority badge */
tbw-grid .sort-index {
  background: var(--tbw-multi-sort-badge-bg, var(--tbw-color-panel-bg));
  color: var(--tbw-multi-sort-badge-color, var(--tbw-color-fg));
  width: var(--tbw-multi-sort-badge-size, 1em);
  height: var(--tbw-multi-sort-badge-size, 1em);
}

Row Insertion with Active Sort

When multi-sort is active, assigning rows automatically re-sorts the data — so a newly inserted row will jump to its sorted position. If you want the row to stay exactly where you placed it (e.g., after a user clicks “Add Row”), use insertRow():

grid.insertRow(3, newRow); // stays at visible index 3, auto-animates

The row is also added to source data, so the next full grid.rows = freshData assignment re-sorts normally. See the API Reference → Insert & Remove Rows for full details.

Tip

Do not use insertRow() for data refreshes (API responses, WebSocket updates). In those cases just set grid.rows = newData and let multi-sort re-apply.

See Also

• Filtering — Filter rows by column values
• Plugins Overview — Plugin compatibility and combinations