Navigation

• Overview
• Cell Navigation
• Scrolling
  • Scroll To Column
  • Scroll To Row

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

New Row on Tab

You can navigate between editable cells using the Tab key, By default nothing will happen when you tab out of the last editable cell on the table.

The tabEndNewRow option will cause the table to create a new row and add focus on the first editable cell in that row when you tab out of the last editable cell on the table. You can set it to one of a number of options to determine the data of the new row.

Boolean

Passing a value of true to the option will result in an empty new row being created

var table = new Tabulator("#example-table", {
    tabEndNewRow: true, //create empty new row on tab
});

Data Object

Passing an object to the option will result in a new rown being created with the data object provided

var table = new Tabulator("#example-table", {
    tabEndNewRow: {name:"steve", age:62}, //create new row with this data
});

Function

If you pass a function to the option the function will be called and passed the row component for the row of the current cell, the function should return the data object for the new row.

var table = new Tabulator("#example-table", {
    tabEndNewRow: function(row){
        //row - row component for current last row in table
        return {name:"bob", age:34}; // return data object for new row
    }
});

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.