/ S

This page covers a next version of Handsontable, and is not published yet.

This page covers a non-latest version of Handsontable.

# Row sorting

Table of contents

# Overview

The column sorting plugin works as a proxy between the datasource and the Handsontable rendering module. It can:

  • Map indices of displayed rows visual indices to the indices of corresponding rows in the datasource physical indices and vice versa
  • Alter the order of rows presented to a user without changing the datasource’s internal structure

The sort operation is performed using a stable sort algorithm (opens new window) regardless of the browser you use or the size of the data set which you sort.

TIP

The columnSorting and multiColumnSorting plugins shouldn't be enabled simultaneously.

# Basic plugin configuration

The simplest way to enable the plugin is to set the columnSorting key to true. You will then be able to use the API methods and click on the header to sort, as shown in the example below:

By default:

  • No column will be sorted initially
  • A sorting indicator will be enabled
  • Empty cells won't be sorted
  • The sort method will use default compare functions - read more about them here

    # Extended plugin configuration

    Plugin options can be customized by providing a configuration as an object.

    Here is the list of possible options to set:

    • initialConfig (Object) determines the initial sort status for some column. It contains the following keys:
      • column (Number) determines the visual index of the sorted column
      • sortOrder (String) determines the order that the column will be sorted in - possible values: 'asc' and 'desc'
    • indicator (Boolean) defines whether the sorting order indicator is displayed - an arrow icon in the column header specifying the sorting order
    • sortEmptyCells (Boolean) defines whether empty cells should take part in the sorting process
    • headerAction (Boolean) defines whether clicking the header should sort the table
    • compareFunctionFactory (Function) defines the compare function factory - described in more detail in this section

    See the example plugin configuration below:

      TIP

      Options defined by the columnSorting key in the main Handsontable settings apply to the entire table. Most of them can also be set for a particular column, as described in this section.

      # Default compare functions - sorting different kinds of data

      As in the native Array.sort (opens new window) method, our internal sorting algorithm uses the compare function - also known as a comparator. Different kinds of cells like date, numeric, text are treated differently. Each of them has its own comparator for sorting a particular data type.

      As a result, you can see that different types of data are sorted properly. Handsontable simply needs the declared data type for the column, as shown in the example below.

        # Custom compare functions

        You can pass in your own custom compare function to the sorting algorithm. This function should look the same as an argument in the native Array.sort (opens new window) method - read the description here (opens new window). It is handled by the plugin when compareFunctionFactory is defined in the configuration. The compare function factory must be placed under this key. The factory takes the parameters sortOrder and columnMeta and returns the compare function.

        The example below shows how the custom compare function factory should look:

        function compareFunctionFactory(sortOrder, columnMeta) {
  return function comparator(value, nextValue) {
    // Some value comparisons which will return -1, 0 or 1...
  };
};

        The next section details how the plugin may be used just for certain columns.

        # Plugin options for certain columns only

        The plugin's options, such as compareFunctionFactory, sortEmptyCells, headerAction, indicator, can be set just for a particular column. This can be done by using columns option. The example below demonstrates how to disable the indicator and completely block sorting action for the first column:

          # Custom sort implementation

          The plugin exposes the setSortConfig method. Use this to set the internal sort state.

          TIP

          The data set won't be sorted just by using this method. The isSorted and getSortConfig methods will return results corresponding to the previously set configuration.

          To use a custom sort implementation, you need to:

          • Provide a callback for the beforeColumnSort hook, which will return false
          • Sort data by yourself - for example, on the server-side
          • Set the internal state of the sort by using the setSortConfig method

          The code snippet below provides an example of a custom sort implementation:

          beforeColumnSort(currentSortConfig, destinationSortConfigs) {
  const columnSortPlugin = this.getPlugin('columnSorting');

  columnSortPlugin.setSortConfig(destinationSortConfigs);

  // const newData = ... // Calculated data set, ie. from an AJAX call.

  // this.loadData(newData); // Load a new data set.

  return false; // The blockade for the default sort action.
}

          # Plugin hooks

          The plugin provides two hooks:

          • beforeColumnSort runs before the sort
            • The sort configuration obtained by the getSortConfig method within the callback will match the sort configuration preserved before the hook call
            • The callback for beforeColumnSort will return false and stop the table from being sorted, which results in the afterColumnSort hook not being called
          • afterColumnSort always runs after sorting unless the callback for beforeColumnSort hook returns false

          TIP

          Hooks are also run when you use the clearSort method or provide a configuration that won't be processed, causing validation to fail.

          # Plugin API

          List of methods exposed by the plugin:

          ← Row trimming →