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