Grouping Data

• Overview
• Setup
  • Grouping by Field
  • Group Headers
  • Opening State
  • Toggle Element
• Multi Level Grouping
• Force Group Field Values
• Group Management
• Movable Rows
• Callbacks

Overview Demo

You can group rows together that share a column value, this creates a visible header for each group and allows the user to collapse groups that they don't want to see.

<div id="example-table"></div>

var table = new Tabulator("#example-table", {
    height:"311px",
    layout:"fitColumns",
    movableRows:true,
    groupBy:"gender",
    columns:[
        {title:"Name", field:"name", width:200},
        {title:"Progress", field:"progress", formatter:"progress", sorter:"number"},
        {title:"Gender", field:"gender"},
        {title:"Rating", field:"rating", formatter:"star", hozAlign:"center", width:100},
        {title:"Favourite Color", field:"col"},
        {title:"Date Of Birth", field:"dob", hozAlign:"center", sorter:"date"},
        {title:"Driver", field:"car", hozAlign:"center", formatter:"tickCross"},
    ],
});

Setup

Grouping by Field

Rows can be grouped by a common field value by setting the groupBy option to the name of the field to be grouped.

groupBy:"gender",

If you need to group by more complex value, you can pass a function that returns a string that represents the group.

groupBy:function(data){
    //data - the data object for the row being grouped

    return data.gender + " - " + data.age; //groups by data and age
}

Custom Group Headers

You can set the contents of the group headers with the groupHeader option.

groupHeader:function(value, count, data, group){
    //value - the value all members of this group share
    //count - the number of rows in this group
    //data - an array of all the row data objects in this group
    //group - the group component for the group

    return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
},

The groupHeader function should either return a DOM node, a text string or an HTML string

Printing Group Headers

When printing you may want to apply a different group header from the one usualy used in the table. You can now do this using the groupHeaderPrint table option, which takes the same inputs as the standard groupHeader property.

var table = new Tabulator("#example-table", {
    groupHeader: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
    },
    groupHeaderPrint: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'></span>";
    },
});

Passing a value of false into groupHeaderPrint will cause the header to show the groups key as plain text

Clipboard Group Headers

When copying to clipboard you may want to apply a different group header from the one usualy used in the table. You can now do this using the groupHeaderClipboard table option, which takes the same inputs as the standard groupHeader property.

var table = new Tabulator("#example-table", {
    groupHeader: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
    },
    groupHeaderClipboard: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'></span>";
    },
});

Passing a value of false into groupHeaderClipboard will cause the header to show the groups key as plain text

Download Group Headers

When downloading you may want to apply a different group header from the one usualy used in the table. You can now do this using the groupHeaderDownload table option, which takes the same inputs as the standard groupHeader property.

var table = new Tabulator("#example-table", {
    groupHeader: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
    },
    groupHeaderDownload: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'></span>";
    },
});

Passing a value of false into groupHeaderDownload will cause the header to show the groups key as plain text

HTML Output Group Headers

When the getHtml function is called you may want to apply a different group header from the one usualy used in the table. You can now do this using the groupHeaderHtmlOutput table option, which takes the same inputs as the standard groupHeader property.

var table = new Tabulator("#example-table", {
    groupHeader: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
    },
    groupHeaderHtmlOutput: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'></span>";
    },
});

Passing a value of false into groupHeaderHtmlOutput will cause the header to show the groups key as plain text

Group Open State

You can set the default open state of groups using the groupStartOpen property.

groupStartOpen:true,

This can take one of three possible values:

• true - all groups start open (default value)
• false - all groups start closed
• function() - a callback to decide if a group should start open or closed

Group Open Function

If you want to decide on a group by group basis which should start open or closed then you can pass a function to the groupStartOpen property. This should return true if the group should start open or false if the group should start closed.

groupStartOpen:function(value, count, data, group){
    //value - the value all members of this group share
    //count - the number of rows in this group
    //data - an array of all the row data objects in this group
    //group - the group component for the group

    return count > 3; //all groups with more than three rows start open, any with three or less start closed
},

Group Toggle Element

By default Tabulator allows users to toggle a group open or closed by clicking on the arrow icon in the left of the group header. If you would prefer a different behaviour you can use the groupToggleElement option to choose a different option:

