Version 6.3 Released!

Click to checkout the new features
Old Documentation
You are browsing documentation for an old version of Tabulator. Consider upgrading your project to Tabulator 6.3

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

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.

Donate