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

Events

Overview

Tabulator provides a range of events, triggered during table usage that allow you to handle user interaction and system events.

Events are triggered as a simple notification, and do not expect any return value, unlike Callbacks which can be used to alter the behaviour of the table

Subscribe To Events

You can subscribe to events by calling the on function on the table and passing in the name of the event and the function you wish to be triggered on the event.

var table = new Tabulator("#example-table", {
  //setup your table
});

//subscribe to event
table.on("dataLoaded", function(data){
  //data has been loaded
});

Unsubscribe From Events

Unsubscribe All Listeners

To unsubscribe all listeners for a given event call the off function passing in the name of the event.

table.off("dataProcessed")

Unsubscribe One Listener

To a specific listener for a given event call the off function passing in the name of the event and the function that you previously subscribed too.

var dataProcessedEvent = function(data){
  //data has been loaded
}

//subscribe to event
table.on("dataProcessed", dataProcessedEvent);

//unsubscribe from event
table.off("dataProcessed", dataProcessedEvent);

Table Events

Table Building

When a the tabulator constructor is called, the tableBuilding callback will triggered:

table.on("tableBuilding", function(){});

Table Built

When a the tabulator constructor is called and the table has finished being rendered, the tableBuilt callback will triggered:

table.on("tableBuilt", function(){});

Column Events

Column Header Click

The headerClick event is triggered when a user left clicks on a column or group header.

table.on("headerClick", function(e, column){
    //e - the click event object
    //column - column component
});

Column Header Double Click

The headerDblClick event is triggered when a user double clicks on a column or group header.

table.on("headerDblClick", function(e, column){
    //e - the click event object
    //column - column component
});

Column Header Right Click

The headerContext event is triggered when a user right clicks on a column or group header.

table.on("headerContext", function(e, column){
    //e - the click event object
    //column - column component
});

Column Header Tap

The headerTap event is triggered when a user taps on the column header on a touch display.

table.on("headerTap", function(e, column){
    //e - the tap event object
    //column - column component
});

Column Header Double Tap

The headerDblTap event is triggered when a user taps on the column header on a touch display twice in under 300ms.

table.on("headerDblTap", function(e, column){
    //e - the tap event object
    //column - column component
});

Column Header Tap Hold

The headerTapHold event is triggered when a user taps on the column header on a touch display and holds their finger down for over 1 second.

table.on("headerTapHold", function(e, column){
    //e - the tap event object
    //column - column component
});

Column Header Mouse Enter

The headerMouseEnter event is triggered when the mouse pointer enters a column header.

table.on("headerMouseEnter", function(e, column){
    //e - the mouse event object
    //column - column component
});

Column Header Mouse Leave

The headerMouseLeave event is triggered when the mouse pointer leaves a column header.

table.on("headerMouseLeave", function(e, column){
    //e - the mouse event object
    //column - column component
});

Column Header Mouse Over

The headerMouseOver event is triggered when the mouse pointer moves over a column header, or any of its children.

table.on("headerMouseOver", function(e, column){
    //e - the mouse event object
    //column - column component
});

Column Header Mouse Out

The headerMouseOut event is triggered when the mouse pointer leaves a column header, or any of its children.

table.on("headerMouseOut", function(e, column){
    //e - the mouse event object
    //column - column component
});

Column Header Mouse Move

The headerMouseMove event is triggered when the mouse pointer moves over a column header.

table.on("headerMouseMove", function(e, column){
    //e - the mouse event object
    //column - column component
});

Column Moved

The columnMoved event will be triggered when a column has been successfully moved.

table.on("columnMoved", function(column, columns){
    //column - column component of the moved column
    //columns- array of columns in new order
});

Column Resized

The columnResized event will be triggered when a column has been resized by the user.

table.on("columnResized", function(column){
    //column - column component of the resized column
});

Column Visibility Changed

The columnVisibilityChanged event is triggered whenever a column changes between hidden and visible states.

table.on("columnVisibilityChanged", function(column, visible){
    //column - column component
    //visible - is column visible (true = visible, false = hidden)
});

Column Title Changed

