Navigation
Overview
Tabulator comes packed with a number of different ways to navigate around your table.
Cell Navigation
When a cell is being edited it is possible to move the editor focus from the current cell to one if its neighbours. There are a number of functions that can be called to move the focus in different directions.
Note: These actions will only work when a cell is editable and has focus.
Note: Navigation commands will only focus on editable cells, that is cells with an editor and if present an editable function that returns true.
Navigation Functions
Previous Cell
Use the navigatePrev function to shift focus to the next editable cell on the left, if none available move to the right most editable cell on the row above.
table.navigatePrev();
If the keybindings module is installed, this action can also be triggered with the shift + tab key combination.
Next Cell
Use the navigateNext function to shift focus to the next editable cell on the right, if none available move to left most editable cell on the row below.
table.navigateNext();
If the keybindings module is installed, this action can also be triggered with the tab key combination.
Left Cell
Use the navigateLeft function to shift focus to next editable cell on the left, return false if none available on row.
table.navigateLeft();
Right Cell
Use the navigateRight function to shift focus to next editable cell on the right, return false if none available on row.
table.navigateRight();
Up Cell
Use the navigateUp function to shift focus to the same cell in the row above.
table.navigateUp();
If the keybindings module is installed, this action can also be triggered with the up arrow key combination.
Down Cell
Use the navigateDown function to shift focus to the same cell in the row below.
table.navigateDown();
If the keybindings module is installed, this action can also be triggered with the down arrow key combination.
Navigation from Cell Components
If you have a CellComponent, you can call navigation functions directly on the component. For more details see the CellComponent documentation
Scrolling
Scroll To Column
If you want to trigger an animated scroll to a column then you can use the scrollToColumn function. The first argument should be any of the standard column component look up options for the column you want to scroll to.
The second argument is optional, and is used to set the position of the column, it should be a string with a value of either left, middle or right, if omitted it will be set to the value of the scrollToColumnPosition option which has a default value of left.
The third argument is optional, and is a boolean used to set if the table should scroll if the column is already visible, true to scroll, false to not, if omitted it will be set to the value of the scrollToColumnIfVisible option, which defaults to true
table.scrollToColumn("age", "middle", false); //scroll column with field of "age" to the middle if not already visible
The function will return a promise, this can be used to run any other commands that have to be run after the column has been scrolled to. By running them in the promise you ensure they are only run after the column has been scrolled to.
table.scrollToColumn("age", "middle", false)
.then(function(){
//run code after column has been scrolled to
})
.catch(function(error){
//handle error scrolling to column
});
Default ScrollTo Position
The default ScrollTo position can be set using the scrollToColumnPosition option. It can take one of three possible values:
- left - position column with its left edge at the left of the table (default)
- center - position column with its left edge in the center of the table
- right - position column with its right edge at the right of the table
var table = new Tabulator("#example-table", {
scrollToColumnPosition: "center", //position column in the center of the table when scrolled to
});
Default ScrollTo If Visible
The default option for triggering a ScrollTo on a visible element can be set using the scrollToColumnIfVisible option. It can take a boolean value:
- true - scroll to column, even if it is visible (default)
- false - scroll to column, unless it is currently visible, then don't move
var table = new Tabulator("#example-table", {
scrollToColumnIfVisible: false, //position column in the middle of the table when scrolled to
});
Partially Visible Columns
If a column is not entirely visible, ie. it is partially scrolled out of view, it will be counted as not visible and the scroll action will occur.
Scroll To Row
If you want to trigger an animated scroll to a row then you can use the scrollToRow function.
The first argument should be any of the standard row component look up options for the row you want to scroll to.
The second argument is optional, and is used to set the position of the row, it should be a string with a value of either top, center, bottom or nearest, if omitted it will be set to the value of the scrollToRowPosition option which has a default value of top.
The third argument is optional, and is a boolean used to set if the table should scroll if the row is already visible, true to scroll, false to not, if omitted it will be set to the value of the scrollToRowIfVisible option, which defaults to true
table.scrollToRow(23, "center", false); //scroll row with id of 23 to the center if not already visible
The function will return a promise, this can be used to run any other commands that have to be run after the row has been scrolled to. By running them in the promise you ensure they are only run after the row has been scrolled to.
table.scrollToRow(23, "middle", false)
.then(function(){
//run code after row has been scrolled to
})
.catch(function(error){
//handle error scrolling to row
});
Default ScrollTo Position
The default ScrollTo position can be set using the scrollToRowPosition option. It can take one of four possible values:
- top - position row with its top edge at the top of the table (default)
- center - position row with its top edge in the center of the table
- bottom - position row with its bottom edge at the bottom of the table
- nearest - position row on the edge of the table it is closest to
var table = new Tabulator("#example-table", {
scrollToRowPosition: "center", //position row in the center of the table when scrolled to
});
Row Availability
In order to scroll to the top or center a row must have enough rows underneath it in the table to allow it to reach that position. Tabulator does not allow for empty space beneath rows, so if a row does not have enough rows underneath it to reach the desired position it will scroll as high as it can without leaving empty space at the bottom of the table.
Default ScrollTo If Visible
The default option for triggering a ScrollTo on a visible element can be set using the scrollToRowIfVisible option. It can take a boolean value:
- true - scroll to row, even if it is visible (default)
- false - scroll to row, unless it is currently visible, then don't move
var table = new Tabulator("#example-table", {
scrollToRowIfVisible: false, //prevent scrolling to a row if it is visible
});
Partially Visible Rows
If a row is not entirely visible, ie. it is partially scrolled out of view, it will be counted as not visible and the scroll action will occur.