Row Selection

• Overview
• Setup
  • Rolling Selection
  • Range Selection
  • Persistent Selection
  • Selection Eligibility
  • Tickbox Formatter
• Selection Management
• Component Selection
• Events

Overview Demo

Row selection allows users to select and highlight a number of rows that you can then take action on. This allows rows to be selected in a number of ways:

• Clicking on a row, to toggle its state.
• Holding down the shift key and click dragging over a number of rows to toggle the state of all rows the cursor passes over.
• Programmatically with the selectRow and deselectRow functions.

<div>
    <button id="select-row">Select "Oli Bob"</button>
    <button id="deselect-row">Deselect "Oli Bob"</button>
    <button id="select-all">Select All</button>
    <button id="deselect-all">Deselect All</button>

    <span id="select-stats"></span>
</div>

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

//Build Tabulator
var table = new Tabulator("#example-table", {
    height:"311px",
    selectableRows:true, //make rows selectable
    columns:[
	    {title:"Name", field:"name", width:200},
	    {title:"Progress", field:"progress", width:100, hozAlign:"right", sorter:"number"},
	    {title:"Gender", field:"gender", width:100},
	    {title:"Rating", field:"rating", hozAlign:"center", width:80},
	    {title:"Favourite Color", field:"col"},
	    {title:"Date Of Birth", field:"dob", hozAlign:"center", sorter:"date"},
	    {title:"Driver", field:"car", hozAlign:"center", width:100},
    ],
});

table.on("rowSelectionChanged", function(data, rows){
  document.getElementById("select-stats").innerHTML = data.length;
});

//select row on "select" button click
document.getElementById("select-row").addEventListener("click", function(){
    table.selectRow(1);
});

//deselect row on "deselect" button click
document.getElementById("deselect-row").addEventListener("click", function(){
    table.deselectRow(1);
});

//select row on "select all" button click
document.getElementById("select-all").addEventListener("click", function(){
    table.selectRow();
});

//deselect row on "deselect all" button click
document.getElementById("deselect-all").addEventListener("click", function(){
    table.deselectRow();
});

Setup

To enable row selection, set the selectableRows option to true

var table = new Tabulator("#example-table", {
	selectableRows:true,
});

The selectableRows option can take one of a several values:

• false - selectable rows are disabled
• true - selectable rows are enabled, and you can select as many as you want
• integer - any integer value, this sets the maximum number of rows that can be selected (when the maximum number of selected rows is exceded, the first selected row will be deselected to allow the next row to be selected).
• "highlight" (default) - rows have the same hover stylings as selectable rows but do not change state when clicked. This is great for when you want to show that a row is clickable but don't want it to be selectable.

Note: using the setData function will clear the currently selected rows.

Range Selection

By default you can select a range of rows by holding down the shift key and click dragging over a number of rows to toggle the selected state state of all rows the cursor passes over.

If you would prefere to select a range of row by clicking on the first row then holding down shift and clicking on the end row then you can achieve this by setting the selectableRowsRangeMode to click

var table = new Tabulator("#example-table", {
  selectableRowsRangeMode:"click",
});

In this mode, in order to select multiple non-continuous rows, you need to hold down the ctrl key and click on each row in turn.

Rolling Selection

By default, row selection works on a rolling basis, if you set the selectableRows option to a numeric value then when you select past this number of rows, the first row to be selected will be deselected. If you want to disable this behaviour and instead prevent selection of new rows once the limit is reached you can set the selectableRowsRollingSelection option to false.

var table = new Tabulator("#example-table", {
    selectableRows:5,
    selectableRowsRollingSelection:false, // disable rolling selection
});

Persistent Selection

By default Tabulator will maintain selected rows when the table is filtered, sorted or paginated (but NOT when the setData function is used). If you want the selected rows to be cleared whenever the table view is updated then set the selectableRowsPersistence option to false.

var table = new Tabulator("#example-table", {
    selectableRows:true,
    selectableRowsPersistence:false, // disable selection persistence
});

