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

Component Objects

Overview

Component objects are a key feature of Tabulator, that allow you to interact directly with the components of your table.

There is a component object for each row, column, cell and row group in your table. Each component provides a range of functions you can call to manipulate the table.

Components are passed into almost every callback available in Tabulator.

Component Types

Row Component

The row component provides access to a specific row. The example below shows how it is passed to the rowFormatter callback:

var table = new Tabulator("#example-table", {
    rowFormatter:function(row){
        var data = row.getData(); //get data object for row

        if(data.col == "blue"){
            row.getElement().style.backgroundColor = "#1e3b20"; //apply css change to row element
        }
    },
});

The component provides the following functions:

Get Data

The getData function returns the data object for the row.

var rowData = row.getData();

Get Element

The getElement function returns the DOM node for the row.

var rowElement = row.getElement();

Get Table

The getTable function returns the Tabulator object for the table containing the row.

var table = row.getTable();

Get Next Row

The getNextRow function returns the Row Component for the next visible row in the table, if there is no next row it will return a value of false.

var nextRow = row.getNextRow();

Get Previous Row

The getPrevRow function returns the Row Component for the previous visible row in the table, if there is no previous row it will return a value of false.

var prevRow = row.getPrevRow();

Get Cells

The getCells function returns an array of CellComponent objects, one for each cell in the row.

var cells = row.getCells();

Get Cell in Specific Column

The getCell function returns the CellComponent for the specified column from this row.

var cell = row.getCell(column);

Get Index