The columnTitleChanged event is triggered whenever a user edits a column title when the editableTitle parameter has been enabled in the column definition array.

table.on("columnTitleChanged", function(column){
    //column - column component
});

Row Events

Row Click

The rowClick event is triggered when a user clicks on a row.

table.on("rowClick", function(e, row){
    //e - the click event object
    //row - row component
});

Row Double Click

The rowDblClick event is triggered when a user double clicks on a row.

table.on("rowDblClick", function(e, row){
    //e - the click event object
    //row - row component
});

Row Right Click

The rowContext event is triggered when a user right clicks on a row.

If you want to prevent the browsers context menu being triggered in this event you will need to include the preventDefault() function in your event.

table.on("rowContext", function(e, row){
    //e - the click event object
    //row - row component

    e.preventDefault(); // prevent the browsers default context menu form appearing.
});

Row Tap

The rowTap event is triggered when a user taps on a row on a touch display.

table.on("rowTap", function(e, row){
    //e - the tap event object
    //row - row component
});

Row Double Tap

The rowDblTap event is triggered when a user taps on a row on a touch display twice in under 300ms.

table.on("rowDblTap", function(e, row){
    //e - the tap event object
    //row - row component
});

Row Tap Hold

The rowTapHold event is triggered when a user taps on a row on a touch display and holds their finger down for over 1 second.

table.on("rowTapHold", function(e, row){
    //e - the tap event object
    //row - row component
});

Row Mouse Enter

The rowMouseEnter event is triggered when the mouse pointer enters a row.

table.on("rowMouseEnter", function(e, row){
    //e - the event object
    //row - row component
});

Row Mouse Leave

The rowMouseLeave event is triggered when the mouse pointer leaves a row.

table.on("rowMouseLeave", function(e, row){
    //e - the event object
    //row - row component
});

Row Mouse Over

The rowMouseOver event is triggered when the mouse pointer enters a row or any of its child elements.

table.on("rowMouseOver", function(e, row){
    //e - the event object
    //row - row component
});

Row Mouse Out

The rowMouseOut event is triggered when the mouse pointer leaves a row or any of its child elements.

table.on("rowMouseOut", function(e, row){
    //e - the event object
    //row - row component
});

Row Mouse Move

The rowMouseMove event is triggered when the mouse pointer moves over a row.

table.on("rowMouseMove", function(e, row){
    //e - the event object
    //row - row component
});

Row Added

The rowAdded event is triggered when a row is added to the table by the addRow and updateOrAddRow functions.

table.on("rowAdded", function(row){
    //row - row component
});

Row Updated

The rowUpdated event is triggered when a row is updated by the updateRow, updateOrAddRow, updateData or updateOrAddData, functions.

table.on("rowUpdated", function(row){
    //row - row component
});

Row Deleted

The rowDeleted event is triggered when a row is deleted from the table by the deleteRow function.

table.on("rowDeleted", function(row){
    //row - row component
});

Row Resized

The rowResized event will be triggered when a row has been resized by the user.

table.on("rowResized", function(row){
    //row - row component of the resized row
});

Cell Events

Cell Click

The cellClick event is triggered when a user left clicks on a cell.

table.on("cellClick", function(e, cell){
        //e - the click event object
        //cell - cell component
});

Cell Double Click

The cellDblClick event is triggered when a user double clicks on a cell

table.on("cellDblClick", function(e, cell){
        //e - the click event object
        //cell - cell component
});

Cell Right Click

The cellContext event is triggered when a user right clicks on a cell.

table.on("cellContext", function(e, cell){
        //e - the click event object
        //cell - cell component
});

Cell Tap

The cellTap event is triggered when a user taps on a cell in this column on a touch display.

table.on("cellTap", function(e, cell){
        //e - the tap event object
        //cell - cell component
});

Cell Double Tap

The cellDblTap event is triggered when a user taps on a cell in this column on a touch display twice in under 300ms.

table.on("cellDblTap", function(e, cell){
        //e - the tap event object
        //cell - cell component
});

Cell Tap Hold

The cellTapHold event is triggered when a user taps on a cell in this column on a touch display and holds their finger down for over 1 second.

