Sorting Data

• Overview
• Sorter Functions
  • Built In Sorters
  • Custom Sorters
• Header Sorting
• Initial Sort
• Managing Sorting
• Callbacks

Overview Demo

Tabulator allows you to sort the data in your table in any way you want.

By default Tabulator will attempt to guess which sorter should be applied to a column based on the data contained in the first row. It can determine sorters for strings, numbers, alphanumeric sequences and booleans, anything else will be treated as a string.

To specify a sorter to be used on a column use the sorter property in the columns definition object

You can pass an optional additional property with sorter, sorterParams that should contain an object with additional information for configuring the sorter.

{title:"Birthday", field:"birthday", sorter:"date", sorterParams:{format:"DD/MM/YY"}}

Params Lookup Function

If you want to dynamically generate the sorterParams at the time the sort is called you can pass a function into the property that should return the params object.

//define lookup function
function paramLookup(column, dir){
    //column - the column component for the column being sorted
    //dir - the direction of the sort ("asc" or "desc")

    //do some processing and return the param object
    return {param1:"green"};
}

//column definition
{title:"Birthday", field:"birthday", sorter:"date", sorterParams:paramLookup}

Sorter Functions

Built In Sorters

Tabulator comes with a number of preconfigured sorters including:

• string - sorts column as strings of characters
  • optional sorterParams:
    • locale - the locale code for the string comparison function, (without this the sorter will use the locale of the browser). it can accept:
      • string - the locale code for the sort
      • boolean - set the value to true to use the current table locale
    • alignEmptyValues - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
      • top - force empty cells to the top of the table
      • bottom - force empty cells to the bottom of the table
• number - sorts column as numbers (integer or float, will also handle numbers using "," separators)
  • optional sorterParams:
    • alignEmptyValues - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
      • top - force empty cells to the top of the table
      • bottom - force empty cells to the bottom of the table
• alphanum - sorts column as alpha numeric code
  • optional sorterParams:
    • alignEmptyValues - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
      • top - force empty cells to the top of the table
      • bottom - force empty cells to the bottom of the table
• boolean - sorts column as booleans
• exists - sorts column ordering if value has a type of "undefined" or not
• date - sorts column as dates
  • You will need to include the moment.js library to use this sorter
  • optional sorterParams:
    • format - the format of the date (default: DD/MM/YYYY)
    • alignEmptyValues - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
      • top - force empty cells to the top of the table
      • bottom - force empty cells to the bottom of the table
• time - sorts column as time (formatted as hh:mm)
  • You will need to include the moment.js library to use this sorter
  • optional sorterParams:
    • format - the format of the time (default: hh:mm)
    • alignEmptyValues - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
      • top - force empty cells to the top of the table
      • bottom - force empty cells to the bottom of the table
• datetime - sorts column as datetimes
  • You will need to include the moment.js library to use this sorter
  • optional sorterParams:
    • format - the format of the date (default: DD/MM/YYYY hh:mm:ss)
    • alignEmptyValues - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
      • top - force empty cells to the top of the table
      • bottom - force empty cells to the bottom of the table
• array - sorts arrays of data
  • optional sorterParams:
    • type - Arrays will be sorted by length by default, this property takes a string for the comparison type:
      • length - sort arrays by length
      • sum - sort arrays by sum of their value
      • max - sort arrays by maximum value
      • min - sort arrays by minimum value
      • avg - sort arrays by average value of all elements
    • alignEmptyValues - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
      • top - force empty cells to the top of the table
      • bottom - force empty cells to the bottom of the table

Custom Sorters

for advanced sorting can define a custom sorter function in the sorter option:

{title:"Name", field:"name", sorter:function(a, b, aRow, bRow, column, dir, sorterParams){
        //a, b - the two values being compared
        //aRow, bRow - the row components for the values being compared (useful if you need to access additional fields in the row data for the sort)
        //column - the column component for the column being sorted
        //dir - the direction of the sort ("asc" or "desc")
        //sorterParams - sorterParams object from column definition array

        return a - b; //you must return the difference between the two values
    },
}

The fifth parameter in this callback is a ColumnComponent for the column being sorted.

Header Sorting

By default all columns in a table are sortable by clicking on the column header, if you want to disable this behaviour, set the headerSort property to false in the column definition array:

{title:"Name", field:"name", sorter:"string", headerSort:false} //disable header sorter

You can sort by multiple columns at the same time by holding the ctrl or shift key when you click on the column headers.

Header Sort Direction

By default Tabulator will sort a column in ascending order when a user first clicks on the column header.

The headerSortStartingDir property in the column definition can be used to set the starting sort direction when a user clicks on an unsorted column, it can either be set to asc or desc.

{title:"Name", field:"name", sorter:"string", headerSortStartingDir:"desc"} //start sorting column in descending order when user clicks on header of unsorted column

Initial Sort

When the table is first created it can be defined with an initial set of sorters. These can be set using the initialSort option. This will take the same sorter array as the setSort function. (see Sorter Functions for more details)

var table = new Tabulator("#example-table", {
    initialSort:[
        {column:"age", dir:"asc"}, //sort by this first
        {column:"height", dir:"desc"}, //then sort by this second
    ]
});

Manage Sorting

Trigger Sorting Programmatically

You can trigger sorting using the setSort function

table.setSort("age", "asc");

If you wish to sort by multiple columns then you can pass an array of sorting objects to this function, the data will then be sorted in the order of the objects.

table.setSort([
    {column:"age", dir:"asc"}, //sort by this first
    {column:"height", dir:"desc"}, //then sort by this second
]);

Sorting Order
When using multiple sorters, the order in the array is the order in which the sort functions will be applied to the data. In the example above the data will first be sorted by age, and then the result of that sort will be sorted by height. So the data displayed on screen will be sorted in order of height, with any equal height values being sorted by age. If you find the results of a sort not matching up to your expectations, try reversing the order of your sorters.

Get Current Sorters

If you need to retrieve the details of the currently sorted column at any point you can use the getSorters function.

table.getSorters();

This will return an array of sort objects with three properties, column the column component for the sorted column, field a string of the field name for the sorted column, and dir a string of either "asc" or "desc" indicating the direction of sort.

[
    {
        column:column,
        field:"age",
        dir:"asc"
    },
    {
        column:column,
        field:"height"
        dir:"desc"
    }
]

If the table is not currently sorted then the array will be empty.

Clear All Sorters

To remove all sorting from the table, call the clearSort function.

table.clearSort();

Callbacks

A range of callbacks are available for tracking progress of sorting. See the Sorting Callbacks section for more information.