The getIndex function returns the index value for the row. (this is the value from the defined index column, NOT the row's position in the table)

var rowIndex = row.getIndex();

Get Position

Use the getPosition function to retrieve the numerical position of a row in the table. By default this will return the position of the row in all data, including data currently filtered out of the table.

If you want to get the position of the row in the currently filtered/sorted data, you can pass a value of true to the optional first argument of the function.

var rowPosition = row.getPosition(true); //return the position of the row in the filtered/sorted data

Get Group

When using grouped rows, you can retrieve the group component for the current row using the getGroup function.

var group = row.getGroup();

Delete

The delete function deletes the row, removing its data from the table

row.delete();

The delete method returns a promise, this can be used to run any other commands that have to be run after the row has been deleted. By running them in the promise you ensure they are only run after the row has been deleted.

row.delete()
.then(function(){
    //run code after row has been deleted
})
.catch(function(error){
    //handle error deleting row
});

Scroll To

The scrollTo function will scroll the table to the row if it passes the current filters.

row.scrollTo();

The scrollTo method returns 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.

row.scrollTo()
.then(function(){
    //run code after row has been scrolled to
})
.catch(function(error){
    //handle error scrolling to row
});

Page To

The pageTo function will load the page for the row if it passes the current filters.

row.pageTo();

The pageTo method returns 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 page has been loaded.

row.pageTo()
.then(function(){
    //run code after row has been scrolled to
})
.catch(function(error){
    //handle error scrolling to row
});

Local Pagination Only
This functionality is only available on local pagination. when using remote pagination Tabulator has ow way to lookup which page the requested row is on.

Move Row

You can move a row next to another row using the move function.

The first argument should be the target row that you want to move to, and can be any of the standard row component look up options.

The second argument determines whether the row is moved to above or below the target row. A value of false will cause to the row to be placed below the target row, a value of true will result in the row being placed above the target

row.move(12, true); //move the current row above the row with an index of 12

Update

You can update the data in the row using the update function. You should pass an object to the function containing any fields you wish to update. This object will not replace the row data, only the fields included in the object will be updated.

row.update({"name":"steve"}); //update the row data for field "name"

The update method returns a promise, this can be used to run any other commands that have to be run after the row has been updated. By running them in the promise you ensure they are only run after the row has been updated.

row.update()
.then(function(){
    //run code after row has been updated
})
.catch(function(error){
    //handle error updating row
});

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

Check Selection State

The isSelected function will return a boolean representing the current selected state of the row.

var selected = row.isSelected();

Normalize Height

If you are making manual adjustments to elements contained within the row, it may sometimes be necessary to recalculate the height of all the cells in the row to make sure they remain aligned. Call the normalizeHeight function to do this.

row.normalizeHeight();

Re-Format

If you want to re-format a row once it has been rendered to re-trigger the cell formatters and the rowFormatter callback, Call the reformat function.

row.reformat();

Freeze

You can freeze a row at the top of the table by calling the freeze function. This will insert the row above the scrolling portion of the table in the table header.

row.freeze();

Unfreeze

A frozen row can be unfrozen using the unfreeze function. This will remove the row from the table header and re-insert it back in the table.

row.unfreeze();

Check Frozen State

The isFrozen function will return a boolean representing the current frozen state of the row.

var frozen = row.isFrozen();

Expand Row

When the tree structure is enabled the treeExpand function will expand current row and show its children.

row.treeExpand();

Collapse Row

When the tree structure is enabled the treeCollapse function will collapse current row and hide its children.

row.treeCollapse();

Toggle Row

When the tree structure is enabled the treeToggle function will toggle the collapsed state of the current row.

row.treeToggle();

Get Parent Row

When the tree structure is enabled the getTreeParent function will return the Row Component for the parent of this row. If no parent exists, a value of false will be returned.

var parent = row.getTreeParent();

Get Child Rows

When the tree structure is enabled the getTreeChildren function will return an array of Row Components for this rows children.

var children = row.getTreeChildren();

Validate Row Data

The validate method will check the data in the cells of this row to see that it passes any validatiors defined on the rows columns

var valid = row.validate();

This will return a value of true if every cell passes validation, if any cells fail, then it will return an array of Cell Components representing each cell in that row that has failed validation.

Column Component

The column component provides access to a specific column. The example below shows how it is passed to the columnMoved callback.

var table = new Tabulator("#example-table", {
    columnMoved:function(column, columns){
        alert("The user has moved column: " + column.getField()); //display the columns field name
    }
});

The component provides the following functions:

Get Element

The getElement function returns the DOM node for the column.

var columnElement = column.getElement();

Get Table

The getTable function returns the Tabulator object for the table containing the column.

var table = column.getTable();

Get Definition

The getDefinition function returns the column definition object for the column.

var columnDefinition = column.getDefinition();

Update Definition

You can update the definition of a column by calling the updateDefinition function passing in an object containing properties of the column that you want to change. Any properties defined on the original column definition and not contained in the update object will be unchanged.

The function will return a promise that will resolve when the column has been updated, passing in the updated column component as an argument.

column.updateDefinition({title:"Updated Title"}) //change the column title
.then(function(column){
    //column - column component for the updated column;
})
.catch(function(error){
    //handle column update error
});

New Column Component It is worth noting that using this function actually replaces the old column with a totally new column component, therefor any references to the previous column component will no longer work after this function has been run.

Get Field

The getField function returns the field name for the column.

var columnField = column.getField();

Get Cells

The getCells function returns an array of CellComponent objects, one for each cell in the column.

var cells = column.getCells();

Get Next Column

The getNextColumn function returns the Column Component for the next visible column in the table, if there is no next column it will return a value of false.

var nextColumn = column.getNextColumn();

Get Previous Column

The getPrevColumn function returns the Column Component for the previous visible column in the table, if there is no previous column it will return a value of false.

var prevColumn = column.getPrevColumn();

Get Visibility

The isVisible function returns a boolean to show if the column is visible, a value of true means it is visible.

var visible = column.isVisible();

Show Column

The show function shows the column if it is hidden.

column.show();

Hide Column

The hide function hides the column if it is visible.

column.hide();

Toggle Visibility

The toggle function toggles the visibility of the column, switching between hidden and visible.

column.toggle();

Get Width

The getWidth function returns the width of the column in pixels

var width = column.getWidth();

Set Width

You can set the width of a column using the setWidth function, passing the width of the column in pixes as an integer as the first argument,

column.setWidth(123); // set the column width to 123 pixels

Passing a value of true to the function will resize the column to fit its contents

column.setWidth(true); // set the column width to fit its contents

Delete

The delete function deletes the column, removing it from the table

column.delete();

Scroll To

The scrollTo function will scroll the table to the column if it is visible.

column.scrollTo();

The scrollTo method returns 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.

column.scrollTo()
.then(function(){
    //run code after column has been scrolled to
})
.catch(function(error){
    //handle error scrolling to column
});

Move Column

You can move a column next to another column using the move function.

The first argument should be the target column that you want to move to, and can be any of the standard column component look up options.

The second argument determines whether the column is moved to before or after the target column. A value of false will cause to the column to be placed before the target column, a value of true will result in the column being placed after the target

column.move("age", true); //move the current column after the age column

Get Sub Columns

The getSubColumns function returns an array of ColumnComponent objects, one for each sub column of this column.

var subColumns = column.getSubColumns();

Get Parent Column

The getParentColumn function returns the ColumnComponent for the parent column of this column. if no parent exists, this function will return false

var parentColumn = column.getParentColumn();

Focus on Header Filter

The headerFilterFocus function will place focus on the header filter element for this column if it exists.

column.headerFilterFocus();

Set Header Filter Value

The setHeaderFilterValue function set the value of the columns header filter element to the value provided in the first argument.

column.setHeaderFilterValue("steve");

Get Header Filter Value

The getHeaderFilterValue function will retrieve the current value of the columns header filter.

var filterValue = column.getHeaderFilterValue();

Reload Header Filter Element

The reloadHeaderFilter function rebuilds the header filter element, updating any params passed into the editor used to generate the filter.

column.reloadHeaderFilter();

Column Data Validation

The validate method will check the data in the cells in this column to see that it passes any validatiors defined on the column

var valid = column.validate();

This will return a value of true if every cell passes validation, if any cells fail, then it will return an array of Cell Components representing each cell in that column that has failed validation.

Cell Component

The cell component provides access to a specific cell. The example below shows how it is passed to the cellClick callback for a cell.

{title:"Name", field:"name", cellClick:function(e, cell){
        alert("The cell has a value of:" + cell.getValue()); //display the cells value
    },
}

The Component provides the following functions:

Get Value

The getValue function returns the current value for the cell.

var cellValue = cell.getValue();

Get Old Value

The getOldValue function returns the previous value of the cell before the last edit. Very useful in the event of cell update callbacks.

var cellOldValue = cell.getOldValue();

Restore Old Value

The restoreOldValue reverts the value of the cell back to its previous value, without triggering any of the cell edit callbacks.

cell.restoreOldValue();

Get Initial Value

The getInitialValue function returns the value the cell held when it was first loaded, before any editing took place.

var cellInitialValue = cell.getInitialValue();

Restore Initial Value

The restoreInitialValue reverts the value of the cell back to its initial value, without triggering any of the cell edit callbacks.

cell.restoreInitialValue();

Get Element

The getElement function returns the DOM node for the cell.

var cellElement = cell.getElement();

Get Table

The getTable function returns the Tabulator object for the table containing the cell.

var table = cell.getTable();

Get Row

The getRow function returns the RowComponent for the row that contains the cell.

var row = cell.getRow();

Get Column

The getColumn function returns the ColumnComponent for the column that contains the cell.

var column = cell.getColumn();

Get Data

The getData function returns the data for the row that contains the cell.

var data = cell.getData();

Get Field

The getField function returns the field name for the column that contains the cell.

var field = cell.getField();

Set Value

You can change the value of the cell using the setValue function. The first parameter should be the new value for the cell, the second optional parameter will apply the column mutators to the value when set to true (default = true).

cell.setValue("Steve", true); //set the cell's value to "Steve" and apply the column mutators if present

Check Height

If you are making manual adjustments to elements contained withing the cell, or the cell itself, it may sometimes be necessary to recalculate the height of all the cells in the row to make sure they remain aligned. Call the checkHeight function to check if the height of the cell has changed and normalize the row if it has.

cell.checkHeight();

Edit

You and programmatically cause a cell to open its editor element using the edit function.

cell.edit();

If you want to ignore the editable property of the column definition and force the edit, you can pass an optional value of true to the function

cell.edit(true); //force the editor to open even if editable is set to false

Cancel Edit

You and programmatically cancel a cell edit that is currently in progress by calling the cancelEdit function.

cell.cancelEdit();

Check If Cell Has Been Edited

The isEdited function can be used to check if a cell has been edited in the past, it will return a value of true if the cell has been edited and false if it hasnt.

var edited = cell.isEdited();

Clear Edit Flag

The clearEdited function clear the edited state of the cell used by the isEdited function and mark the cell as unedited.

cell.clearEdited();

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 on the nav function to move the focus in different directions.

cell.nav().left(); //move focus left to next editable cell.

You can navigate any direction around the table using the following functions:

  • prev - next editable cell on the left, if none available move to the right most editable cell on the row above
  • next - next editable cell on the right, if none available move to left most editable cell on the row below
  • left - next editable cell on the left, return false if none available on row
  • right - next editable cell on the right, return false if none available on row
  • up - move to the same cell in the row above
  • down - move to the same cell in the row below

Cell Validation

The validate method will check the value of the cell against any validators defined on its column

var valid = cell.validate();

This will return a value of true if every cell passes validation, or false if it fails validation.

Cell Data Is Valid

The isValid method checks if a cell has previously passed a validation check without revalidating it, This is useful if you are using the highligh validation mode and want to check if an edited cell has passed validation

var valid = cell.isValid();

This will return a value of true if every cell passes validation, or false if it fails validation.

Clear Invalid Validation

The clearValidation method clears the invalid flag used by the isValid function and marks the cell as valid

cell.clearValidation();

Group Component

The group component provides access to a set of grouped rows. The example below shows how it is passed to the groupVisibilityChanged callback.

var table = new Tabulator("#example-table", {
    groupVisibilityChanged:function(group, visible){
        alert("The user has " (visible ? "opened" : "collapsed") +" group: " + group.getKey()); //display the groups unique key
    }
});

The component provides the following functions:

Get Element

The getElement function returns the DOM node for the group header.

var groupElement = group.getElement();

Get Table

The getTable function returns the Tabulator object for the table containing the group.

var table = group.getTable();

Get Key

The getKey function returns the unique key that is shared between all rows in this group.

var key = group.getKey();

Get Field

The getField function returns the string of the field that all rows in this group have been grouped by. (if a function is used to group the rows rather than a field, this function will return false)

var field = group.getField();

Get Rows

The getRows function returns an array of RowComponent objects, one for each row in the group.

var rows = group.getRows();

Get Sub Groups

The getSubGroups function returns an array of GroupComponent objects, one for each sub group of this group.

var subGroups = group.getSubGroups();

Get Parent Group

The getParentGroup function returns the GroupComponent for the parent group of this group. if no parent exists, this function will return false

var parentGroup = group.getParentGroup();

Get Visibility

The isVisible function returns a boolean to show if the group is visible, a value of true means it is visible.

var visible = group.isVisible();

Show Group

The show function shows the group if it is hidden.

group.show();

Hide Group

The hide function hides the group if it is visible.

group.hide();

Toggle Visibility

The toggle function toggles the visibility of the group, switching between hidden and visible.

group.toggle();

Calculation Component

The calc component is a subset of the Row Component, and is used for all calculation rows in the table, it has similar basic functionality to the row component, without a lot of the row specific functionality.

The component provides the following functions:

Get Data

The getData function returns the data object for the row.

var rowData = row.getData();

Get Element

The getElement function returns the DOM node for the row.

var rowElement = row.getElement();

Get Table

The getTable function returns the Tabulator object for the table containing the row.

var table = row.getTable();

Get Cells

The getCells function returns an array of CellComponent objects, one for each cell in the row.

var cells = row.getCells();

Get Cell in Specific Column

The getCell function returns the CellComponent for the specified column from this row.

var cell = row.getCell(column);

Component Lookup

Any function that takes a component as an argument will also attempt to find that component based on the value provided if it is not a component itself. The following values can be used for each component type:

Row

Column

Cell

Row Range Lookup

Functions that export rows from the table, like print and clipboard require a range of rows to be specified to be included in the export. This range variable can take one of the following strings as input:

  • visible - Rows currently visible in the table viewport
  • active - Rows currently in the table (rows that pass current filters etc)
  • selected - Rows currently selected by the selection module (this includes not currently active rows)
  • all - All rows in the table regardless of filters
var table = new Tabulator("#example-table", {
    printRowRange:"selected", //print only currently selected rows
});

Custom Row Range

For custom row ranges it is also possible to pass a function into range properties that should return an array of Row Components:

var table = new Tabulator("#example-table", {
    printRowRange:function(){
        //only print rows where the age is over 18
        return this.getRows().filter((row) => {
            return row.getData().age > 18;
        });
    },
});
Donate