table.on("cellTapHold", function(e, cell){
        //e - the tap event object
        //cell - cell component
});

Cell Mouse Enter

The cellMouseEnter event is triggered when the mouse pointer enters a cell.

table.on("cellMouseEnter", function(e, cell){
        //e - the event object
        //cell - cell component
});

Cell Mouse Leave

The cellMouseLeave event is triggered when the mouse pointer leaves a cell.

table.on("cellMouseLeave", function(e, cell){
        //e - the event object
        //cell - cell component
});

Cell Mouse Over

The cellMouseOver event is triggered when the mouse pointer enters a cell or one of its child element.

table.on("cellMouseOver", function(e, cell){
        //e - the event object
        //cell - cell component
});

Cell Mouse Out

The cellMouseOut event is triggered when the mouse pointer leaves a cell or one of its child element.

table.on("cellMouseOut", function(e, cell){
        //e - the event object
        //cell - cell component
});

Cell Mouse Move

The cellMouseMove event is triggered when the mouse pointer moves over a cell.

table.on("cellMouseMove", function(e, cell){
        //e - the event object
        //cell - cell component
});

Data Events

Data Loading

The dataLoading event is triggered whenever new data is loaded into the table.

table.on("dataLoading", function(data){
        //data - the data loading into the table
});

Data Loaded

The dataLoaded event is triggered when a new set of data is loaded into the table, but before it is processed.

table.on("dataLoaded", function(data){
        //data - all data loaded into the table
});

Data Load Error

The dataLoadError event is triggered there is an error response to a load request. This event is passed the Fetch Response Object as its first argument, which allows access to the response content, status code, etc.

table.on("dataLoadError", function(error){
    //error - the returned error object
});

Data Processing

The dataProcessing event is triggered after data is loaded into the table, just as it starts being processed into rows and cells.

table.on("dataProcessing", function(){});

Data Processed

The dataProcessed event is triggered after data has been processed and the table has been rendered.

table.on("dataProcessed", function(){});

Data Changed

The dataChanged event is triggered whenever the table data is changed. Triggers for this include editing any cell in the table, adding a row and deleting a row or updating a row.

table.on("dataChanged", function(data){
        //data - the updated table data
});

Edit Events

Cell Editing

The cellEditing event is triggered when a user starts editing a cell.

table.on("cellEditing", function(cell){
        //cell - cell component
});

Cell Edit Cancelled

The cellEditCancelled event is triggered when a user aborts a cell edit and the cancel function is called.

table.on("cellEditCancelled", function(cell){
        //cell - cell component
});

Cell Edited

The cellEdited event is triggered when data in an editable cell is changed.

table.on("cellEdited", function(cell){
        //cell - cell component
});

HTML Import Events

HTML Importing

The htmlImporting event is triggered when Tabulator starts importing data from an HTML table.

table.on("htmlImporting", function(){});

HTML Imported

The htmlImported event is triggered when Tabulator finishes importing data from an HTML table.

table.on("htmlImported", function(){});

Filter Events

Data Filtering

The dataFiltering event is triggered whenever a filter event occurs, before the filter happens.

table.on("dataFiltering", function(filters){
    //filters - array of filters currently applied

});

Data Filtered

The dataFiltered event is triggered after the table dataset is filtered.

table.on("dataFiltered", function(filters, rows){
    //filters - array of filters currently applied
    //rows - array of row components that pass the filters
});

Sorting Events

Data Sorting

The dataSorting event is triggered whenever a sort event occurs, before sorting happens.

table.on("dataSorting", function(sorters){
    //sorters - an array of the sorters currently applied
});

Data Sorted

The dataSorted event is triggered after the table dataset is sorted.

table.on("dataSorted", function(sorters, rows){
    //sorters - array of the sorters currently applied
    //rows - array of row components in their new order
});

Layout Events

Render Started

The renderStarted event is triggered whenever all the rows in the table are about to be rendered. This can include:

  • Data is loaded into the table when setData is called
  • A page is loaded through any form of pagination
  • Rows are added to the table during progressive rendering
  • Columns are changed by setColumns
  • The data is filtered
  • The data is sorted
  • The redraw function is called

