JavaScript Data Grid Rows sorting

JavaScript Data GridRows sorting

Sort data alphabetically or numerically, in ascending, descending or a custom order, by one or multiple columns.

On this page

Overview

With sorting, you can easily rearrange rows of data, based on the values in specific columns. This is particularly useful for analyzing and organizing large data sets, which helps you identify patterns and trends.

You can sort data in different ways:

  • Alphabetically, numerically, or based on a custom sorting logic
  • In ascending, descending, or a custom order
  • By a single column, or by multiple columns
  • Using Handsontable's UI or API

Handsontable sorts data only visually, so your source data remains in the original order. To save your sorting changes in the data source, see this guide: Saving data.

Sorting demo

Click on one of the column names to sort the values in ascending (↑) or descending (↓) order, or to go back to the original order.

    Enable sorting

    To enable sorting for all columns, set columnSorting to true.

    const configurationOptions = {
  // enable sorting for all columns
  columnSorting: true,
};

    To enable sorting only for specific columns, set headerAction to false for those columns that you don't want to sort. In the following example, only columns Model, Date and In stock are sortable.

      Configure sorting

      You can configure the sorting UI, set an initial sort order, and implement your own comparator.

      By default:

      • Sorting is enabled for all columns.
      • The end user can sort data by clicking on the column name.
      • The sort order indicator is visible.
      • At Handsontable's initialization, no rows are sorted.

      You can configure the following options:

      const configurationOptions = {
  columnSorting: {
    // let the end user sort data by clicking on the column name (set by default)
    headerAction: true,
    // don't sort empty cells – move rows that contain empty cells to the bottom (set by default)
    sortEmptyCells: false,
    // enable the sort order icon that appears next to the column name (set by default)
    indicator: true,

    // at initialization, sort data by the first column, in descending order
    initialConfig: {
      column: 1,
      sortOrder: 'desc',
    },

    // implement your own comparator
    compareFunctionFactory(sortOrder, columnMeta) {
      return function (value, nextValue) {
        // here, add a compare function
        // that returns `-1`, or `0`, or `1`
      };
    },
  },
};

      Sort different types of data

      Handsontable sorts different types of data automatically, based on which type you configure for each column.

      You can configure the following types:

        You can also create a custom type. For details, see this guide: Cell type.

        Sort by multiple columns

        You can sort data by more than one column, which lets you apply multiple sets of sort criteria at the same time.

        To try out sorting by multiple columns, see the following demo:

        1. Click on the Brand column name. The data gets sorted by brand.
        2. Hold down Cmd/Ctrl and click on the Model column name.
          The data gets sorted by model, but within each brand.
        3. Hold down Cmd/Ctrl and click on the Price column name.
          The data gets sorted by price, but within each model.

          To enable sorting by multiple columns, set multiColumnSorting to true.

          const configurationOptions = {
  // enable sorting by multiple columns, for all columns
  multiColumnSorting: true,
};

          To select which columns can be sorted at the same time, set headerAction to false for those columns that you don't want to sort.

          const configurationOptions = {
  // enable sorting by multiple columns, for all columns
  multiColumnSorting: true,
  columns: [
    {
      // disable sorting by multiple columns for the first column
      multiColumnSorting: {
        headerAction: false,
      },
    },
};

          The columnSorting and multiColumnSorting options are mutually exclusive; do not enable them together. If you do, columnSorting will be automatically disabled as it is overridden by multiColumnSorting.

          Set an initial sort order

          You can set a default sort order that's applied every time you initialize Handsontable.

          In the following demo, the data is initially sorted:

          • By the Brand column, in ascending order
          • By the Model column, in descending order

            To set an initial sort order, use the initialConfig option.

            const configurationOptions = {
  columnSorting: {
    // at initialization, sort data by the first column, in ascending order
    initialConfig: {
      column: 0,
      sortOrder: 'asc', // for descending order, use `'desc'`
    },
};

            To initially sort data by multiple columns, set initialConfig to an array.

            const configurationOptions = {
  // enable sorting by multiple columns
  multiColumnSorting: {
    initialConfig: [
      // at initialization, sort data by the first column, in ascending order
      {
        column: 0,
        sortOrder: 'asc',
      },
      // at initialization, sort data by the second column, in descending order
      {
        column: 1,
        sortOrder: 'desc',
      },
    ]
};

            Add custom sort icons

            The default sort icons (↑↓) are encoded url. You can replace them by changing -webkit-mask-image for the following pseudo-elements of Handsontable's CSS:

            • .columnSorting.sortAction.ascending::before
            • .columnSorting.sortAction.descending::before

              To replace the icons that indicate sorting by multiple columns (1, 2 etc.), change content for the .columnSorting.sort-1::after and subsequent pseudo-elements:

                Add a custom comparator

                A comparator is a function that determines the sort order, based on specified criteria.

                Adding a custom comparator lets you go beyond Handsontable's built-in sorting features. You can:

                • Apply a custom sort order. For example, instead of sorting data alphabetically or numerically, you can sort it by length or by the occurrence of a specific character.
                • Handle exceptions. For example, in a list of employees, you can exclude workers with a specific job title from sorting.
                • Implement a custom sorting logic based on your own criteria.

                To add a custom comparator, use the compareFunctionFactory option.

                const configurationOptions = {
  columnSorting: {
    compareFunctionFactory: function (sortOrder, columnMeta) {
      // implement your own comparator
      return function (value, nextValue) {
        if (value < nextValue) {
          return -1;
        }
        if (value > nextValue) {
          return 1;
        }

        return 0;
      };
    },
  },
};

                Use sorting hooks

                You can run your code before or after sorting, using the following Handsontable hooks:

                For example, you can use beforeColumnSort() for server-side sorting, or use afterColumnSort() to exclude rows from sorting.

                const configurationOptions = {
  beforeColumnSort() {
    // add your code here
    return false; // to block front-end sorting
  },
  afterColumnSort() {
    // add your code here
  },
};

                Exclude rows from sorting

                You can exclude any number of top or bottom rows from sorting.

                For example, if you freeze a row at the top (to display column names), and freeze a row at the bottom (to display column summaries), you can prevent those frozen rows from getting sorted, so they always stay in place.

                  Control sorting programmatically

                  You can control sorting at the grid's runtime by using Handsontable's hooks and API methods.

                  This allows you to:

                  • Enable or disable sorting depending on specified conditions. For example, you can disable sorting for very large data sets.
                  • Trigger sorting depending on the state of another component in your application. For example, you can let the end user sort data by clicking on buttons outside of the grid.

                  Enable or disable sorting programmatically

                  To enable or disable sorting programmatically, use the updateSettings() method.

                  // enable sorting for all columns
handsontableInstance.updateSettings({
  columnSorting: true,
});

// disable sorting for all columns
handsontableInstance.updateSettings({
  columnSorting: false,
});

                  You can also enable or disable sorting for specific columns.

                  handsontableInstance.updateSettings({
  columns: [
    {
      // enable sorting for the first column
      columnSorting: {
        headerAction: true,
      },
    },
    {
      // disable sorting for the second column
      columnSorting: {
        headerAction: false,
      },
    },
  ],
});

                  Sort data programmatically

                  To sort data programmatically, use the columnSorting.sort() method. Remember to enable sorting first.

                  Mind that calling columnSorting.sort() overwrites any previous sort orders.

                  const configurationOptions = {
  // enable sorting for all columns
  columnSorting: true,
};

const columnSorting = handsontableInstance.getPlugin('columnSorting');

columnSorting.sort(
  // sort data by the first column, in ascending order
  {
    column: 0,
    sortOrder: 'asc', // for descending order, use `'desc'`
  }
);

// go back to the original order
columnSorting.clearSort();

                  To see how it works, try out the following demo:

                    Sort data programmatically by multiple columns

                    To sort data programmatically by multiple columns, use the multiColumnSorting.sort() method. Remember to enable sorting by multiple columns first.

                    Mind that calling multiColumnSorting.sort() overwrites any previous sort orders.

                    const configurationOptions = {
  // enable sorting by multiple columns, for all columns
  multiColumnSorting: true,
};

// get the `MultiColumnSorting` plugin
const multiColumnSorting = handsontableInstance.getPlugin('multiColumnSorting');

multiColumnSorting.sort([
  // sort data by the first column, in ascending order
  {
    column: 0,
    sortOrder: 'asc',
  },
  // within the above sort criteria,
  // sort data by the second column, in descending order
  {
    column: 1,
    sortOrder: 'desc',
  },
]);

// go back to the original order
multiColumnSorting.clearSort();

                    To see how it works, try out the following demo:

                      Import the sorting module

                      You can reduce the size of your bundle by importing and registering only the modules that you need.

                      To use sorting, you need only the following modules:

                      // import the base module
import Handsontable from 'handsontable/base';

// import Handsontable's CSS
import 'handsontable/styles/handsontable.css';
import 'handsontable/styles/ht-theme-main.css';

// import the ColumnSorting plugin (or the MultiColumnSorting plugin)
import { registerPlugin, ColumnSorting } from 'handsontable/plugins';

// register the ColumnSorting (or MultiColumnSorting plugin)
registerPlugin(ColumnSorting);
                      Windows macOS Action Excel Sheets
                      Enter Enter Sort data by the selected column, in ascending, descending, or the original order ✗ ✗
                      Ctrl+Enter Cmd+Enter Sort data by multiple columns, in ascending, descending, or the original order. Requires the MultiColumnSorting plugin. ✗ ✗

                      API reference

                      For the list of options, methods, and Handsontable hooks related to sorting, see the following API reference pages:

                      Troubleshooting

                      Didn't find what you need? Try this: