Beta Release - This version is currently under development and should not be used in a production environment.

Row Selection

Overview

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.

Setup

To enable row selection, set the selectable option to true

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

The selectable 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.

Rolling Selection

By default, row selection works on a rolling basis, if you set the selectable 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 disabled this behaviour and instead prevent selection of new rows once the limit is reached you can set the selectableRollingSelection option to false.

var table = new Tabulator("#example-table", {
    selectable:5,
    selectableRollingSelection: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 selectablePersistence option to false.

var table = new Tabulator("#example-table", {
    selectable:true,
    selectablePersistence:false, // disable rolling selection
});

Selection Eligibility

You many want to exclude certain rows from being selected. The selectableCheck 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", {
    selectableCheck:function(row){
        //row - row component
        return row.getData().age > 18; //alow 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.

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 selectable option to a numeric value, it will be ignored when selecting all rows).

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

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

If you do not pass any arguments to the selectRow function, all rows will be selected. To select only rows that have been filtered pass true as the first argument.

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

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

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();

Callbacks

A range of callbacks are avaialble for row selection. See the Selection Callbacks section for more information.