table.on("renderStarted", function(){});

Render Complete

The renderComplete event is triggered after the table has been rendered

table.on("renderComplete", function(){});

Pagination Events

Page Loaded

Whenever a page has been loaded, the pageLoaded event is called, passing the current page number as an argument.

table.on("pageLoaded", function(pageno){
    //pageno - the number of the loaded page
});

Page Size Changed

Whenever the page size of the table is set or changed the pageSizeChanged event is called, passing the number of rows per page as an argument.

table.on("pageSizeChanged", function(pagesize){
    //pagesize - the number of rows per page
});

Localization Events

Table Localized

When a localization event has occurred , the localized event will triggered, passing the current locale code and language object:

table.on("localized", function(locale, lang){
    //locale - a string representing the current locale
    //lang - the language object for the current locale
});

Group Events

Group Click

The groupClick event is triggered when a user clicks on a group header.

table.on("groupClick", function(e, group){
    //e - the click event object
    //group - group component
});

Group Double Click

The groupDblClick event is triggered when a user double clicks on a group header.

table.on("groupDblClick", function(e, group){
    //e - the click event object
    //group - group component
});

Group Right Click

The groupContext event is triggered when a user right clicks on a group header.

If you want to prevent the browsers context menu being triggered in this event you will need to include the preventDefault() function in your event.

table.on("groupContext", function(e, group){
    //e - the click event object
    //group - group component

    e.preventDefault(); // prevent the browsers default context menu form appearing.
});

Group Tap

The groupTap event is triggered when a user taps on a group header on a touch display.

table.on("groupTap", function(e, group){
    //e - the tap event object
    //group - group component
});

Group Double Tap

The groupDblTap event is triggered when a user taps on a group header on a touch display twice in under 300ms.

table.on("groupDblTap", function(e, group){
    //e - the tap event object
    //group - group component
});

Group Tap Hold

The groupTapHold event is triggered when a user taps on a group header on a touch display and holds their finger down for over 1 second.

table.on("groupTapHold", function(e, group){
    //e - the tap event object
    //group - group component
});

Group Mouse Enter

The groupMouseEnter event is triggered when the mouse pointer enters a group header.

table.on("groupMouseEnter", function(e, group){
    //e - the event object
    //group - group component
});

Group Mouse Leave

The groupMouseLeave event is triggered when the mouse pointer leaves a group header.

table.on("groupMouseLeave", function(e, group){
    //e - the event object
    //group - group component
});

Group Mouse Over

The groupMouseOver event is triggered when the mouse pointer enters a group header or any of its child elements.

table.on("groupMouseOver", function(e, group){
    //e - the event object
    //group - group component
});

Group Mouse Out

The groupMouseOut event is triggered when the mouse pointer leaves a group header or any of its child elements.

table.on("groupMouseOut", function(e, group){
    //e - the event object
    //group - group component
});

Group Mouse Move

The groupMouseMove event is triggered when the mouse pointer moves over a group header.

table.on("groupMouseMove", function(e, group){
    //e - the event object
    //group - group component
});

Data Grouping

The dataGrouping event is triggered whenever a data grouping event occurs, before grouping happens.

table.on("dataGrouping", function(){});

Data Grouped

The dataGrouped event is triggered whenever a data grouping event occurs, after grouping happens.

table.on("dataGrouped", function(groups){
    //groups - array of top level group components
});

Group Visibility Changed

The groupVisibilityChanged event is triggered whenever a group changes between hidden and visible states.

table.on("groupVisibilityChanged", function(group, visible){
    //group - group component
    //visible - is group visible (true = visible, false = hidden)
});

Selection Events

Row Selected

The rowSelected event is triggered when a row is selected, either by the user or programmatically.

table.on("rowSelected", function(row){
    //row - row component for the selected row
});

Row Deselected

The rowDeselected event is triggered when a row is deselected, either by the user or programmatically.

table.on("rowDeselected", function(row){
    //row - row component for the deselected row
});

Row Selection Changed