var table = new Tabulator("#example-table", {
   groupToggleElement:"header", //toggle group on click anywhere in the group header
});

The option can take one of three values:

• arrow - togggle group on arrow element click
• header - toggle group on click anywhere on the group header element
• false - prevent clicking anywhere in the group toggling the group

Multi Level Grouping

To set multiple levels of grouping, pass an array to the groupBy option. Each item in the array will be a sub-group of the previous item.

groupBy:["gender", "color"], //group by gender then favourite color

To then set the default open state of each of these levels you can pass an array to the groupStartOpen option.

groupStartOpen:[true, false], //start with gender groups open and color sub groups closed

You can also set a different header for each level of group, as above you pass an array to the groupHeader option.

groupHeader:[
    function(value, count, data){ //generate header contents for gender groups
        return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
    },
    function(value, count, data){ //generate header contents for color groups
        return value + "<span style='color:#0dd; margin-left:10px;'>(" + count + " item)</span>";
    },
],

Sub Group Styling

Each group header element is assigned a class based on its level in the grouping list. This allows you to differentiate between different gouping levels by styling their classes. By default each level's headers are indented more than the last.

For example, all group headers in the first grouping level will be assigned the class tabulator-group-level-1

Note: You can have as many levels of subgroup as you like, but Tabulator only comes with indent styling built in for the first five levels of subgroup.

Force Group Field Values

By default Tabulator will create groups for rows based on the values contained in the row data. if you want to explicitly define which field values groups should be created for at each level, you can use the groupValues option.

This option takes an array of value arrays, each item in the first array should be a list of acceptable field values for groups at that level

var table = new Tabulator("#example-table", {
    groupBy:["color", "age"],
    groupValues:[
        ["red", "blue", "green"], //create groups for color values of "red", "blue", and "green",
        [10, 20, 30], //create sub groups for ages of 10, 20 and 30
    ],
});

Rows with values not in the arrays will not be show in the table. In this mode empty groups will remain visible in the table.

If you want to only specify groups for some of the levels, you can pass a value of false into the levels where you want Tabulator to decide on the grouping.

var table = new Tabulator("#example-table", {
    groupBy:["color", "age"],
    groupValues:[
        false, //createany groups needed for the colors field
        [10, 20, 30], //create sub groups for ages of 10, 20 and 30
   ],
});

Group Management

If you want to alter the structure of the groups after the table has been created there are a number of functions available.

Change the GroupBy Fields

You can use the setGroupBy function to change the fields that rows are grouped by. This function has one argument and takes the same values as passed to the groupBy setup option.

table.setGroupBy("gender");

You can clear existing grouping by calling this function with a value of false

table.setGroupBy(false); //clear current grouping

Change Allowed Group Values

You can use the setGroupValues function to change the list of allowed values that rows are grouped by. This function has one argument and takes the same values as passed to the groupValues setup option.

table.setGroupValues([["male", "female", "smizmar"]]);

Change the Start Open States

You can use the setGroupStartOpen function to change the default open state of groups. This function has one argument and takes the same values as passed to the groupStartOpen setup option.

table.setGroupStartOpen(true);

Change the Header Formatter

You can use the setGroupHeader function to change the header generation function for each group. This function has one argument and takes the same values as passed to the groupHeader setup option.

table.setGroupHeader(function(value, count, data, group){
    //value - the value all members of this group share
    //count - the number of rows in this group
    //data - an array of all the row data objects in this group
    //group - the group component for the group

    return value + " (" + count + " items)" ; //return the header contents
});

Note: If you use the setGroupStartOpen or setGroupHeader before you have set any groups on the table, the table will not update until the setGroupBy function is called.

Get Group Components

You can use the getGroups function to retrieve an array of all the first level Group Components in the table.

var groups = table.getGroups();

Movable Rows and Grouping

If you move a row between groups, its values will be updated to match those of the new group.

If you move or delete the last row in a group out of that group, that group will be removed.

Change Row Group On Cell Edit

Enabling the groupUpdateOnCellEdit option will cause a row to be regrouped when the cell it is grouped by is edited.

var table = new Tabulator("#example-table", {
    groupUpdateOnCellEdit:true, //regroup a row when its groubBy cell is edited
});

Callbacks

A range of callbacks are available for grouping. See the Group Callbacks section for more information.