Selection Eligibility

You many want to exclude certain rows from being selected. The selectableRowsCheck options allows you to pass a function to check if the current row should be selectable, returning true will allow row selection, false will result in nothing happening. The function should accept a RowComponent as its first argument.

var table = new Tabulator("#example-table", {
    selectableRowsCheck:function(row){
        //row - row component
        return row.getData().age > 18; //allow selection of rows where the age is greater than 18
    },
});

Note: Any selectable rows will be assigned the tabulator-selectable class, any unselectable rows will be assigned the tabulator-unselectable class.

Tickbox Formatter

Use the rowSelection formatter in the row header to add a column of tickboxes down one side of your table to handle row selection:

var table = new Tabulator("#example-table", {
    selectableRows:true,
    rowHeader:{formatter:"rowSelection", titleFormatter:"rowSelection", headerSort:false, resizable: false, frozen:true, headerHozAlign:"center", hozAlign:"center"},
});

By default all rows in the table are toggled when the title formatter check box is clicked, you can change this by passing a Row Range Lookup value to the rowRange parameter in the column definitions titleFormatterParams option

var table = new Tabulator("#table", {
    selectableRows:true,
    rowHeader: {formatter:"rowSelection", titleFormatter:"rowSelection", titleFormatterParams:{
        rowRange:"active" //only toggle the values of the active filtered rows
    }, hozAlign:"center", headerSort:false},
});

The rowSelection formatter can only be used on the row header or one column at a time, loading this formatter onto multiple columns will result in inconsistent functionality.

Selection Management

As well as clicking on a row, you can trigger the selection or deselection of a row programmatically.

Select Row

To programmatically select a row you can use the selectRow function.

To select a specific row you can pass the any of the standard row component look up options into the first argument of the function. If you leave the argument blank you will select all rows (if you have set the selectableRows option to a numeric value, it will be ignored when selecting all rows).

table.selectRow(1); //select row with id of 1

Multiple Row Selection

If you want to select multiple rows at once you can either pass an array of row component look up options into the first argument:

table.selectRow([1,2,3,4]); //select rows with id's of 1,2 3 and 4

Or you can pass a Row Range Lookup value in its first argument:

table.selectRow("visible"); //select all rows currently visible in the table viewport

If you do not pass any arguments to the selectRow function, all rows will be selected

Deselect Row

To programmatically deselect a row you can use the deselectRow function.

To deselect a specific row you can pass any of the standard row component look up options into the first argument of the function. If you leave the argument blank you will deselect all rows.

table.deselectRow(1); //deselect row with id of 1

Multiple Row Deselection

If you want to deselect multiple rows you can pass an array of row component look up options into the first parameter

table.deselectRow([1,2,3]); //deselect thre rows with id's 1,2 and 3

Note: If you do not pass any arguments to the the deselectRow function, all rows will be deselected.

Get Selected Data

To get the data objects for the selected rows you can use the getSelectedData function.

This will return an array of the selected rows data objects in the order in which they were selected.

var selectedData = table.getSelectedData(); //get array of currently selected data.

Get Selected Row Components

To get the RowComponent's for the selected rows at any time you can use the getSelectedRows function.

This will return an array of RowComponent's for the selected rows in the order in which they were selected.

var selectedRows = table.getSelectedRows(); //get array of currently selected row components.

Component Selection

You can use the row component passed into any of Tabulator's callbacks to trigger selection of that row.

var table = new Tabulator("#example-table", {
    rowClick:function(e, row){
        //e - the click event object
        //row - row component

        row.toggleSelect(); //toggle row selected state on row click
    },
});

Select

The select function will select the current row.

row.select();

Deselect

The deselect function will deselect the current row.

row.deselect();

Toggle Selection

The toggleSelect function will toggle the selected state the current row.

row.toggleSelect();

Events

A range of events are available for row selection. See the Selection Events section for more information.