Whenever the number of selected rows changes, through selection or deselection, the rowSelectionChanged event is triggered. This passes an array of the data objects for each row in the order they were selected as the first argument, and an array of row components for each of the rows in order of selection as the second argument.

table.on("rowSelectionChanged", function(data, rows){
    //rows - array of row components for the selected rows in order of selection
    //data - array of data objects for the selected rows in order of selection
});

Row Movement Events

Standard Row Movement Events

These events are triggered when a row is moved inside a single table

Row Move Started

The rowMoving event will be triggered when a row has started to be dragged.

table.on("rowMoving", function(row){
    //row - row component
});

Row Moved

The rowMoved event will be triggered when a row has been successfully moved.

table.on("rowMoved", function(row){
    //row - row component
});

Row Move Cancelled

The rowMoveCancelled event will be triggered when a row has been moved but has not changed position in the table.

table.on("rowMoveCancelled", function(row){
    //row - row component
});

Inter-Table Row Movement Events

These events are triggered when a row is dragged between tables

Sending Start

The movableRowsSendingStart event is triggered on the sending table when a row is picked up from a sending table.

table.on("movableRowsSendingStart", function(toTables){
    //toTables - array of receiving table elements
});

Row Sent

The movableRowsSent event is triggered on the sending table when a row has been successfully received by a receiving table.

table.on("movableRowsSent", function(fromRow, toRow, toTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //toTable - the Tabulator object for the receiving table
});

Row Sent Failed

The movableRowsSentFailed event is triggered on the sending table when a row has failed to be received by the receiving table.

table.on("movableRowsSentFailed", function(fromRow, toRow, toTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //toTable - the Tabulator object for the receiving table
});

Sending Stop

The movableRowsSendingStop event is triggered on the sending table after a row has been dropped and any senders and receivers have been handled.

table.on("movableRowsSendingStop", function(toTables){
    //toTables - array of receiving table Tabulator objects
});

Receiving Start

The movableRowsReceivingStart event is triggered on a receiving table when a connection is established with a sending table.

table.on("movableRowsReceivingStart", function(fromRow, fromTable){
    //fromRow - the row component from the sending table
    //fromTable - the Tabulator object for the sending table
});

Row Received

The movableRowsReceived event is triggered on a receiving table when a row has been successfully received.

table.on("movableRowsReceived", function(fromRow, toRow, fromTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //fromTable - the Tabulator object for the sending table
});

Row Received Failed

The movableRowsReceivedFailed event is triggered on a receiving table when a row receiver has returned false.

table.on("movableRowsReceivedFailed", function(fromRow, toRow, fromTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //fromTable - the Tabulator object for the sending table
});

Receiving Stop

The movableRowsReceivingStop event is triggered on a receiving table after a row has been dropped and any senders and receivers have been handled.

table.on("movableRowsReceivingStop", function(fromTable){
    //fromTable - the Tabulator object for the sending table
});

Row Dropped on Element

The movableRowsElementDrop event is triggered when a row is dropped on an element listed in the movableRowsConnectedElements option.

table.on("movableRowsElementDrop", function(e, element, row){
    //e - mouseup event object
    //element - node object for the element that the row was dropped onto
    //row - row component for the row that was moved
});

Validation Events

Validation Failed

The validationFailed event is triggered when the value entered into a cell during an edit fails to pass validation.

table.on("validationFailed", function(cell, value, validators){
    //cell - cell component for the edited cell
    //value - the value that failed validation
    //validators - an array of validator objects that failed
});

The validators argument contains a an array of validator objects for each validator that has failed. each object has a type prop which is the key for that validator (eg. "required"), and parameters prop which contains any props passed with the validator

In the example below, the validation failed on the min validator with its parameter set to 5:

[
    {
        key:"min"
        parameters:5,
    }
]

History Events

History events are triggered when undo and redo actions are triggered.

The history events are passed three arguments, the first is a string representing the action being undone/redone, the second is the Row or Cell component relating to the action, the third is the data object related to the action. The table below outlines the possible actions and their associated data objects:

Action Description Component Data
cellEdit Cell value edited Cell Component 
{
    oldValue:"", //the original value of the cell
    newValue:"", //the nev value of the cell
}
rowAdd Row added to table Row Component 
{
    data:{}, //the data contained in the row
    pos:0, //the position the row was inserted into the table
    index:0, //the index column value for the row
}
rowDelete Row deleted from table Row Component 
{
    data:{}, //the data contained in the row
    pos:0, //the position the row was removed from the table
    index:0, //the index column value for the row
}
rowMoved Row moved to new position in table Row Component 
{
    pos:0, //the position the row was moved from
    to:null, //row component for the row this row was moved next to
    after:false, //row was moved before or after the "to" row
}

Undo Occurred

The historyUndo event is triggered when the undo action is triggered.

table.on("historyUndo", function(action, component, data){
    //action - the action that has been undone
    //component - the Component object affected by the action (could be a row or cell component)
    //data - the data being changed
});

Redo Occurred

The historyRedo event is triggered when the redo action is triggered.

table.on("historyRedo", function(action, component, data){
    //action - the action that has been redone
    //component - the Component object affected by the action (could be a row or cell component)
    //data - the data being changed
});

Clipboard Events

Data Copied to Clipboard

The clipboardCopied event is triggered whenever data is copied to the clipboard.

table.on("clipboardCopied", function(clipboard){
    //clipboard - the string that has been copied into the clipboard
});

Data Pasted into Table

The clipboardPasted event is triggered whenever data is successfully pasted into the table.

table.on("clipboardPasted", function(clipboard, rowData, rows){
    //clipboard - the clipboard string
    //rowData - the row data from the paste parser
    //rows - the row components from the paste action (this will be empty if the "replace" action is used)
});

Data Paste into Table Failed

The clipboardPasteError event is triggered whenever an attempt to paste data into the table has failed because it was rejected by the paste parser.

table.on("clipboardPasteError", function(clipboard){
    //clipboard - the clipboard string that was rejected by the paste parser
});

Menu Events

Menu Opened

The menuOpened callback is triggered when a menu is opened.

table.on("menuOpened", function(component){
    //component - the component the menu has been opened on (could be cell, row or column depending on menu)
});

Menu Closed

The menuClosed callback is triggered when a menu is closed.

table.on("menuClosed", function(component){
    //component - the component the menu has been closed for (could be cell, row or column depending on menu)
});

Popup Events

Popup Opened

The popupOpened callback is triggered when a popup is opened.

table.on("popupOpened", function(component){
    //component - the component the popup has been opened on (could be cell, row or column depending on popup)
});

Popup Closed

The popupClosed callback is triggered when a popup is closed.

table.on("popupClosed", function(component){
    //component - the component the popup has been closed for (could be cell, row or column depending on popup)
});

Download Events

Download Complete

The downloadComplete callback is triggered when the user has been prompted to download the file.

table.on("downloadComplete", function(){});

Data Tree Events

Row Expanded

The dataTreeRowExpanded callback is triggered when a row with child rows is expanded to reveal the children.

table.on("dataTreeRowExpanded", function(row, level){
    //row - the row component for the expanded row
    //level - the depth of the row in the tree
});

Row Collapsed

The dataTreeRowCollapsed callback is triggered when a row with child rows is collapsed to hide its children.

table.on("dataTreeRowCollapsed", function(row, level){
    //row - the row component for the collapsed row
    //level - the depth of the row in the tree
});

Scrolling Events

Vertical Scroll

The scrollVertical callback is triggered when the table is vertically scrolled.

table.on("scrollVertical", function(top){
        //top - the current vertical scroll position
});

Complex Functions This function is called many times during a scroll. It is strongly recommended that you don't carry out any intensive actions or call any other functions on the table in this function as it will slow down the table rendering and result in a poor user experience.

Horizontal Scroll

The scrollHorizontal callback is triggered when the table is horizontally scrolled.

table.on("scrollHorizontal", function(left){
        //left - the current horizontal scroll position
});

Complex Functions This function is called many times during a scroll. It is strongly recommended that you don't carry out any intensive actions or call any other functions on the table in this function as it will slow down the table rendering and result in a poor user experience.

Donate