Setup

You can have yourself up and running in a couple of minutes using the steps below:

Include the jQuery and jQuery UI libraries before you load the Tabulator library. you can either download these and load them from your local server or choose from a popular CDN.

<script type="text/javascript" src="jquery.min.js"></script>
<script type="text/javascript" src="jquery-ui.min.js"></script>

Include the Tabulator library and style sheet

<link href="dist/css/tabulator.min.css" rel="stylesheet">
<script type="text/javascript" src="dist/js/tabulator.min.js"></script>

Create an element to hold the table

<div id="example-table"></div>

Turn the element into a tabulator with some simple javascript

$("#example-table").tabulator();

Installation

There are a number of ways you can include the Tabulator source in your project.

Bower Installation

To get Tabulator via the Bower package manager, open a terminal in your project directory and run the following commmand:

bower install tabulator --save

NPM Installation

To get Tabulator via the NPM package manager, open a terminal in your project directory and run the following commmand:

npm install jquery.tabulator --save
Then to add the library to your project, you will need to require it after the jquery-ui library:
require('jquery.tabulator');

Git Clone

If you use the Git CVS you can clone the repository directly to your computer with the following terminal command:

git clone https://github.com/olifolkerd/tabulator.git

Download

You can download the source as a zip fie from here.

CDNJS

To access Tabulator directly from the CDNJS CDN servers, include the following two lines at the start of your project, instead of the localy hosted versions:

<link href="https://cdnjs.cloudflare.com/ajax/libs/tabulator/3.5.3/css/tabulator.min.css" rel="stylesheet">
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/tabulator/3.5.3/js/tabulator.min.js"></script>

Check out more of the great libraries available to use direclty from CDNJS at https://cdnjs.com/

jQuery Dependencies

Tabulator is dependant on the jQuery and jQuery UI libraries. You can include these files in your project or reference them from a CDN of your choice.

If you are looking for the most optimized packages possible, then Tabulator only depends on a few of the features available in jQUery UI:

Core Dependencies

  • Widget

An opmimized jQuery UI library can be downloaded here.

Note: In the long term Tabulator is going to become dependencey free, by version 4.0 there will be no dependencies on either jQuery or jQuery UI.

Define Columns Updated

Column headers are defined as an array of JSON objects passed into the columns option when you create your tabulator

$("#example-table").tabulator({
    columns:[
        {title:"Name", field:"name", sorter:"string", width:200, editor:true},
        {title:"Age", field:"age", sorter:"number", align:"right", formatter:"progress"},
        {title:"Gender", field:"gender", sorter:"string", cellClick:function(e, cell){console.log("cell click")},},
        {title:"Height", field:"height", formatter:"star", align:"center", width:100},
        {title:"Favourite Color", field:"col", sorter:"string"},
        {title:"Date Of Birth", field:"dob", sorter:"date", align:"center"},
        {title:"Cheese Preference", field:"cheese", sorter:"boolean", align:"center", formatter:"tickCross"},
    ],
});

There are a number of properties that can be set in a defintion object to determine how the column is displayed:

General

  • title - Required This is the title that will be displayed in the header for this column
  • field - Required (not required in icon/button columns) this is the key for this column in the data array
  • visible - (boolean, default - true) determines if the column is visible. (see Column Visibility for more details)

Layout

  • align - sets the text alignment for this column (left|center|right)
  • width - sets the width of this column, this can be set in pixels or as a percentage of total table width (if not set the system will determine the best)
  • minWidth - sets the minimum width of this column, this should be set in pixels (this takes priority over the global option of columnMinWidth)
  • widthGrow New - when using fitColumns layout mode, determines how much the column should grow to fill available space (see Table Layout for more details)
  • widthShrink New - when using fitColumns layout mode, determines how much the column should shrink to fit available space (see Table Layout for more details)
  • resizable New - set whether column can be resized by user dragging its edges (see Table Layout for more details)
  • frozen - freezes the column in place when scrolling (see Frozen Columns for more details)
  • responsive - an integer to determine when the column should be hidden in responsive mode (see Responsive Layout for more details)
  • tooltip - sets the on hover tooltip for each cell in this column (see Formatting Data for more details)
  • cssClass - sets css classes on header and cells in this column. (value should be a string containing space seperated class names)
  • rowHandle - sets the column as a row handle, allowing it to be used to drag movable rows. (see Movable Rows for more details)
  • hideInHtml - When the getHtml function is called, hide the column from the output.

Data Manipulation

  • sorter - determines how to sort data in this column (see Sorting Data for more details)
  • sorterParams - additional parameters you can pass to the sorter(see Sorting Data for more details)
  • formatter - set how you would like the data to be formatted (see Formatting Data for more details)
  • formatterParams - additional parameters you can pass to the formatter(see Formatting Data for more details)
  • variableHeight -alter the row height to fit the contents of the cell instead of hiding overflow
  • editable - callback to check if the cell is editable (see Manipulating Data for more details)
  • editor - set the editor to be used when editing the data. (see Manipulating Data for more details)
  • editorParams - additional parameters you can pass to the editor (see Manipulating Data for more details)
  • validator - set the validator to be used to approve data when a user edits a cell. (see Manipulating Data for more details)
  • mutator - function for manipulating column values as they are parsed into the table (see Mutators for more details)
  • mutatorParams - additional parameters you can pass to the mutator(see Mutators for more details)
  • mutatorData New - function for manipulating column values as they are parsed into the table by command (see Mutators for more details)
  • mutatorDataParams New - additional parameters you can pass to the mutatorData(see Mutators for more details)
  • mutatorEdit New - function for manipulating column values as they are edited by a user (see Mutators for more details)
  • mutatorEditParams New - additional parameters you can pass to the mutatorEdit(see Mutators for more details)
  • mutatorClipboard New - function for manipulating column values as they are pasted by a user (see Mutators for more details)
  • mutatorClipboardParams New - additional parameters you can pass to the mutatorClipboard(see Mutators for more details)
  • accessor - function to alter column values before they are extracted from the table function (see Accessors for more details)
  • accessorParams - additional parameters you can pass to the accessor(see Accessors for more details)
  • accessorData New - function to alter column values before they are extracted from the table using the getData function (see Accessors for more details)
  • accessorDataParams New - additional parameters you can pass to the accessorData(see Accessors for more details)
  • accessorDownload New - function to alter column values before they are included in a file download (see Accessors for more details)
  • accessorDownloadParams New - additional parameters you can pass to the accessorDownload(see Accessors for more details)
  • accessorClipboard New - function to alter column values before they are copied to the clipboard (see Accessors for more details)
  • accessorClipboardParams New - additional parameters you can pass to the accessorClipboard(see Accessors for more details)
  • download - show or hide column in downloaded data (see Downloading Table Data for more details)
  • downloadTitle - set custom title for column in download (see Downloading Table Data for more details)
  • topCalc - the column calculation to be displayed at the top of this column(see Column Calculations for more details)
  • topCalcParams - additional parameters you can pass to the topCalc calculation function (see Column Calculations for more details)
  • topCalcFormatter - formatter for the topCalc calculation cell(see Column Calculations for more details)
  • topCalcFormatterParams - additional parameters you can pass to the topCalcFormatter function(see Column Calculations for more details)
  • bottomCalc - the column calculation to be displayed at the bottom of this column(see Column Calculations for more details)
  • bottomCalcParams - additional parameters you can pass to the bottomCalc calculation function(see Column Calculations for more details)
  • bottomCalcFormatter - formatter for the bottomCalc calculation cell(see Column Calculations for more details)
  • bottomCalcFormatterParams - additional parameters you can pass to the bottomCalcFormatter function(see Column Calculations for more details)

Cell Events

  • cellClick - callback for when user clicks on a cell in this column (see Callbacks for more details)
  • cellDblClick - callback for when user double clicks on a cell in this column (see Callbacks for more details)
  • cellContext - callback for when user right clicks on a cell in this column (see Callbacks for more details)
  • cellTap - callback for when user taps on a cell in this column, triggered in touch displays. (see Callbacks for more details)
  • cellDblTap - callback for when user double taps on a cell in this column, triggered in touch displays when a user taps the same cell twice in under 300ms. (see Callbacks for more details)
  • cellTapHold - callback for when user taps and holds on a cell in this column, triggered in touch displays when a user taps and holds the same cell for 1 second. (see Callbacks for more details)
  • cellEditing - callback for when a cell in this column is being edited by the user (see Callbacks for more details)
  • cellEdited - callback for when a cell in this column has been edited by the user (see Callbacks for more details)
  • cellEditCancelled - callback for when an edit on a cell in this column is aborted by the user (see Callbacks for more details)

Column Headers

  • headerSort - user can sort by clicking on the header (see Sorting Data for more details)
  • headerSortStartingDir New - set the starting sort direction when a user first clicks on a header (see Sorting Data for more details)
  • headerClick - callback for when user clicks on the header for this column (see Callbacks for more details)
  • headerDblClick - callback for when user double clicks on the header for this column (see Callbacks for more details)
  • headerContext - callback for when user right clicks on the header for this column (see Callbacks for more details)
  • headerTap - callback for when user taps on a header for this column, triggered in touch displays. (see Callbacks for more details)
  • headerDblTap - callback for when user double taps on a header for this column, triggered in touch displays when a user taps the same header twice in under 300ms. (see Callbacks for more details)
  • headerTapHold - callback for when user taps and holds on a header for this column, triggered in touch displays when a user taps and holds the same header for 1 second. (see Callbacks for more details)
  • headerTooltip - sets the on hover tooltip for the column header (see Formatting Data for more details)
  • editableTitle - allows the user to edit the header titles. (see Editable Column Titles for more details)
  • titleFormatter - formatter function for header title (see Formatting Data for more details)
  • titleFormatterParams - additional parameters you can pass to the header title formatter(see Formatting Data for more details)
  • headerFilter - filtering of columns from elements in the header (see Header Filtering for more details)
  • headerFilterPlaceholder - placeholder text for the header filter (see Header Filtering for more details)
  • headerFilterParams - additional parameters you can pass to the header filter (see Header Filtering for more details)
  • headerFilterFunc - the filter function that should be used by the header filter (see Header Filtering for more details)
  • headerFilterFuncParams - additional parameters object passed to the headerFilterFunc function (see Header Filtering for more details)

Setting Fields In Nested Data

Tabulator can handle linking columns to fields inside nested data objects. To do this you specify the route to your data using dot notation.

For example here is a basic row data object with data nested inside a user object

{
    id:1,
    user:{
        name:"steve",
        age:23
    },
    col:"red",
    cheese:true
},

If you wanted to make a column that showed the name field inside the user object you could set the field property of the column definition object to user.name

$("#example-table").tabulator({
    columns:[
        {title:"Name", field:"user.name"},  //link column to name property of user object
    ],
});

Note: This functionality is only available for nested objects and will not work with arrays.

Column Grouping

You can group column headers togeather to create complex multi-row table headers.

To group columns, you need to add a column group object in the column definition array. You must give a column group a title and add the grouped column objects into the columns property of the group.

You can use the columnVertAlign option to set how the text in your column headers should be vertically aligned, this can take one of three string values: "top", "middle", "bottom"

You can nest column groups, so you can create column groups many levels deep.

$("#example-table-column-grouping").tabulator({
    columnVertAlign:"bottom", //align header contents to bottom of cell
    columns:[
        {title:"Name", field:"name", width:160},
        {//create column group
            title:"Work Info",
            columns:[
                {title:"Progress", field:"progress", align:"right", sorter:"number", width:100},
                {title:"Rating", field:"rating", align:"center", width:80},
                {title:"Driver", field:"car", align:"center", width:80},
            ],
        },
        {//create column group
            title:"Personal Info",
            columns:[
                {title:"Gender", field:"gender", width:90},
                {title:"Favourite Color", field:"col", width:140},
                {title:"Date Of Birth", field:"dob", align:"center", sorter:"date", width:130},
            ],
        },
    ],
});

Available Options

As well as the required title and columns options, the following options can also be set on a column group:

  • headerClick - callback for when user clicks on the header for this column group (see Callbacks for more details)
  • headerDblClick - callback for when user double clicks on the header for this column group (see Callbacks for more details)
  • headerContext - callback for when user right clicks on the header for this column group (see Callbacks for more details)

Note: any of the click callbacks on the group header will also be triggered by clicking on any of the column headers in the group. To prevent this from happening put a matching binding on the column header and use the e.stopPropagation() function to prevent the group binding from being triggered.

Set Table Data

Tabulator row data is defined as an array of objects, that can either be passed as an array or retrieved as a JSON formatted string via AJAX from a URL.

The data can contain more columns that are defined in the columns options, these will be stored with the rest of the data, but not rendered to screen.

An example JSON data set:

[
    {id:1, name:"Billy Bob", age:"12", gender:"male", height:1, col:"red", dob:"", cheese:1},
    {id:2, name:"Mary May", age:"1", gender:"female", height:2, col:"blue", dob:"14/05/1982", cheese:true},
    {id:3, name:"Christine Lobowski", age:"42", height:0, col:"green", dob:"22/05/1982", cheese:"true"},
    {id:4, name:"Brendon Philips", age:"125", gender:"male", height:1, col:"orange", dob:"01/08/1980"},
    {id:5, name:"Margret Marmajuke", age:"16", gender:"female", height:5, col:"yellow", dob:"31/01/1999"},
    {id:6, name:"Billy Bob", age:"12", gender:"male", height:1, col:"red", dob:"", cheese:1},
    {id:7, name:"Mary May", age:"1", gender:"female", height:2, col:"blue", dob:"14/05/1982", cheese:true},
    {id:8, name:"Christine Lobowski", age:"42", height:0, col:"green", dob:"22/05/1982", cheese:"true"},
    {id:9, name:"Brendon Philips", age:"125", gender:"male", height:1, col:"orange", dob:"01/08/1980"},
    {id:10, name:"Margret Marmajuke", age:"16", gender:"female", height:5, col:"yellow", dob:"31/01/1999"},
]

Data Mutation

Note: if you have defined any mutator functions in your column definition array, these will be applied to your data as it is being parsed into the table. (see Mutators for more details)

Row Index

A unique index value should be present for each row of data if you want to be able to programatically alter that data at a later point, this should be either numeric or a string. By default Tabulator will look for this value in the id field for the data. If you wish to use a different field as the index, set this using the index option parameter.

$("#example-table").tabulator({
    index:"age", //set the index field to the "age" field.
});

Set data using array

You can pass an array directly to the table using the setData method.

var tableData = [
    {id:1, name:"Billy Bob", age:"12", gender:"male", height:1, col:"red", dob:"", cheese:1},
    {id:2, name:"Mary May", age:"1", gender:"female", height:2, col:"blue", dob:"14/05/1982", cheese:true},
]

$("#example-table").tabulator("setData", tableData);

Set Initial Data Array

If you want your table to be created already containing data, then you can pass the array into the data option in the table constructor.

var tableData = [
    {id:1, name:"Billy Bob", age:"12", gender:"male", height:1, col:"red", dob:"", cheese:1},
    {id:2, name:"Mary May", age:"1", gender:"female", height:2, col:"blue", dob:"14/05/1982", cheese:true},
]

$("#example-table").tabulator({
    data:tableData, //set initial table data
    columns:[
        {title:"Name", field:"name"},
        {title:"Age", field:"age"},
        {title:"Gender", field:"gender"},
        {title:"Height", field:"height"},
        {title:"Favourite Color", field:"col"},
        {title:"Date Of Birth", field:"dob"},
        {title:"Cheese Preference", field:"cheese"},
    ],
});

Set Data at Table Creation

You can set the data at the same time as the table creation by passing the data array to the data option.

var dataArray = [
    {id:1, name:"Billy Bob", age:"12", gender:"male", height:1, col:"red", dob:"", cheese:1},
    {id:2, name:"Mary May", age:"1", gender:"female", height:2, col:"blue", dob:"14/05/1982", cheese:true},
]

$("#example-table").tabulator({
    data:dataArray,
});

Set data using AJAX

If you wish to retrieve your data from a remote source, pass the URL to the setData method and it will perform the AJAX request for you. The URL can be absolute or relative.

$("#example-table").tabulator("setData","http://www.getmydata.com/now");

If you wish to pass parameters with your request you can either include them in-line with the url string, or as an optional second parameter to the setData function. In the latter case they should be provided in the form of an object with key/value pairs.

$("#example-table").tabulator("setData","http://www.getmydata.com/now", {key1:"value1", key2:"value2"});

The server will need to return a JSON formatted array of objects.

Advanced Configuration

By default Tabulator will make all ajax requests using the HTTP request type of GET. If you need to use a different request type for any reason, this can be passed as an optional third parameter.

$("#example-table").tabulator("setData","http://www.getmydata.com/now", {}, "POST"); //make a post request

The third parameter can also be used to pass a config object containing any of the options from the standard jQuery ajax configuration object:

var ajaxConfig = {
    type:"POST", //set request type to Position
    contentType: 'application/json; charset=utf-8', //set specific content type
};

$("#example-table").tabulator("setData","http://www.getmydata.com/now", {}, ajaxConfig); //make ajax request with advanced config options

A full list of the available config options can be found on the jQuery website.

Note: You MUST NOT set any of the following options in the advanced config option as they are set by Tabulator and needed for correct operation of the library:

  • url
  • async
  • dataType
  • success
  • error

Repeated Requests

If you always request the same url for your data then you can set it in the ajaxURL, ajaxParams & ajaxConfig options as needed when you create your Tabulator. This will cause the table to immediately load the data from the remote resource as soon as the table is created. These options take the same input options as the first second and third arguments of the setData function.

$("#example-table").tabulator({
    ajaxURL:"http://www.getmydata.com/now", //ajax URL
    ajaxParams:{key1:"value1", key2:"value2"}, //ajax parameters
    ajaxConfig:"POST", //ajax HTTP request type
});

You can call the setData function to refresh the data at any point

$("#example-table").tabulator("setData");

Ajax Response Alteration

Tabulator expects the response to an ajax request to be a JSON encoded string representing an array of data objects. If you need to pass other data back in your request as well, you can use the ajaxResponse callback to process the returned data before it is passed to the table. The return value of this callback should be an array of row data objects.

$("#example-table").tabulator({
    ajaxResponse:function(url, params, response){
        //url - the URL of the request
        //params - the parameters passed with the request
        //response - the JSON object returned in the body of the response.

        return response.tableData; //return the tableData peroperty of a response json object
    },
});

Ajax Filtering

If you would prefer to filter your data server side rather than in Tabulator, you can use the ajaxFiltering option to send the filter data to the server instead of processing it client side

$("#example-table").tabulator({
    ajaxFiltering:true, //send filter data to the server instead of processing locally
});

An array of filters objects will then be passed in the filters parameter of the request, the name of this parameter can be set in the in the paginationDataSent option, in the pagination extension.

The array of filter objects will take the same form as those returned from the getFilters function:

[
    {field:"age", type:">", value:52}, //filter by age greater than 52
    {field:"height", type:"<", value:142}, //and by height less than 142
]

If a custom filter function is being used then the type parameter will have a value of "function".

If the table is not currently filtered then the array will be empty.

Ajax Sorting

If you would prefer to sort your data server side rather than in Tabulator, you can use the ajaxSorting option to send the sort data to the server instead of processing it client side

$("#example-table").tabulator({
    ajaxSorting:true, //send sort data to the server instead of processing locally
});

An array of sorters objects will then be passed in the sorters parameter of the request, the name of this parameter can be set in the in the paginationDataSent option, in the pagination extension.

The array of sorter objects will take the same form as those returned from the getSorters function:

[
    {
        column:column,
        field:"age",
        dir:"asc"
    },
    {
        column:column,
        field:"height"
        dir:"desc"
    }
]

If the table is not currently sorted then the array will be empty.

Get Current Ajax URL

You can retrieve the current AJAX URL of the table with the gtAjaxUrl function.

var url = $("#example-table").tabulator("gtAjaxUrl");

Note: This function will return the url set on the ajaxURL property or the latest url set with the setData function, it will not include any pagination, filter or sorter parameters

Aborting an Ajax Request

The ajaxRequesting callback is called just before an AJAX request is made, if you want to abort the request for any reason you can return a value of false from the function.

$("#example-table").tabulator({
    ajaxRequesting:function(url, params){
        return false; //abort ajax request
    },
});

Callbacks

A range of callbacks are avaialble for tracking progress of ajax data loading. See the Ajax Callbacks section for more information.

Server Side Code (PHP)

When using ajax loading, the server should respond with a JSON encoded string representing an array of row objects. An example in PHP can be seen below:

//build data array
$data = array(
    array(id=>1, name=>"Billy Bob", age=>"12", gender=>"male", height=>1, col=>"red", dob=>"", cheese=>1),
    array(id=>2, name=>"Mary May", age=>"1", gender=>"female", height=>2, col=>"blue", dob=>"14/05/1982", cheese=>true),
    array(id=>3, name=>"Christine Lobowski", age=>"42", height=>0, col=>"green", dob=>"22/05/1982", cheese=>"true"),
    array(id=>4, name=>"Brendon Philips", age=>"125", gender=>"male", height=>1, col=>"orange", dob=>"01/08/1980"),
    array(id=>5, name=>"Margret Marmajuke", age=>"16", gender=>"female", height=>5, col=>"yellow", dob=>"31/01/1999"),
);

//return JSON formatted data
echo(json_encode($data));

Progressive Ajax Loading New

If you are loading a lot of data from a remote source into your table in one go, it can sometimes take a long time for the server to return the request, which can slow down the user experience.

To speed things up in this situation Tabulator has a progressive load mode, this uses the pagination extension to make a series of requests for part of the data set, one at a time, appending it to the table as the data arrives. This mode can be enable using the ajaxProgressiveLoad option. No pagination controls will be visible on screen, it just reusues the functionality of the pagination extension to sequentially load the data.

With this mode enabled, all of the settings outlined in the Ajax Documentation are still available

There are two different progressive loading modes, to give you a choice of how data is loaded into the table.

Load Mode

In load mode the table will sequentially add each page of data into the table untill all data is loaded.

$("#example-table").tabulator({
    ajaxURL:"http://www.getmydata.com/now", //ajax URL
    ajaxProgressiveLoad:"load", //sequentially load all data into the table
});

By default tabulator will make the requests to fill the table as quickly as possible. On some servers these repeates requests from the same client may trigger rate limiting or security systems. In this case you can use the ajaxProgressiveLoadDelay option to add a delay in milliseconds between each page request.

$("#example-table").tabulator({
    ajaxURL:"http://www.getmydata.com/now", //ajax URL
    ajaxProgressiveLoad:true, enable progressive loading
    ajaxProgressiveLoadDelay:200 //wait 200 milliseconds between each request
});

Scroll Mode

In scroll mode Tabulator will initially load enough data into the table to fill the visible area of the table plus the scroll margin.

Whenever the user scrolls down vertically, if they are with the the scroll margin of the bottom of the table an ajax request will be triggered for the next page worth of data.

$("#example-table").tabulator({
    ajaxURL:"http://www.getmydata.com/now", //ajax URL
    ajaxProgressiveLoad:"scroll", //load data into the table as the user scrolls
});

The ajaxProgressiveLoadScrollMargin property determines how close to the bottom of the table in pixels, the scroll bar must be before the next page worth of data is loaded, by default it is set to twice the height of the table.

$("#example-table").tabulator({
    ajaxURL:"http://www.getmydata.com/now", //ajax URL
    ajaxProgressiveLoad:true, enable progressive loading
    ajaxProgressiveLoadScrollMargin:300 //triger next ajax load when scroll bar is 300px or less from the bottom of the table.
});

Scroll Margin Size
to ensure a good user experience, you should make sure you have a reasonably large scroll margin, to give your users room to scroll while the data is being loaded from the server.

Returned Response Data

When using progressive loading the data returned from the server will need to be formatted for pagination.

{
    "last_page":15, //the total number of available pages (this value must be greater than 0)
    "data":[ // an array of row data objects
        {id:1, name:"bob", age:"23"}, //example row data object
    ]
}

All the ususal pagination options, such as paginationSize, paginationDataSent etc can be used in this mode, you can find out more about the options and expected response in the Remote Pagination Documentation

Page Size
For the best user experience, it is recomended that the number of records sent per page be at least enough to fill the height of the table.

Blocking Progressive Load
Calling any of the setData or updateData type functions will cause any active progressive loading to halt to prevent an uncontrolled mix of local and remote data

Extract Data from an HTML Table Element

You can create a Tabulator table directly from an HTML table element. You can define the columns in the usual way with the columns option, or you can set them as th elements in the thead of a table.

Any rows of data in the tbody of the table will automatically be converted to tabulator data in displayed in the resulting table.

If you define the width attribute in a table header cell, this will be used to set the width of the column in Tabulator.

<table id="example-table">
    <thead>
        <tr>
            <th width="200">Name</th>
            <th>Age</th>
            <th>Gender</th>
            <th>Height</th>
            <th>Favourite Color</th>
            <th>Date of Birth</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Billy Bob</td>
            <td>12</td>
            <td>male</td>
            <td>1</td>
            <td>red</td>
            <td></td>
        </tr>
        <tr>
            <td>Mary May</td>
            <td>1</td>
            <td>female</td>
            <td>2</td>
            <td>blue</td>
            <td>14/05/1982</td>
        </tr>
    </tbody>
</table>
$("#example-table").tabulator({});

Note: Tabulator can only parse simple tables. Tables using multiple header rows, colspan or rowspan attributes will cause the import to fail.

Options Attributes

You can set options parameters directly in the HTML by using tabulator- attributes on the table and th elements, these will then be set as configuration options on the table.

Setting option on table:

<table id="example-table" tabulator-tooltips="true">
    <thead>
        <tr>
            <th>Name</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Billy Bob</td>
        </tr>
    </tbody>
</table>

Setting option on row:

<table id="example-table">
    <thead>
        <tr>
            <th tabulator-align="center">Name</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Billy Bob</td>
        </tr>
    </tbody>
</table>

Note: This approach can only be used for text, numeric and boolean options, for callbacks and functions you will need to use the constructor object outlined below.

Complex Options Setup

If you need to set up any column options on the imported table you can declare these in table constructor as you would do for any other table. It is important to note that the title parameter for each column definition must match the text in the table element's header cell exactly for the imported data to link to the correct column.

If you use a column definition array in the Tabulator constructor, the order of columns in this array will take priority over the order of the columns in the table element.

$("#example-table").tabulator({
    tooltips:true, //example option (enable tooltips on all cells)
    columns:[ //set column definitions for imported table data
        {title:"Age", sorter:"number"},
        {title:"Height", sorter:"number"},
        {title:"Date of Birth", sorter:"date"},
    ],
});

Mutators & Accessors Updated

Mutators (setters) and Accessors (getters) allow you to manipulate the table data as it enters and leaves your Tabulator, allowing you to convert values for use in your table and then change them again as they leave.

Mutators Updated

Mutators are used to alter data as it is parsed into Tabulator. For example if you wanted to convert a numeric column into a boolean based on its value, before the data is used to build the table.

You can set mutators on a per column basis using the mutator option in the column definition object.

You can pass an optional additional parameter with mutator, mutatorParams that should contain an object with additional information for configuring the mutator.

{title:"Has Too Many Cars", field:"cars", mutatorParams:{threshold:5}, mutator:function(value, data, type, params, component){
        //value - original value of the cell
        //data - the data for the row
        //type - the type of mutation occuring (data|edit)
        //params - the mutatorParams object from the column definition
        //component - when the "type" argument is "edit", this contains the cell component for the edited cell, otherwise it is the column component for the column

        return value > mutatorParams.threshold; //return the new value for the cell data.
    },
}

Mutation Type Updated

Data can be mutated whenever it enters the table, either through a command or through a user editing the table. To allow you to have more control over how your data is mutated, there are a variety of different mutation options you can pass your callback to instead of just the mutator callback.

There are four options for mutator callbacks

  • mutatorData - only called when data is loaded via a command {eg. setData).
  • mutatorEdit - only called when data is changed via a user editing a cell.
  • mutatorClipboard - only called when data is pasted into the table.
  • mutator - called if the matching mutator from the above list is not set.

Each mutator function has its own matching params option, for example mutatorData has mutatorDataParams.

The example below will use the mutatorEdit function if a cell edit is performed otherwise it will use the mutator funcion.

var ageMutator = function(value, data, type, params, component){
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", mutator:ageMutator, mutatorParams:{legalAge:16}, mutatorEdit:ageMutator, mutatorEditParams:{legalAge:18} }

Mutators vs Formatters
An important difference between a mutator and a formatter is that a mutator will alter the data contained in the table, which will then be visible in the data retrieved using the getData function, a formatter will only alter how data is displayed in cells but will not affect the data itself. (see Formatting for more details)

Accessors Updated

Accessors are used to alter data as it is extracted from the table, through commands, the clipboard, or download.

You can set accessors on a per column basis using the accessor option in the column definition object.

You can pass an optional additional parameter with accessor, accessorParams that should contain an object with additional information for configuring the accessor.

The example below shows a usage case that ensures float values in a column are rounded down to integers before you retrieved the data.

{title:"Tax Owed (£)", field:"tax", accessorParams:{}, accessor:function(value, data, type, params, column){
        //value - original value of the cell
        //data - the data for the row
        //type - the type of access occuring (data|download|clipboard)
        //params - the accessorParams object passed from the column definition
        //column - column component for the column this accessor is bound to

        return Math.floor(value); //return the new value for the cell data.
    },
}

Accessor Type New

Data can be altered whenever it enters the table, either through a command or through a clipboard copy event or through a download of the table. To allow you to have more control over how your data is altered, there are a variety of different accessor options you can pass your callback to instead of just the accessor callback.

There are four options for accessor callbacks

  • accessorData - only called when data is extracted via a command {eg. getData).
  • accessorDownload - only called when data is being converted into a downloadable file.
  • accessorClipboard - only called when data is being copied into the clipboard.
  • accessor - called if the matching accessor from the above list is not set.

Each accessor function has its own matching params option, for example accessorDownload has accessorDownloadParams.

The example below will use the accessorDownload function if a data is downloaded to a file accessor funcion.

var ageAccessor = function(value, data, type, params, column){
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", accessor:ageAccessor, accessorParams:{legalAge:16} accessorDownload:ageAccessor, accessorDownloadParams:{legalAge:18} }

Formatting Data Updated

Tabulator allows you to format your data in a wide variety of ways, so your tables can display information in a more graphical and clear layout.

You can set formatters on a per column basis using the formatter option in the column definition object.

You can pass an optional additional parameter with the formatter, formatterParams that should contain an object with additional information for configuring the formatter.

{title:"Name", field:"name", formatter:"star", formatterParams:{stars:6}}

Tabulator comes with a number of preconfigured formatters including:

  • plaintext - This is the default formatter for all cells, and simply displays the value of the cell as text.
  • textarea - shows text with carriage returns intact (great for multiline text), this formatter will also adjust the height of rows to fit the cells contents when columns are resized
  • html - displays un-sanitized html
  • money - formats a number into currency notation (eg. 1234567.8901 -> 1,234,567.89)
    • optional formatterParams:
      • decimal - Symbol to represent the decimal point (default ".")
      • thousand - Symbol to represent the thousands seperator (default ",")
      • symbol - currency symbol (no default)
      • symbolAfter - position the symbol after the number (default false)
      • precision - the number of decimals to display (default is 2), setting this value to false will display however many decimals are provided with the number
  • image - creates an img element wirh the src set as the value. (triggers the normalizeHeight function on the row on image load)
  • link - renders data as an anchor with a link to the given value (by default the value will be used as both the url and the label of the tag)
    • optional formatterParams:
      • labelField - the field in the row data that should be used for the link lable
      • label - a string representing the lable, or a function which must return the string for the label, the function is passed the Cell Component as its first argument
      • urlPrefix - a prefix to put before the url value (eg. to turn a emaill address into a clickable mailto link you should set this to "mailto:")
      • urlField - the field in the row data that should be used for the link url
      • url - a string representing the url, or a function which must return the string for the url, the function is passed the Cell Component as its first argument
  • tick - displays a green tick if the value is (true|'true'|'True'|1) and an empty cell if not
  • tickCross - displays a green tick if the value is (true|'true'|'True'|1) and a red cross if not
  • color - sets the background colour of the cell to the value. Can be any valid CSS color eg. #ff0000, #f00, rgb(255,0,0), red, rgba(255,0,0,0), hsl(0, 100%, 50%)
  • star - displays a graphical star rating based on integer values
    • optional formatterParams:
      • stars - maximum number of stars to be displayed (default 5)
  • progress Updated - displays a progress bar that fills the cell from left to right, using values 0-100 as a percentage of width
    • optional formatterParams:
      • min - minimum value for progress bar (default 0)
      • max - minimum value for progress bar (default 100)
      • color - colour of progress bar (default #2DC214), this can be:
        • string - any valid css color string (eg "#fff000")
        • array of strings - an array of color strings, that will devide the background colour across the min-max range of values(eg ["green", "orange", "red"])
        • function - a callback that is passed the value of the cell and must return the bar color (eg function(value){return "red"})
      • legend - a text value to display over the progress bar, this can be:
        • string - any string
        • true - if set to true this will show the value of the cell
        • function - a callback that is passed the value of the cell and must return the legend contents (eg function(value){return value + "%"})
      • legendColor - the text colour for the legend, has the same range of value options as the color property
      • legendAlign New - the text alignment for the legend, this can be:
        • center - center align text (default)
        • left - left align text
        • right - right align text
        • justify - stretch out text to fit line
  • lookup - looks up the value to display from a object passed into the formatterParams property, if not present it displays the current cell value
    • pass an object to formatterParams where the initial value of the cell is the property key and the value to be displayed is the property value (eg {"blue":"black", "red":"green"}, would change the value "blue" to "black", and the value "red" to green)
  • buttonTick - displays a tick icon on each row (for use as a button)
  • buttonCross - displays a cross icon on each row (for use as a button)
  • rownum - shows an incrementing row number for each row.
  • handle - fills the cell with hamburger bars, to be used as a row handle

Note: To guard against code injection, any formatters that are meant to display text (plaintext, textarea, money, email, link) have the data sanitized first to escape any potentially harmful HTML or JavaScript from making into the table, this causes any such data to be displayed as its plain text alternative. If you want the HTML to be displayed correctly use the html formatter, but be aware if your data can be user edited this could allow for malicious script injection.

Note: For a guide to adding your own formatters to this list, have a look at the Extending Tabulator section.

Custom Formatters

As well as the built-in formatters you can define a formatter using a custom formatter function.

The formatter function accepts two arguments, the CellComponent for the cell being formatted and the formatterParams option from the column defintion.

The function must return the contents of the cell, either the text value of the cell, valid HTML or a jQuery element.

{title:"Name", field:"name", formatter:function(cell, formatterParams){
        //cell - the cell component
        //formatterParams - parameters set for the column

        return "Mr" + cell.getValue(); //return the contents of the cell;
    },
}

Formatters vs Mutators
An important difference between a formatter and a mutator is that a formatter will only alter how data is displayed in cells but will not affect the data itself, while a mutator will alter the data contained in the table, which will then be visible in the data retrieved using the getData function. (see Mutators for more details)

Variable Height Formatters

By default formatters will keep their contents within the height of the current row, hiding any overflow. The only exception to this is the textarea formatter which will automatically vary its height when the column is resized so its contents does not overflow.

If you would like this functionally to appear in another type of formatter you can set the variableHeight property to true in the column definition and it will will behave in a similar way to the textarea formatter:

{title:"Name", field:"name", formatter:myCustomFormatter, variableHeight:true}

Icon/Button Columns

You can create icon/button columns, by not specifying the field option in the column definition object and creating a custom formatter for the column contents. In the example below we have created a print button on the left of each row.

//custom formatter definition
var printIcon = function(cell, formatterParams){ //plain text value
    return "<i class='fa fa-print'></i>";
};

//column definition in the columns array
{formatter:printIcon, width:40, align:"center", cellClick:function(e, cell){alert("Printing row data for: " + cell.getRow().getData().name)}},

Row Formatting

Tabulator also allows you to define a row level formatter using the rowFormatter option. this lets you alter each row of the table based on the data it contains.

The function accepts one argument, the RowComponent for the row being formatted.

The example below changes the background colour of a row to blue if the col value for that row is "blue".

$("#example-table").tabulator({
    rowFormatter:function(row){
        //row - row component

        var data = row.getData();

        if(data.col == "blue"){
            row.getElement().css({"background-color":"#A6A6DF"});
        }
    },
});

Re-Format Row

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 on its Row Component.

row.reformat();

ToolTips Updated

You can set tooltips to be displayed when the cursor hovers over cells. By default, tooltips are not displayed.

Tooltips can either be set globally using the tooltips options parameter:

$("#example-table").tabulator({
    tooltips:true,
});

Or on a per column basis in the column definition array:

//column definition in the columns array
{formatter:printIcon, width:40, align:"center", tooltip:true},

The tooltip parameter can take three different types of value

  • boolean - a value of false disables the tooltip, a value of true sets the tooltip of the cell to its value
  • string - a string that will be displayed for all cells in the matching column/table.
  • function - a callback function that returns the string for the cell. see below:

The function accepts one argument, the CellComponent for the cell the tooltip is being generated for.

$("#example-table").tabulator({
    tooltips:function(cell){
        //cell - cell component

        //function should return a string for the tooltip of false to hide the tooltip
        return  cell.getColumn().getField() + " - " + cell.getValue(); //return cells "field - value";
    },
});

Note: setting a tooltip value on a column will override the global setting.

Tooltip Generation Mode New

By default Tabulator regenerates tooltips whenever data in a cell changes, however if you use a tooltip generation function that is dependant on values outside the cell this may mean the tooltip does not update as expected.

To get round this, you can use the tooltipGenerationMode parameter to make tooltips regenerate whenever the users mouse enters the cell. The parameter can have one of two values

  • load - Generate tooltip when value is loaded into cell (default behaviour)
  • hover - Generate tooltip when users mouse enters the cell
$("#example-table").tabulator({
    tooltipGenerationMode:"hover", //regenereate tooltip as users mouse enters the cell;
});

Column Header ToolTips

It is also possible to set tooltips to display on the column headers. This is particularly useful when your columns are too narrow to display full header names.

Header tooltips can either be set globally using the tooltipsHeader options parameter:

$("#example-table").tabulator({
    tooltipsHeader:true, //enable header tooltips
});

Or on a per column basis in the column definition array:

//column definition in the columns array
{title:"name", field:"name", width:40, align:"center", headerTooltip:true},

The tooltip headerTooltip can take three different types of value

  • boolean - a value of false disables the tooltip, a value of true sets the tooltip of the column header to its title value.
  • string - a string that will be displayed for the tooltip.
  • function - a callback function that returns the string for the column header. see below:

The function accepts one argument, the ColumnComponent for the column the tooltip is being generated for.

$("#example-table").tabulator({
    tooltips:function(column){
        //column - column component

        //function should return a string for the header tooltip of false to hide the tooltip
        return  column.getDefinition().title;
    },
});

Note: setting a headerTooltip value on a column will override the global setting.

Column Header Title Formatters

You can use formatters to layout your column titles using the titleFormatter and titleFormatterParams options in a column's defintition object:

//column definition in the columns array
{title:5, titleFormatter:"star", titleFormatterParams:{stars:5}, field:"rating"},

Filtering Data Updated

Tabulator allows you to filter the table data by any field in the data set.

To set a filter you need to call the setFilter method, passing the field you wish to filter, the comparison type and the value to filter for.

This funtion will replace any exiting filters on the table with the specified filters.

$("#example-table").tabulator("setFilter", "age", ">", 10);

Tabulator comes with a number of filter comparison types including:

  • = - Displays only rows with data that is the same as the filter
  • < - displays rows with a value less than the filter value
  • <= - displays rows with a value less than or qual to the filter value
  • > - displays rows with a value greater than the filter value
  • >= - displays rows with a value greater than or qual to the filter value
  • != - displays rows with a value that is not equal to the filter value
  • like - displays any rows with data that contains the specified string anywhere in the specified field. (case insesitive)
  • in - displays any rows with a value in the filter value array passed to the filter (eg ["steve", "bob", "jim"], values must be of the same type as they are in the array

If you wish to apply multiple filters then you can pass an array of filter objects to this function, the data will then have to pass all filters to be displayed in the table.

$("#example-table").tabulator("setFilter", [
    {field:"age", type:">", value:52}, //filter by age greater than 52
    {field:"height", type:"<", value:142}, //and by height less than 142
    {field:"name", type:"in", value:["steve", "bob", "jim"]}, //name must be steve, bob or jim
]);

Filters will remain in effect until they are cleared, including during setData calls.

Complex Filtering New

The filtering example above shows how to apply a series of filters to some table data and show only the data where all the filters are matched, but what if you want to use an OR type comparison.

To do this you can put an array of filters inside your filter array, and any filters in this second array will use an OR comparison type.

The example below applies a filter that will let through rows with a age of greater than 52 AND (either a height of less than 142 OR with the name steve)

$("#example-table").tabulator("setFilter", [
    {field:"age", type:">", value:52}, //filter by age greater than 52
    [
        {field:"height", type:"<", value:142}, //with a height of less than 142
        {field:"name", type:"=", value:"steve"}, //or a name of steve
    ]
]);

You can nest OR filter arrays several levels deep to build up complex filters.

Custom Filter Functions

If you want to perform a more complicated filter then you can pass a callback function to the setFilter method, you can also pass an optional second argument, an object with parameters to be passed to the filter function.

function customFilter(data, filterParams){
    //data - the data for the row being filtered
    //filterParams - params object passed to the filter

    return data.name == "bob" && data.height < filterParams.height; //must return a boolean, true if it passes the filter.
}

$("#example-table").tabulator("setFilter", customFilter, {height:3});

Additional Filter Functions

There are a number of additional filter functions that can be called to customise your filtering experience

Add Filter to Exsiting Filters

If you want to add another filter to the existing filters then you can call the addFilter function:

$("#example-table").tabulator("addFilter", "age", ">", 22);

Remove One of Many Existing Filters

If you want to remove one filter from the current list of filters you can use the removeFilter function:

$("#example-table").tabulator("removeFilter", "age", ">", 22);

Get Current Filters

You can retrieve an array of the current programtic filters using the getFilters function, this will not include any of the header filters:

var filters = $("#example-table").tabulator("getFilters");

This will return an array of filter objects

[
    {field:"age", type:">", value:52}, //filter by age greater than 52
    {field:"height", type:"<", value:142}, //and by height less than 142
]

To include header filters in the returend array pass an option argument of true to the getFilters function:

var allFilters = $("#example-table").tabulator("getFilters", true);

Get Header Filters

If you just want to retreive the current header filters, you can use the getHeaderFilters function:

var headerFilters = $("#example-table").tabulator("getHeaderFilters");

Clear All Filters

To remove all filters from the table, use the clearFilter function.

$("#example-table").tabulator("clearFilter");

This will clear all programatically set filters, if you wisht to clear all header filters as well pass an argument of true to this function.

$("#example-table").tabulator("clearFilter", true);

Clear Header Filters

To remove just the header filters, leaving the programatic filters in place, use the clearHeaderFilter function.

$("#example-table").tabulator("clearHeaderFilter");

Header Filtering

Is is possible to filter the table data directly from the column headers, by setting the headerFilter parameter in the column definition object for that column.

{title:"Name", field:"name", headerFilter:true} //show header filter matching the cells editor

Setting this parameter to true will cause an editor element matching the columns editor type to be displayed in the header below the column title, and will allow the user to filter data in the table by values in that column. The editor will be chosen using the same rules as the editor parameter, for more information on this see the Manipulating Data section.

Alternatively you can pass a string to this parameter containing any of the standard editors listed in the Manipulating Data section

{title:"Name", field:"name", headerFilter:"input"} //show headerFilter using "input" editor

You can also pass a custom editor function to this parameter in the same way as you would for column editor. For more information see the Manipulating Data section.

You can pass an optional additional parameter with the header filter, headerFilterParams that should contain an object with additional information for configuring the header filter element. This will be passed to the editor in the column header instead of the editorParams property.

{title:"Name", field:"name", headerFilter:"input", headerFilterParams:{initial:"Steve Bobberson"}} //show headerFilter using "input" editor

Note: At present, the progress and star editors are not available as header filters.

Header Filters and Programmatic Filters

Header filters and programatic filters can be set independently allowing you to use a header filter to further restrict the rows shown in an already filtered data set.

Real Time Filtering

If an input element is used as the filter element, then then the table will be filtered in real time as the user types in the input element. To prevent exessive redrawing of the table Tabulator will wait 300 miliseconds after the user has finished typing before tirggering the filter, this ensures that the table is not redrawn for every character typed by the user.

Note: If the input has a type attribute value of text it will be automatically changed to search to give the user the option to clear the input text.

Filter Comparison Types

By default Tabulator will try and match the comparison type to the type of element used for the header filter.

Standard input elements will use the "like" filter, this allows for the matches to be displayed as the user types.

For all other element types (select boxes, check boxes, input elements of type number) an "=" filter type is used.

If you want to specify the type of filter used you can pass it to the headerFilterFunc option in the column definition object. This will take any of the standard filters outlined above or a custom function:

{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:"<="} //show only rows with an age less than or equal the entered value

When using a custom filter function for a header filter, the arguments passed to the function will be slightly different from a normal custom filter function

function customHeaderFilter(headerValue, rowValue, rowData, filterParams){
    //headerValue - the value of the header filter element
    //rowValue - the value of the column in this row
    //rowData - the data for the row being filtered
    //filterParams - params object passed to the headerFilterFuncParams property

    return rowData.name == filterParams.name && rowValue < headerValue; //must return a boolean, true if it passes the filter.
}

//column defintion object in table constructor
{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:customHeaderFilter, headerFilterFuncParams:{name:"bob"}}

As the above example demostrates it is possible to pass additional parameters to the custom filter function by passing an object to the headerFilterFuncParams option in the column definition.

{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:customHeaderFilter, headerFilterFuncParams:{name:"bob"}}

Placeholder Text

The default placeholder text used for input elements can be set using the headerFilterPlaceholder option in the table definition

$("#example-table").tabulator({
    headerFilterPlaceholder:"filter data...", //set column header placeholder text
});

To set the placeholder text on a per column basis you can use the headerFilterPlaceholder option in the column's definition object.

$("#example-table").tabulator({
    headerFilterPlaceholder:"filter data...", //set column header placeholder text
    columns:[
        {title:"Name", field:"name", headerFilter:true, headerFilterPlaceholder:"Find a Person..."} //set placeholder text on name column header filter
    ]
});

Set Header Filter Value

You can programatically set the header filter value of a column by calling the setHeaderFilterValue function, This function takes any of the standard column component look up options as its first parameter, with the value for the header filter as the second option

$("#example-table").tabulator("setHeaderFilterValue", "name", "Steve"); //set header filter for name column to  "steve"

Focus On Header Filter

You can programatically set the focus on a header filter element by calling the setHeaderFilterFocus function, This function takes any of the standard column component look up options as its first parameter

$("#example-table").tabulator("setHeaderFilterFocus", "name"); //focus on the header filter for the name column

Callbacks

A range of callbacks are avaialble for tracking progress of filtering. See the Filter Callbacks section for more information.

Sorting Data Updated

Tabulator allows you to sort the data in your table in any way you want.

By default Tabulator will attempt to guess which sorter should be applied to a column based on the data contained in the first row. It can determine sorters for strings, numbers, alphanumeric squences and booleans, anything else will be treated as a string.

To specify a sorter to be used on a column use the param property in the columns definition object

You can pass an optional additional property with sorter, sorterParams that should contain an object with additional information for configuring the sorter.

{title:"Birthday", field:"birthday", sorter:"date", sorterParams:{format:"DD/MM/YY"}}

Tabulator comes with a number of preconfigured sorters including:

  • string - sorts column as strings of characters
    • optional sorterParams:
      • locale - the locale code for the string comparison function, (without this the sorter will use the locale of the browser). it can accept:
        • string - the locale code for the sort
        • boolean - set the value to true to use the current table locale
      • alignEmptyValues New - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
        • top - force empty cells to the top of the table
        • bottom - force empty cells to the bottom of the table
  • number - sorts column as numbers (integer or float, will also handle numbers using "," seperators)
    • optional sorterParams:
      • alignEmptyValues New - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
        • top - force empty cells to the top of the table
        • bottom - force empty cells to the bottom of the table
  • alphanum - sorts column as alpha numeric code
    • optional sorterParams:
      • alignEmptyValues New - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
        • top - force empty cells to the top of the table
        • bottom - force empty cells to the bottom of the table
  • boolean - sorts column as booleans
  • exists - sorts column ordering if value has a type of "undefined" or not
  • date - sorts column as dates
    • You will need to include the moment.js library to use this sorter
    • optional sorterParams:
      • format - the format of the date (default: DD/MM/YYYY)
      • alignEmptyValues New - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
        • top - force empty cells to the top of the table
        • bottom - force empty cells to the bottom of the table
  • time - sorts column as time (formatted as hh:mm)
    • You will need to include the moment.js library to use this sorter
    • optional sorterParams:
      • format - the format of the time (default: hh:mm)
      • alignEmptyValues New - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
        • top - force empty cells to the top of the table
        • bottom - force empty cells to the bottom of the table
  • datetime - sorts column as datetimes
    • You will need to include the moment.js library to use this sorter
    • optional sorterParams:
      • format - the format of the date (default: DD/MM/YYYY hh:mm:ss)
      • alignEmptyValues New - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
        • top - force empty cells to the top of the table
        • bottom - force empty cells to the bottom of the table
  • array - sorts arrays of data
    • optional sorterParams:
      • type - Arrays will be sorted by length by default, this property takes a string for the comparison type:
        • length - sort arrays by length
        • sum - sort arrays by sum of their value
        • max - sort arrays by maximum value
        • min - sort arrays by minimum value
        • avg - sort arrays by average value of all elements
      • alignEmptyValues New - force empty cells to top or bottom of table regardless of sort order, this property takes a string:
        • top - force empty cells to the top of the table
        • bottom - force empty cells to the bottom of the table

Custom Sorters

for advanced sorting can define a custom sorter function in the sorter option:

{title:"Name", field:"name", sorter:function(a, b, aRow, bRow, column, dir, sorterParams){
        //a, b - the two values being compared
        //aRow, bRow - the row components for the values being compared (useful if you need to access additional fields in the row data for the sort)
        //column - the column component for the column being sorted
        //dir - the direction of the sort ("asc" or "desc")
        //sorterParams - sorterParams object from column definition array

        return a - b; //you must return the difference between the two values
    },
}

The fifth parameter in this callback is a ColumnComponent for the column being fitered.

Header Sorting Updated

By default all columns in a table are sortable by clicking on the column header, if you want to disable this behaviour, set the headerSort property to false in the column defintion array:

{title:"Name", field:"name", sorter:"string", headerSort:false} //disable header sorter

You can sort by multiple columns at the same time by holding the ctrl or shift key when you click on the column headers.

Header Sort Direction New

By default Tabulator will sort a column in ascending order when a user first clicks on the column header.

The headerSortStartingDir property in the column definition can be used to set the starting sort direction when a user clicks on an unsorted column, it can either be set to asc or desc.

{title:"Name", field:"name", sorter:"string", headerSortStartingDir:"desc"} //start sorting column in descending order when user clicks on header of unsorted column

Sort Data on Load

When the table is first created it can be setwith an initial set of sorters. These can be set using the initialSort option. This will take the same sorter array as the setSort function. (see Initial Data Sorting for more details)

$("#example-table").tabulator({
    initialSort:[
        {column:"age", dir:"asc"}, //sort by this first
        {column:"height", dir:"desc"}, //then sort by this second
    ]
});

Trigger Sorting Programmatically

You can trigger sorting using the setSort function

$("#example-table").tabulator("setSort", "age", "asc");

If you wish to sort by multiple columns then you can pass an array of sorting objects to this function, the data will then be sorted in the order of the objects.

$("#example-table").tabulator("setSort", [
    {column:"age", dir:"asc"}, //sort by this first
    {column:"height", dir:"desc"}, //then sort by this second
]);

Get Current Sorters

If you need to retrieve the details of the currently sorted column at any point you can use the getSorters function.

$("#example-table").tabulator("getSorters");

This will return an array of sort objects with three properties, column the column component for the sorted column, field a string of the field name for the sorted column, and dir a string of either "asc" or "desc" indicating the direction of sort.

[
    {
        column:column,
        field:"age",
        dir:"asc"
    },
    {
        column:column,
        field:"height"
        dir:"desc"
    }
]

If the table is not currently sorted then the array will be empty.

Clear All Sorters

To remove all sorting from the table, call the clearSort function.

$("#example-table").tabulator("clearSort");

Callbacks

A range of callbacks are avaialble for tracking progress of sorting. See the Sorting Callbacks section for more information.

Column Calculations Updated

Column calculations can be useed to add a row of calcualted values to the top or bottom of your table to display infmation such as the sum of a columns data.

There are two options that can be set in a column definition object to define a calculation, the topCalc option defines a calculation for the top of the column, and the bottomCalc defines a calculation for the bottom of the column. You can define, either, both or neither of the options.

{title:"Rating", field:"rating", topCalc:"avg"} //show average rating

Tabulator comes with a number of preconfigured calculations including:

  • avg - the average value of the column
    • optional topCalcParams/bottomCalcParams:
      • precision - the number of decimals to display (default is 2), setting this value to false will display however many decimals are provided with the number
  • max - the maximum value in the column
    • optional topCalcParams/bottomCalcParams:
      • precision - the number of decimals to display, setting this value to false will display however many decimals are provided with the number (default is false)
  • min - the minimum value in the column
    • optional topCalcParams/bottomCalcParams:
      • precision - the number of decimals to display, setting this value to false will display however many decimals are provided with the number (default is false)
  • sum - a sum of all values in the column (only sums numerical columns)
    • optional topCalcParams/bottomCalcParams:
      • precision - the number of decimals to display, setting this value to false will display however many decimals are provided with the number (default is false)
  • concat - join all values into one string
  • count - a count of all non empty cells in the column

You can pass an optional additional parameter with the each calculation option, topCalcParams and bottomCalcParams that should contain an object with additional information for configuring the calculation function.

{title:"Rating", field:"rating", topCalc:customCalcFunction, topCalcParams:{age:18}}

Note: If a calculation is defined on any column the calculations rows will be shown, any column without a calculations will show as an empty cell in the calculation row

Note: At the moment all calculations are formatted as plain text, formatters for column calculations will be comming soon.

Custom Calculation Function

If you want to perform your own calculations on a column then you can pass a custom calculation function to either of the topCalc or bottomCalc options.

//count number of users over 18
var adultCalc = function(values, data, calcParams){
    //values - array of column values
    //data - all table data
    //calcParams - params passed from the column defintion object

    var calc = 0;

    values.forEach(function(value){
        if(value > 18){
            calc ++;
        }
    });

    return calc;
}

 //in your column definition for the column
 {title:"Age", field:"age", topCalc:adultCalc},
  

Calculations For Grouped Data

When you are using the groupBy option with your table, the calculation rows will be displayed differently. Instead of being displayed at the top and bottom of the table, they will be displayed inside each group, at the top and bottom of that group, showing the calculations for that group.

Group Calculation Visibility

By default Tabulator will hide column calculations in groups when the group is toggled closed. If you would like column calculations to display when a group is closed, set the groupClosedShowCalcs option to true.

$("#example-table").tabulator({
    groupClosedShowCalcs:true, //show column calculations when a group is closed
});

Calculation Visibility New

By default column calculations are shown at the top and bottom of the table, unless row grouping is enabled, in which case they are shown at the top and bottom of each group.

The columnCalcs option lets you decided where the calculations should be displayed, it can take one of four values:

  • true - show calcs at top and bottom of the table, unless grouped, then show in groups (boolean, default)
  • both - show calcs at top and bottom of the table and show in groups
  • table - show calcs at top and bottom of the table only
  • group - show calcs in groups only
$("#example-table").tabulator({
    columnCalcs:"both", //show column calculations at top and bottom of table and in groups
});

Formatting Calculation Cells

You can apply formatters (see Formatting Data for more information) to any calculation cells, using the topCalcFormatter and bottomCalcFormatter options in a columns definition object. you can also pass in additional parameters to the formatter functions using the topCalcFormatterParams and bottomCalcFormatterParams options:

{title:"Rating", field:"rating", topCalc:"avg", topCalcFormatter:"star", topCalcFormatterParams:{stars:5}} //apply star formatter to top calculation cell

Getting Calculation Results

You can retreive the results of the column calculations at any point using the getCalcResults function.

var results = $("#example-table").tabulator("getCalcResults");

For a table without grouped rows, this will return an object with top and bottom properties, that contain a row data object for all the columns in the table for the top calculations and bottom calculations respectively.

{
    top:{
        age:53,
        score:73
    },
    bottom:{
        age:27,
        score:66
    },
}

For tables with grouped rows, this will return an object, where each group is represented by a property in the object, with the key for the group being the key for the property. As above each of the groupn objects contains a top and bottom property as well as a groups property that contains the data for any sub groups.

{
    old:{
        top:{
            age:53,
            score:73
        },
        bottom:{
            age:95,
            score:66
        },
        groups:{
            //data for any sub groups
        }
    }
    young:{
        top:{
            age:18,
            score:73
        },
        bottom:{
            age:12,
            score:66
        },
        groups:{
            //data for any sub groups
        }
    }
}

Editing & Manipulating Data

Tabulator allows you to manipulate the data in the table in a number of different ways

Editable Data

Columns of the table can be set as editable using the editor property in the column definition. (see Define Columns for more details).

When a user clicks on an editable column the will be able to edit the value for that cell.

By default Tabulator will use an editor that matches the current formatter for that cell. if you wish to specify a specific editor, you can set them per column using the editor option in the column definition. Passing a value of true to this option will result in Tabulator applying the editor that best matches the columns formatter, if present.

You can pass an optional additional parameter with the editor, editorParams that should contain an object with additional information for configuring the editor.

{title:"Rating", field:"rating", editor:"star", editorParams:{stars:4}}

Tabulator comes with a number of preconfigured editors including:

  • input - editor for plain text.
  • textarea - editor for multi-line text, allows the row to vertically resize to fit the text as it is entered.
  • number - editor for numbers with increment and decrement buttons.
    • optional editorParams:
      • max - the maximum allowed value
      • min - the minimum allowed value
      • step - the step size when increementing/decremeting the value (default 1)
  • range - range slider editor for numbers.
    • optional editorParams:
      • max - the maximum allowed value (default 0)
      • min - the minimum allowed value (default 10)
      • step - the step size when increementing/decremeting the value (default 1)
  • tick - editor for tick and tickCross columns.
  • star - editor for star columns (can use left/right arrow keys and enter for selection as well as mouse).
  • progress - editor for progress bar columns (can use left/right arrow keys and enter for selection as well as mouse)
  • select - a select box for picking from a set of options. (details of how to use this can be seen below)

Select Editor

The select editor creates a dropdown select box to allow the user to select from some prefined options, you define the list of options in the editorParams property. There are three ways you can define the options list depending on your needs.

The simplist way to define the list is by passing in an object where the property keys represent the value of the option and their value represents the label of the option.

{title:"Name", field:"name", editor:"select", editorParams:{
    "steve":"Steve Boberson",
    "bob":"Bob Jimmerson",
    "jim":"Jim Stevenson",
}}

For more complex option lists you can use an array of objects, that allows you to define option groups, and disabled options.

{title:"Name", field:"name", editor:"select", editorParams:[
    //option group
    {
        label:"Men",

        //options in option group
        options:[
        {
            label:"Steve Boberson",
            value:"steve",
        },
        {
            label:"Bob Jimmerson",
            value:"bob",
        },
        ]
    },

    //option group
    {
        label:"Women",

        //options in option group
        options:[
        {
            label:"Jenny Jillerson",
            value:"jenny",
        },
        {
            label:"Jill Betterson",
            value:"jill",
        },
        ]
    },

    //ungrouped option
    {
        label:"Other",
        value:"other",
    },

    //disabled option
    {
        label:"Disabled",
        value:"disabled",
        disabled:true,
    }
]}

If you want to generate the options when the select editor is triggered, then you can pass a function into the editorParams, that must return the option list in one of the two formats outlined above

{title:"Name", field:"name", editor:"select", editorParams:function(cell){

    //create a options list of all names currently in the table

    var rows = $("example-table").tabulator("getRows");
    var options = {};

    rows.forEach(function(row){
        var data = row.getData();

        options[data.name] = data.name;
    });

    return options;
}

Custom Editor

If you need a different type of editor, you can pass a custom editor function to the editor option. This function should take four parameters, a CellComponent for the cell being edited, a function to call when the cell has ben rendered, which can be used to set focus or tidy up the display after the element has become visible, a function to call to pass back the new value, when the user has successfully entered new data in the cell, and a function to call if the user aborts the edit.

var dateEditor = function(cell, onRendered, success, cancel){
    //cell - the cell component for the editable cell
    //onRendered - function to call when the editor has been rendered
    //success - function to call to pass the succesfully updated value to Tabulator
    //cancel - function to call to abort the edit and return to a normal cell

    //create and style editor
    var editor = $("<input type='date'></input>");
    editor.css({
        "padding":"3px",
        "width":"100%",
        "box-sizing":"border-box",
    });

    //Set value of editor to the current value of the cell
    editor.val(moment(cell.getValue(), "DD/MM/YYYY").format("YYYY-MM-DD"));

    //set focus on the select box when the editor is selected (timeout allows for editor to be added to DOM)
    onRendered(function(){
      editor.focus();
      editor.css("height","100%");
    });

    //when the value has been set, trigger the cell to update
    editor.on("change blur", function(e){
        success(moment(editor.val(), "YYYY-MM-DD").format("DD/MM/YYYY"));
    });

    //return the editor element
    return editor;
};


//in your column definition for the column
{title:"Birthday", field:"dob", editor:dateEditor}}

Blue Event
It is important to note that a custom editor must specify how to handle a blur event on its element by either calling the success or cancel functions. This is because when a user clicks or tabs out of a cell, the blur event will be fired and must be handled to move on to the next cell. As a fallback Tabulator will cancel the edit if an editor is blured and the event has not been correctly handled.

Optional Editing

There are some circumstances where you may want to block editibility of a cell for one reason or another. To meet this need you can use the editable option. This lets you set a callback that is executed before the editor is built, if this callback returns true the editor is added, if it returns false the edit is aborted and the cell remains a non editable cell. The function is passed one parameter, the CellComponent of the cell about to be edited. You can also pass a boolean value instead of a function to this property.

var editCheck = function(cell){
    //cell - the cell component for the editable cell

    //get row data
    var data = cell.getRow().getData();

    return data.age > 18; // only allow the name cell to be edited if the age is over 18
}

//in your column definition for the column
{title:"Name", field:"name", editor:"input", editable:editCheck}

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to your edited value as it is being parsed into the table. (see Mutators for more details)

Validating Data

You can set validators on columns to ensure that any user input into your editable cells matches your requirements.

Validators can be applied by using the validator property in a columns definition object (see Define Columns for more details).

{title:"Rating", field:"rating", editor:"input", validator:"required"}

When using validators that take properties you can pass in an object:

{title:"Rating", field:"rating", editor:"input", validator:{
    type:"max",
    parameters:5,
}}

Or you can use the shorthand notation, seperating the type and parameter with a : symbol:

{title:"Rating", field:"rating", editor:"input", validator:"max:5"}

Tabulator has a wide variety of built in validators:

  • required - value cannot be null or an empty string
  • unique - no other row in the column can have this value
  • integer - value must be an integer
  • float - value must be a float
  • numeric - value must be a number
  • string - value must be a non-numeric string
  • min - value must be greater than or equal to parameter
     {validator:"min:5"} \\value must be greater than or equal to 5
  • max - value must be less than or equal to parameter
     {validator:"max:5"} \\value must be less than or equal to 5
  • minLength - string value must have a length greater than or equal to parameter
     {validator:"minLength:5"} \\value must have a length greater than or equal to 5
  • maxLength - string value must have a length less than or equal to parameter
     {validator:"maxLength:5"} \\value must have a length less than or equal to 5
  • in - value must be an empty string or match a value from the | delimieted string in the parameter
     {validator:"in:red|green|blue"} \\value must be 'red', 'green' or 'blue'
  • regex - value must match supplied regex
     {validator:"regex:\\.com$"} \\allow strings that end in '.com'

If the validation fails the tabulator-validation-fail class will be applied to the cell and the validationFailed callback will be triggered. The user will not be able to leave the cell until they input a valid value or cancle the edit (press escape).

Note By default all validators, except the required validator will approve any empty value (ie. empty string, null or undefined). to ensure empty values are rejected you should use the required validator.

Custom Validator Functions

If you want to add your own custom validation functions, you can pass a function to the validator property. It should return true if the value passes validation and false if it fails:

//validator to prevent values divisible by the provided devisor
var noDivide = function(cell, value, parameters){
    //cell - the cell component for the edited cell
    //value - the new input value of the cell
    //parameters - the parameters passed in with the validator

    return value % parameters.divisor; //dont allow values divisible by devisor;
}

//in your column definition for the column
{title:"Age", field:"age", editor:"input", validator:[
        type:noDivide,
        parameters:{
            divisor:5,
        }
    ]
}
                    

Multiple Validaitors

You can use multiple validators on the same column by passing an array to the validator property

{title:"Rating", field:"rating", editor:"input", validator:["requred", "max:5"]}

Callbacks

A range of callbacks are avaialble for validation. See the Validation Callbacks section for more information.

Replacing Data New

The replaceData function lets you silently replace all data in the table without updating scroll position, sort or filtering, and without triggering the aja loading popup. This is great if you have a table you want to periodically update with new/updated information without alerting the user to a change.

It takes the same arguments as the setData function, and behaves in the same way when loading data (ie, it can make ajax requests, parse JSON etc)

$("#example-table").tabulator("replaceData", [{id:1, name:"bob", gender:"male"}, {id:2, name:"Jenny", gender:"female"}]) //load data array
$("#example-table").tabulator("replaceData", "/data.php") //load data from data/php via ajax request
$("#example-table").tabulator("replaceData") //trigger reload of ajax data from ajaxURL property

Note The replaceData function will only maintain scroll position when the Vitrual DOM has been enabled by setting a height on the table.

Updating Existing Data

If you want to update an existing set of data in the table, without completely replacing the data as the setData method would do, you can use the updateData method.

This function takes an array of row objects and will update each row based on its index value. (the index defaults to the "id" parameter, this can be set using the index option in the tabulator constructor). Options without an index will be ignored, as will items with an index that is not already in the table data. The addRow function should be used to add new data to the table.

$("#example-table").tabulator("updateData", [{id:1, name:"bob", gender:"male"}, {id:2, name:"Jenny", gender:"female"}]);

The function will not replace the rows with the provided data, it will only update any of the provided parameters.

//data before update {id:1, name:"Steve", gender:"male", age:20}

$("#example-table").tabulator("updateData", [{id:1, name:"bob"}]); //update data

//data after update  = {id:1, name:"bob", gender:"male", age:20}

Add Data

You can add a data to the existing table data using the addData function.

The first argument should be an array of row data objects. If you do not pass data for a column, it will be left empty.

The second argument is optional and determines whether the data is added to the top or bottom of the table. A value of true will add the data to the top of the table, a value of false will add the data to the bottom of the table. If the parameter is not set the data will be placed according to the addRowPos global option.

$("#example-table").tabulator("addData", [{id:1, name:"bob", gender:"male"}, {id:2, name:"Jenny", gender:"female"}], true);

By default any new rows will be added to the bottom of the table, to change this to the top set the addRowPos option to "top";

If you want to insert the data next to an existing row you can pass an optional third agument to the function that will position the new rows next to the specified row (above or below based on the value of the second argument). This argument will take any of the standard row component look up options:

$("#example-table").tabulator("addData", [{id:6, name:"bob", gender:"male"}, {id:7, name:"Jenny", gender:"female"}], true, 3); //add new data above existing row with index of 3

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to the new data before the data is added. (see Mutators for more details)

Update or Add Data

If the data you are passng to the table contains a mix of existing rows to be updated and new rows to be added then you can call the updateOrAddData function. This will check each row object provided and update the existing row if available, or else create a new row with the data.

$("#example-table").tabulator("updateOrAddData", [{id:1, name:"bob"}, {id:3, name:"steve"}]);

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to the new data before the table is updated. (see Mutators for more details)

Retreiving Data

Retrieve All Data

You can retrieve the data stored in the table using the getData function.

var data = $("#example-table").tabulator("getData");

This will return an array containing the data objects for each row in the table.

By default getData will return an array containing all the data held in the Tabulator. If you only want to access the currently filtered/sorted elements, you can pass a value of true to the first argument of the function.

var data = $("#example-table").tabulator("getData", true); //return currently filtered data

Retrieve Row Data

To rereive the data of a specific row, you can retrieve the Row Component with the getRow function, then use the getData function on the component. The first argument is the row you are looking for, it will take any of the standard row component look up options.

var row = $("#example-table").tabulator("getRow", 1); //return row compoenent with index of 1
var rowData = row.getData();

Data Accessors
If you have defined any accessors on your columns, then these will be applied to the data before the data is returned from any of the above functions. (see Accessors for more details)

Retrieving Row Components

You can retrieve all the row components in the table using the getRows function.

var rows = $("#example-table").tabulator("getRows");

This will return an array containing the Row Component for each row in the table.

By default getRows will return an array containing all the Row Component's held in the Tabulator. If you only want to access the currently filtered/sorted elements, you can pass a value of true to the first argument of the function.

var rows = $("#example-table").tabulator("getRows", true); //return currently filtered data

Find Row Position In Table

Use the getRowPosition function to retreive 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.

The first argument is the row you are looking for, it will take any of the standard row component look up options. 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 second argument of the function.

var position = $("#example-table").tabulator("getRowPosition", row, true); //return the position of the row in the filtered/sorted data

NoteIf the row is not found, a value of -1 will be returned, row positions start at 0

Get Row From Position In Table

You can retreive the Row Component of a row at a given position in the table using getRowFromPosition function. By default this will return the row based in its position in all table data, including data currently filtered out of the table.

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

var rows = $("#example-table").tabulator("getRowFromPosition", 5, true); //return 6th row in the visible table data

Retreive data as HTML Table

You can retrieve the table data as a simple HTML table using the getHtml function.

var table = $("#example-table").tabulator("getHtml");

This will return a HTML encoded string of the table data.

By default getHtml will return a table containing all the data held in the Tabulator. If you only want to access the currently filtered/sorted elements, you can pass a value of true to the first argument of the function.

var table = $("#example-table").tabulator("getHtml", true); //build table from filtered data only

You can hide a column from the HTML output by setting the hideInHtml property to true on its column definition.

{title:"Name", field:"name", hideInHtml:true}

Emptying the Table

You can remove all data from the table using the clearData function:

$("#example-table").tabulator("clearData");

Row Manipulation

There are a number of ways to manipulate individual rows in the table without affecting any other currently rendered rows.

Add Row

You can add a row to the table using the addRow function.

The first argument should be a row data object. If you do not pass data for a column, it will be left empty. To create a blank row (ie for a user to fill in), pass an empty object to the function.

The second argument is optional and determines whether the row is added to the top or bottom of the table. A value of true will add the row to the top of the table, a value of false will add the row to the bottom of the table. If the parameter is not set the row will be placed according to the addRowPos global option.

$("#example-table").tabulator("addRow", {name:"Billy Bob", age:"12", gender:"male", height:1}, true);

By default any new rows will be added to the bottom of the table, to change this to the top set the addRowPos option to "top";

If you want to add the row next to an existing row you can pass an optional third agument to the function that will position the new row next to the specified row (above or below based on the value of the second argument). This argument will take any of the standard row component look up options:

$("#example-table").tabulator("addRow", {name:"Billy Bob", age:"12"}, true, 3); //add new row above existing row with index of 3

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to the new data before the row is added. (see Mutators for more details)

Update Row

You can update any row in the table using the updateRow function.

The first argument is the row you want to update, it will take any of the standard row component look up options.

The second argument should be the updated data object for the row. As with the updateData function, this will not replace the exisiting row data object, it will only update any of the provided parameters.

$("#example-table").tabulator("updateRow", 1, {id:1, name:"bob", gender:"male"});

Once complete, this function will trigger the rowUpdated and dataEdited events.

This function will return true if the update was successfull or false if the requested row could not be found. If the new data matches the existing row data, no update will be performed.

If you already have the RowComponent for the row you wish to update, you can call the update function directly on the component:

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

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to the new data before the row is updated. (see Mutators for more details)

Update or Add Row

If you don't know whether a row already exists you can use the updateOrAddRow function. This will check if a row with a matching index exists, if it does it will update it, if not it will add a new row with that data. This takes the same arguments as the updateRow function.

$("#example-table").tabulator("updateOrAddRow", 3, {id:3, name:"steve", gender:"male"});

Get Row Element

To rereive the jQuery element of a specific row, you can retrieve the RowComponent with the getRow function, then use the getElement function on the component. The first argument is the row you are looking for, it will take any of the standard row component look up options.

var row = $("#example-table").tabulator("getRow", 1); //return row compoenent with index of 1
var rowElement = row.getElement();

Delete Row

You can delete any row in the table using the deleteRow function. The first argument is the row you want to delete, it will take any of the standard row component look up options.

$("#example-table").tabulator("deleteRow", 15);

If you already have the RowComponent for the row you wish to delete, you can call the delete function directly on the component:

row.delete();

Interaction History

If you set the history option to true, Tabulator will keep track of user interactions with the table and allow users to undo/redo those actions.

$("#example-table").tabulator({
    history:true, //record table history
});

The history extension tracks the following actions:

  • Cell Edits
  • Row Added
  • Row Deleted
  • Row Moved

Undo Action

With history enabled you can use the undo function to automatically undo a user action, the more times you call the function, the further up the history log you go.

$("#example-table").tabulator("undo");

If the keybindings extension is installed, this action can also be triggered with the ctrl + z key combination.

Redo Action

With history enabled you can use the redo function to automatically redo user action that has been undone, the more times you call the function, the further up the history log you go. once a user interactes with the table then can no longer redo any further actions until an undo is performed

$("#example-table").tabulator("redo");

If the keybindings extension is installed, this action can also be triggered with the ctrl + y key combination.

Callbacks

A range of callbacks are avaialble for tracking history actions. See the History Callbacks section for more information.

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.

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.

$("#example-table").tabulator("navigatePrev");

If the keybindings extension 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.

$("#example-table").tabulator("navigateNext");

If the keybindings extension 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.

$("#example-table").tabulator("navigateLeft");

Right Cell

Use the navigateRight function to shift focus to next editable cell on the right, return false if none available on row.

$("#example-table").tabulator("navigateRight");

Up Cell

Use the navigateUp function to shift focus to the same cell in the row above.

$("#example-table").tabulator("navigateUp");

If the keybindings extension 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.

$("#example-table").tabulator("navigateDown");

If the keybindings extension 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

Callbacks

A range of callbacks are avaialble for tracking progress of data manipulation. See the Data Callbacks section for more information.

Table Layout Updated

Tabulator has loads of different ways of customizing the layout the table, have a look through the next few sections to see how you can configure your tables to meet your use case.

Layout Modes Updated

You can choose how your table should layout its columns by setting the layout mode, in the configuration options:

$("#example-table").tabulator({
    layout:"fitData",
});

Tabulator has a number of different layout modes to choose from

Fit Columns to Data

By default Tabulator will use the fitData layout mode, which will resize the tables columns to fit the data held in each column, unless you specify a width or minWidth in the column constructor. If the width of all columns exceeds the width of the containing element, a scroll bar will appear.

$("#example-table").tabulator({
    layout:"fitData",
});

Fit Columns to Data and Fill

The fitDataFill layout mode functions in the same way as the fitData mode, but ensures that rows are always at least the full width of the table.

$("#example-table").tabulator({
    layout:"fitDataFill",
});

Fit Columns to Container Updated

As an alternative to the default data fit, you can use the fitColumns layout mode to cause Tabulator to resize columns so they fit perfectly in the available table width.

In this layout mode, columns without a width set are resized to fill any remaning space on the table. If all columns cannot fit on the table then a scrollbar will appear.

$("#example-table").tabulator({
    layout:"fitColumns",
});

You can adjust the behaviour of the layout using the widthGrow and widthShrink properties on a column definition

The widthGrow property should be used on columns without a width property set. The value is used to work out what fraction of the available will be allocated to the column. The value should be set to a number greater than 0, by default any columns with no width set have a widthGrow value of 1.

The widthGrow function works by dividing the available space by the sum total of widthGrow values and then allocating it out to the columns based on their value.

$("#example-table").tabulator({
    layout:"fitColumns",
    columns:[
        {title:"Name", field:"name", width:100}, //column has a fixed width of 100px;
        {title:"Age", field:"age", widthGrow:1}, //column will be allocated 1/5 of the remaining space
        {title:"Color", field:"color", widthGrow:3}, //column will be allocated 3/5 of the remaining space
        {title:"location", field:"location"}, // column has a default widthGrow of 1 and will be allocated 1/5 of the remaining space
    ]
});

The widthShrink property should be used on columns with a width property set. The value is used to work out how to shrink columns with a fixed width when the table is too narrow to fit in all the columns. The value should be set to a number greater than 0, by default columns with a width set have a widthShrink value of 0, meaning they will not be shrunk if the table gets too narrow, and may cause the horizontal scrollbar to appear.

The widthShrink function works by dividing the excess horizontal space by the sum total of widthShrink values and then allocating it out to the columns based on their value.

$("#example-table").tabulator({
    layout:"fitColumns",
    columns:[
        {title:"Name", field:"name", width:100}, //column will not be shrunk
        {title:"Age", field:"age", width:200, widthShrink:2}, //column will be shrunk by 2/3 of the excess space
        {title:"Color", field:"color", width:200, widthShrink:1}, //column will be shrunk by 1/3 of the excess space
        {title:"location", field:"location"}, //column has no width set so will be set at the tables minWidth value
    ]
});

Update Column Widths On New Data

To keep the layout of the columns consistent, once the column widths have been set on the first data load (either from the data property in the constructor or the setData function) they will not be changed when new data is loaded.

If you would prefer that the column widths adjust to the data each time you load it into the table you can set the layoutColumnsOnNewData property to true.

$("#example-table").tabulator({
    layoutColumnsOnNewData:true,
});

Responsive Layout Updated

Responsive layout will automatically hide/show columns to fit the width of the Tabulator element. This allows for clean rendering of tables on smaller mobile devices, showing important data while avoiding horizontal scroll bars. You can enable responsive layouts using the responsiveLayout option.

There are two responsive layout modes available:

  • hide - hide columns that no longer fit in the table
  • collapse - collapse columns that no longer fit on the table into a list under the row
$("#example-table").tabulator({
    responsiveLayout:"hide", // hide rows that no longer fit
});

By default, columns will be hidden from right to left as the width of the table decreases. You can choose exatly how columns are hidden using the responsive property in the column definition object.

When responsive layout is enabled, all columns are given a default responsive value of 1. The higher you set this value the sooner that column will be hidden as the table width decreases. If two columns have the same responsive value then they are hidden from right to left (as defined in the column definition array, ignoring user moving of the columns). If you set the value to 0 then the column will never be hidden regardless of how narrow the table gets.

$("#example-table").tabulator({
    responsiveLayout:true, // enable responsive layouts
    columns:[ //set column definitions for imported table data
        {title:"Name", field:"name", responsive:0}, // this column wil never be hidden
        {title:"Age", field:"age" , responsive:3}, // hidden first
        {title:"Gender", field:"gender" }, // hidden fifth
        {title:"Height", field:"height" , responsive:2}, // hidden third
        {title:"Favourite Color", field:"color" , responsive:2}, // hidden second
        {title:"Date of Birth", field:"dob" }, // hidden fourth
    ],
});

Note: If you are using the fitColumns feature, you will need to set a minWidth property on the columns you want to respond responsively to ensure they are hidden when necessary, otherwise Tabulator will keep on reducing the width of the columns instead.

Responsive Collapsed Column List New

If you set the responsiveLayout option to collapse the values from hidden columns will be displayed in a title/value list under the row.

In this mode an object containg the title of each hidden column and its value is generated and then used to generate a list displayed in a div .tabulator-responsive-collapse under the row data.

The inbuilt collapse formatter creates a table to neatly display the hidden columns. If you would like to format the data in your own way you can use the responsiveLayoutCollapseFormatter, it take an object of the column values as an argument and must return the HTML content of the div.

This function should return an empty string if there is no data to display.

$("#example-table").tabulator({
    responsiveLayoutCollapseFormatter:function(data){
        var list = $("<ul></ul>");

        for(var key in data){
            list.append("<li><strong>" + key + "</strong> - " + data[key] + "</li>");
        }

        return Object.keys(data).length ? list : "";
    }
});

Collapsed List Column Formatting New

By default any formatter set on the column is applied to the value that will appear in the list. while this works for most formatters it can cause issues with the progress formatter which relises on being inside a cell.

If you would like to disable column formatting in the collapsed list, you can use the responsiveLayoutCollapseUseFormatters option:

$("#example-table").tabulator({
    responsiveLayoutCollapseUseFormatters:false,
});

Dummy Cell Component
Because the collapsed data is not based in a cell, a dummy cell component is passed into the formatters to allow them to fucntion as normal. This dummy component only has the getValue, getData, getElement, getRow and getColumn functions rather than the full set of component functions.

Collapsed List Show/Hide New

If you would like your users to be able to interact with the list and hide/show it as needed you can add a column that uses the built-in responsiveCollapse formatter that provides a control for toggling the visibility of the collapsed list

{formatter:"responsiveCollapse", headerSort:false}

Collapsed lists are displayed to the user by default, if you would prefer they start closed so the user can open them you can use the responsiveLayoutCollapseStartOpen option

$("#example-table").tabulator({
    layoutColumnsOnNewData:false,
});

Resizable Rows

You can allow the user to manually resize rows by dragging the top or bottom border of a row. To enable this functionality, set the resizableRows property to true

$("#example-table").tabulator({
    resizableRows:true, // this option takes a boolean value (default = false)
});

Resizable Columns Updated

By default it is possible to manually resize columns by dragging the borders of the column in both the column headers and the cells of the column.

If you want to alter this behaviour you can use the resizableColumns to choose where the resize handles are available. It supports four possible options:

  • true - enable column resizing from both cells and headers
  • "header" - enable column resizing from headers only
  • "cell" - enable column resizing from cells only
  • false - disable column resizing
$("#example-table").tabulator({
    resizableColumns:false, // this option takes a boolean value (default = true)
});

Note: If you double click on a resizeable border it will resize the column to fit the data it contains.

Column Specific Resizing New

You can also set column resizability on a per column basis by passing a boolean value to the resizable property in a columns definition object.

{title:"name", field:"name", resizable:false} //prevent this column from being resized

Minimum Column Width

It is possible to set a minimum column width to prevent resizing columns from becoming too small.

This can be set globally, by setting the columnMinWidth option to the column width when you create your Tabulator.

This option can be overridden on a per column basis by setting the minWidth property on the column definition.

$("#example-table").tabulator({
    columnMinWidth:80, //Minimum column width in px (default = 40)
});

Wrap Column Header Title Text

By default Tabulator will try and keep column header titles on one line, truncating the text with ellipsis if it gets wider that the column.

If you would like to wrap the text instead then you will need to edit the CSS white-space value for the column headers and set it to normal.

.tabulator .tabulator-header .tabulator-col .tabulator-col-content .tabulator-col-title {
    white-space: normal;
}

Frozen Columns

You can freeze the position of columns on the left and right of the table using the frozen property in the column definition array. This will keep the column still when the table is scrolled horizontally.

$("#example-table").tabulator({
    [
        {title:"Name", field:"name", frozen:true}, //frozen column on left of table
        {title:"Age", field:"age"},
        {title:"Eye Colour", field:"eyes"},
        {title:"Height", field:"height", frozen:true}, //frozen column on right of table
    ]
});

You can freeze any number of columns on the left or right of the table, but they must be next to eachother in the column definition array.

Tabulator builds the frozen columns by looking through the column definition array from both sides, building up the frozen columns as it see the frozen property. Once a non-frozen column is reached it stops building the frozen list for that side of the table.

Note: Frozen columns are locked in place and cannot be reordered by dragging and dropping the column header. It is also not possible to freeze a column that is part of a column group.

Note: At lease one column must not be frozen for the table to render correctly. If you want to freeze all your columns then you will acheive the same effect by not freezing any.

Frozen Rows

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

row.freeze();

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

row.unfreeze();

Note: Freezing or unfreezing a row will redraw the table.

Table Resizing

Tabulator will automatically attempt to redraw the data contained in the table if the containing element for the table is resized. To disable this functionality, set the autoResize property to false

$("#example-table").tabulator({
    autoResize:false, // prevent auto resizing of table
});

Note: Tabulator uses the ResizeObserver JavaScript API to watch for resizing of the table, at present this is only available on the Chrome browser in versions 64 and above. In browsers without this functionality, Tabulator will fallback to using the window resize event which will only be able to detect changes on the window size, not on the table element itself.

Redrawing the table

If the size of the element containing the Tabulator changes (and you are not able to use the in built auto-resize functionality) or you create a table before its containing element is visible, it will necessary to redraw the table to make sure the rows and columns render correctly.

This can be done by calling the redraw method. For example, to trigger a redraw whenever the viewport width is changed:

$(window).resize(function(){
    $("#example-table").tabulator("redraw");
});

The redraw function also has an optional boolean argument that when set to true triggers a full rerender of the table including all data on all rows.

$(window).resize(function(){
    $("#example-table").tabulator("redraw", true); //trigger full rerender including all data and rows
});

Virtual DOM

As of version 3.0 tabulator renders its table using a Virtual DOM, this means that it only renders the rows you seen in the table (plus a few above and below the current view) and creates and destroys the rows as you scroll through the table.

This allows tabulator to handle thousands of rows with no overhead as it only processes the information it nedds to display.

A detailed description of how the Virual Dom works can be found in the Architecture Concepts Section

In order for the virtual DOM to function correctly you must ensure that the table element has a height you can either define this in the CSS for the element or set it using the height option in the table constructor, this can be set to any valid CSS value. If no height is set the table will revert to the standard DOM mode and try and render all rows at once, which will have a performance impact on tables with a large number of rows.

$("#example-table").tabulator({
    height:"100%",
});

Note: In version 3.3 and below you were required to set the height option to use the virtual DOM, as of 3.4 this is no longer the case and you can define the height inline on the element or in the CSS and the virtual DOM will still work.

Note: It is not possible to externally add event bindings to elements in the table because they are created and destoryed by Tabulator as needed. The good news is there are callbacks and options to register almsost every binding through the setup options.

Render Buffer

The virtual DOM renders a number of rows above and below the visible rows to ensure a smooth scrolling experience. This buffer will be set at the current of the height of table so there is always and additional tables height worth of rows above and beyond the view.

In some situations, where you have a full screen table with a large number of columns, this can result in slow rendering performance in older browsers. In these situations it is possible to manually set the height of the buffer in pixels using the virtualDomBuffer option. By setting this to a smaller number than the height you can reduce the number of rows that are rendered and increase the performance on older browsers.

$("#example-table").tabulator({
    virtualDomBuffer:300, //set virtual DOM buffer to 300px
});

Changing Table Height

If you want to manually change the height of the table at any time, you can use the setHeight function, which will also redraw the virtual DOM if necessary.

If the height of the table changes at any point (for example the height is set at a percentage and the user resizes the window), you will need to call the redraw function to ensure that the virtual DOM updates to display the corret number of rows.

$("#example-table").tabulator("redraw");

Standard DOM Exceptions

When pagination is enabled Tabulator will revert to using standard DOM rendering as it will only be displaying one page at a time.

Disabling the Virtual DOM

f you need to disable virtual rendering for any reason you can set the virtualDom option to false to force standard rendering.

$("#example-table").tabulator({
    virtualDom:false, //disable virtual DOM rendering
});

Note: You must have the height option set to enable progressive rendering.

Empty Table Placeholder

You can use the placeholder option to display a message to your users when the table has no data set. The function can either take a string to display or, the HTML or jQuery element to display in the empty table.

$("#example-table").tabulator({
    placeholder:"No Data Available", //display message to user on empty table
});

Table Footer

The footer element that the tables uses for holding pagination elements etc, is automatically generated by Tabulator.

If you want to use your own element for any reason, for example you want to add additional elements to the footer, then you can use the footerElement option to pass a jquery selector for the footer element into the table.

$("#example-table").tabulator({
    footerElement:$("<div class='tabulator-footer'><button>Custom Button</button></div>"), //set custom table footer with custom button
});

Note: To ensure correct functioning of the table, it is recommended that you apply the tabulator-footer class to the footer element

Callbacks

A range of callbacks are avaialble for tracking progress of table rendering. See the Layout Callbacks section for more information.

Persistent Configuration

Tabulator can store a variety of table setup options so that each time a user comes back to the page, the table is laid out just as they left it.

Persistence Mode

Persistence information can either be stored in a cookie or in the localSotrage object, you can use the persistenceMode to choose which. It can take three possible values:

  • local - (string) Store the persistence information in the localStorage object
  • cookie - (string) Store the persistence information in a cookie
  • true - (boolean) check if localStorage is available and store persistance information, otherwise store in cookie (Default option)
$("#example-table").tabulator({
    persistenceMode:"cookie", //store persistence information in a cookie
});

Persistence ID

If you are planning on having multiple tables on the same page using persistence then Tabulator needs a way to uniquely identify each table. There are two ways to do this either set the id attribute on the element that will hold the table, Tabulator will automatically use this id as a reference for the persistence id.

<div id="example-table"></div>

Alternatively if you do not want to give an id to the table holding element you can set the tabulator options parameter persistenceID to a unique persistence id for that table.

$("#example-table").tabulator({
    persistenceID:"example1", //id string, can only be numbers, letters, hyphens and underscores.
    persistentLayout:true, //Enable column layout persistence
});

Persistent Column Layout

You can ensure the layout of columns is stored for the next page load by setting the persistentLayout option to true

$("#example-table").tabulator({
    persistentLayout:true, //Enable column layout persistence
});

Note: If you update the column definition array after the the column layout has been stored, Tabulator will attempt to match the stored columns against the new definition. If you have any issues with column definitions updating then you will have to change the persistenceID or delete your cookies/local storage to clear out the old column layout information.

Get Column Layout Information

If you want to handle column layout persistence manually, for example storing it in a database to use elsewhere, you can use the getColumnLayout function to retrieve a layout object for the current table.

var columnLayout = $("#example-table").tabulator("getColumnLayout");

Set Column Layout

If you have previously used the getColumnLayout function to retrieve a tables layout, you can use the setColumnLayout function to apply it to a table.

$("#example-table").tabulator("setColumnLayout", columnLayout);

Persistent Sort

You can ensure the data sorting is stored for the next page load by setting the persistentSort option to true

$("#example-table").tabulator({
    persistentSort:true, //Enable sort persistence
});

Persistent Filter

You can ensure the data filtering is stored for the next page load by setting the persistentFilter option to true

$("#example-table").tabulator({
    persistentFilter:true, //Enable filter persistence
});

Note: Only built-in filters can be stored (including extensions), custom filter functions cannot be persistently stored.

Note: Header filters are not currently stored persistently, this feature will be comming in a future release.

Pagination Updated

If you would prefer to display your data as pages rather than a scrolling list Tabulator can help you out there too.

There are two forms of pagination available. local pagination, where Tabulator will parse in all available data and then paginate this data set. Or remote pagination, where Tabulator will load indiviudal pages of data via Ajax from a remote server.

When pagination is enabled, a footer element will be added to the bottom of the table, with a range of navigation controls to allow your users to easily switch between pages.

The first page of a table will automatically be loaded when the table is created if pagination is enabled.

If you are a Laravel user then you should find that the auto generated URL's and data processing work straight out the box with no additional configuration needed.

Note: Changing the filter, sorting or toggling a groups visibility, while pagination is enabled will revert the table back to the first page.

Remote Pagination

To enable remote pagination, set the pagination option to remote, and set the url for the Ajax request using the ajaxURL parameter. You can also pass an optional object to ajaxParams for any parameters you want to pass with the url (these should be static parameters, the page number etc, will be added later on).

By default the page size will be set by the amount of data returned by the remote server, if you need to tell the remote server how many rows to send you can set the paginationSize parameter.

$("#example-table").tabulator({
    pagination:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    ajaxParams:{token:"ABC123"}, //set any standard parameters to pass with the request
    paginationSize:5, //optional parameter to request a certain number of rows per page
});

Request URL

Tabulator will automaticly create a page request URL when a user selects a page.

By default a url will be generated using the provided ajaxURL and a number of system generated parameters:

  • page - the page number being requested
  • size - the number of rows to a page (if paginationSize is set)
  • sort - the first currently sorted field (if any)
  • sort_dir - the first currently sort direction (if any)
  • filter - the first currently filtered field (if any)
  • filter_value - the first current filter value (if any)
  • filter_type - the first current filter type (if any)

If you need to change the names of any of these parameters to fit your existing system, you can use the paginationDataSent option to set alternative parameter names.

$("#example-table").tabulator({
    pagination:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    paginationDataSent:{
        "page":"pageNo", //change page request parameter to "pageNo"
    } ,
});

Custom Pagination URL Construction

If you need to have more complex control over the request URL, you can pass a callback to the paginator option to return the URL you wish to use for each page.

$("#example-table").tabulator({
    pagination:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    paginator: function(url, pageNo, pageSize, ajaxParams ){
        //url - the url from the ajaxURL parameter
        //pageNo - the requested page number
        //pageSize - the value of the paginationSize parameter
        //ajaxParams - the value of the ajaxParams parameter

        return ""; //must return the string of the page request URL
    },
});

Note: If you use a paginator function you will need to manually add the sort and filter parameters to the request url.

Returned Response Data

The remote server should return a JSON formatted object with the following structure:

{
    "last_page":15, //the total number of available pages (this value must be greater than 0)
    "data":[ // an array of row data objects
        {id:1, name:"bob", age:"23"}, //example row data object
    ]
}

If you need to change the names of any of these parameters to fit your existing system, you can use the paginationDataReceived option to set alternative parameter names.

$("#example-table").tabulator({
    pagination:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    paginationDataReceived:{
        "last_page":"max_pages", //change last_page parameter name to "max_pages"
    } ,
});

Local Pagination Updated

Local pagination works by loading the entier data set into the table then generating paged views of that data.

To enable local pagination set the pagination option to local.

$("#example-table").tabulator({
    pagination:"local", //enable local pagination.
});

Setting Page size Updated

With local pagination there are a couple ways to set the number of rows in each page.

You can specify the page size during table creation by setting the paginationSize option. If no height option is specified the table will resize to fit the number of rows on the page.

$("#example-table").tabulator({
    pagination:"local", //enable local pagination.
    paginationSize:5, // this option can take any positive integer value (default = 10)
});

Alternatively, if you specify the height of the table, either in CSS or by using the height option, and don't define the paginationSize option the page size will be automatically set to fill the height of the table.

$("#example-table").tabulator({
    height:"300px",
    pagination:"local", //enable local pagination.
});

Note: If you set the height of the table and use the paginationSize option, the number of rows may either not fill the available space, or not fit in the table and a vertical scrollbar will appear.

Advance Controls

A number of additional controls are available to help customize the pagination experience.

Set Current Page

When pagination is enabled the table footer will contain a number of pagination controls for navigating through the data.

In addition to these controls it is possible to change page using the setPage function

$("#example-table").tabulator("setPage", 5); // show page 5

The setPage function takes one parameter, which should be an integer representing the page you wish to see. There are also four strings that you can pass into the parameter for special functions.

  • "first" - show the first page
  • "prev" - show the previous page
  • "next" - show the next page
  • "last" - show the last page

Change Page Size

You can change the page size at any point by using the setPageSize function. (this setting will be ignored if using remote pagination with the page size set by the server)

$("#example-table").tabulator("setPageSize", 50); // show 50 rows per page

Get Page Size

To retreive the number of rows allowed per page you can call the getPageSize function:

var pageSize = $("#example-table").tabulator("getPageSize"); // returns number of rows allowed per page

Get Current Page Number

To retrieve the curren page use the getPage function. this will return the number of the current page. If pagination is disabled this will return false.

$("#example-table").tabulator("getPage"); // returns current page

Get Maximum Page Number

To retrieve the maximum available page use the getPageMax function. this will return the number of the maximum available page. If pagination is disabled this will return false.

$("#example-table").tabulator("getPageMax"); // returns maximum page

Custom Pagination Control Element

By default the pagination controls are added to the footer of the table. If you wish the controls to be created in another element pass a JQuery object for that element to the paginationElement option.

$("#example-table").tabulator({
    pagination:"local",
    paginationElement:$("#pagination-element"), //build pagination controls in this element
});

Add Row Behaviour New

When using the addRow function on a paginated table, rows will be added relative to the current page (ie to the top or bottom of the current page), with overflowing rows being shifted onto the next page.

If you would prefer rows to be added relative to the table (firs/last page) then you can use the paginationAddRow option. it can take one of two values:

  • page - add rows releative to current page (default)
  • table - add rows relative to the table
$("#example-table").tabulator({
    pagination:"local",
    paginationAddRow:"table", //add rows relative to the table
});

Callbacks

A range of callbacks are avaialble for pagination. See the Pagination Callbacks section for more information.

Grouping Data

You can group rows togeather that share a column value, this creates a visible header for each group and allows the user to colapse groups that they dont want to see.

Rows can be grouped by a common field value by setting the groupBy option to the name of the field to be grouped.

groupBy:"gender",

If you need to group by more complex value, you can pass a function that returns a string that represents the group.

groupBy:function(data){
    //data - the data object for the row being grouped

    return data.gender + " - " + data.age; //groups by data and age
}

Custom Group Headers

You can set the contents of the group headers with the groupHeader option. This should return the contents of the group header.

groupHeader:function(value, count, data, group){
    //value - the value all members of this group share
    //count - the number of rows in this group
    //data - an array of all the row data objects in this group
    //group - the group component for the group

    return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
},

Group Open State

You can set the default open state of groups using the groupStartOpen property.

groupStartOpen:true,

This can take one of three possible values:

  • true - all groups start open (default value)
  • false - all groups start closed
  • function() - a callback to decide if a group should start open or closed

Group Open Function

If you want to decide on a group by group basis which should start open or closed then you can pass a function to the groupStartOpen property. This should return true if the group should start open or false if the group should start closed.

groupStartOpen:function(value, count, data, group){
    //value - the value all members of this group share
    //count - the number of rows in this group
    //data - an array of all the row data objects in this group
    //group - the group component for the group

    return count > 3; //all groups with more than three rows start open, any with three or less start closed
},

Group Toggle Element

By default Tabulator allows users to toggle a group open or closed by clicking on the arrow icon in the left of the group header. If you would prefer a different behaviour you can use the groupToggleElement option to choose a different option:

$("#example-table").tabulator({
   groupToggleElement:"header", //toggle group on click anywhere in the group header
});

The option can take one of three values:

  • arrow - togggle group on arrow element click
  • header - toggle group on click anywhere on the group header element
  • false - prevent clicking anywhere in the group toggling the group

Multi Level Grouping

To set multiple levels of grouping, pass an array to the groupBy option. Each item in the array will be a sub-group of the previous item.

groupBy:["gender", "color"], //group by gender then favourite color

To then set the default open state of each of these levels you can pass an array to the groupStartOpen option.

groupStartOpen:[true, false], //start with gender groups open and color sub groups closed

You can also set a different header for each level of group, as above you pass an array to the groupHeader option.

groupHeader:[
    function(value, count, data){ //generate header contents for gender groups
        return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
    },
    function(value, count, data){ //generate header contents for color groups
        return value + "<span style='color:#0dd; margin-left:10px;'>(" + count + " item)</span>";
    },
],

Sub Group Styling

Each group header element is assigned a class based on its level in the grouping list. This allows you to differentiate between different gouping levels by styling thier classes. By default each level's headers are indented more than the last.

For example, all group headers in the first grouping level will be assigned the class tabulator-group-level-1

Note: You can have as many levels of subgroup as you like, but Tabulator only comes with indent styling built in for the first five levels of subgroup.

Changing Group Setup

If you want to alter the structure of the groups after the table has been created there are a number of functions available.

Change the GroupBy Fields

You can use the setGroupBy function to change the fields that rows are grouped by. This function has one argument and takes the same values as passed to the groupBy setup option.

$("#example-table").tabulator("setGroupBy", "gender");

Change the Start Open States

You can use the setGroupStartOpen function to change the default open state of groups. This function has one argument and takes the same values as passed to the groupStartOpen setup option.

$("#example-table").tabulator("setGroupStartOpen", true);

Change the Header Formatter

You can use the setGroupHeader function to change the header generation function for each group. This function has one argument and takes the same values as passed to the groupHeader setup option.

$("#example-table").tabulator("setGroupHeader", function(value, count, data, group){
    //value - the value all members of this group share
    //count - the number of rows in this group
    //data - an array of all the row data objects in this group
    //group - the group component for the group

    return count > 3; //all groups with more than three rows start open, any with three or less start closed
});

Note: If you use the setGroupStartOpen or setGroupHeader before you have set any groups on the table, the table will not update until the setGroupBy function is called.

Get Group Components

You can use the getGroups function to retrieve an array of all the first level Group Components in the table.

var groups = $("#example-table").tabulator("getGroups");

Movable Rows and Grouping

If you move a row between groups, its values will be updated to match those of the new group.

If you move or delete the last row in a group out of that group, that group will be removed.

Callbacks

A range of callbacks are avaialble for grouping. See the Group Callbacks section for more information.

Selectable Rows

Row selection allows users to select and highlight a number of rows that you can then take action on. This allows rows to be selected in a number of ways:

  • Clicking on a row, to toggle its state.
  • Holding down the shift key and click dragging over a number of rows to toggle the state of all rows the cursor passes over.
  • Programmatically with the selectRow and deselectRow functions.

To enable row selection, set the selectable option to true

$("#example-table").tabulator({
	selectable:true,
});

The selectable option can take one of a several values:

  • false - selectable rows are disabled
  • true - selectable rows are enabled, and you can select as many as you want
  • integer - any integer value, this sets the maximum number of rows that can be selected (when the maximum number of selected rows is exceded, the first selected row will be deselected to allow the next row to be selected).
  • "highlight" (default) - rows have the same hover stylings as selectable rows but do not change state when clicked. This is great for when you want to show that a row is clickable but don't want it to be selectable.

Note: using the setData function will clear the currently selected rows.

Rolling Selection

By default, row selection works on a rolling basis, if you set the selectable option to a numeric value then when you select past this number of rows, the first row to be selected will be deselected. If you want to disabled this behaviour and instead prevent selection of new rows once the limit is reached you can set the selectableRollingSelection option to false.

$("#example-table").tabulator({
    selectable:5,
    selectableRollingSelection:false, // disable rolling selection
});

Persistent Selection

By default Tabulator will maintain selected rows when the table is filtered, sorted or paginated (but NOT when the setData function is used). If you want the selected rows to be cleared whenever the table view is updated then set the selectablePersistence option to false.

$("#example-table").tabulator({
    selectable:true,
    selectablePersistence:false, // disable rolling selection
});

Selection Eligibility

You many want to exclude certain rows from being selected. The selectableCheck options allows you to pass a function to check if the current row should be selectable, returning true will allow row selection, false will result in nothing happening. The function should accept a RowComponent as its first argument.

$("#example-table").tabulator({
    selectableCheck:function(row){
        //row - row component
        return row.getData().age > 18; //alow selection of rows where the age is greater than 18
    },
});

Note: Any selectable rows will be assigned the tabulator-selectable class, any unselectable rows will be assigned the tabulator-unselectable class.

Programmatic Row Selection

As well as clicking on a row, you can trigger the selection or deselection of a row programmatically.

Select Row

To programmatically select a row you can use the selectRow function.

To select a specific row you can pass the any of the standard row component look up options into the first argument of the function. If you leave the argument blank you will select all rows (if you have set the selectable option to a numeric value, it will be ignored when selecting all rows).

$("#example-table").tabulator("selectRow", 1); //select row with id of 1

If you want to select multiple rows you can pass an array of row component look up options into the first parameter

If you do not pass any arguments to the selectRow function, all rows will be selected. To select only rows that have been filtered pass true as the first argument.

Deselect Row

To programmatically deselect a row you can use the deselectRow function.

To deselect a specific row you can pass any of the standard row component look up options into the first argument of the function. If you leave the argument blank you will deselect all rows.

$("#example-table").tabulator("deselectRow", 1); //deselect row with id of 1

If you want to deselect multiple rows you can pass an array of row component look up options into the first parameter

Note: If you do not pass any arguments to the the deselectRow function, all rows will be deselected.

Selection With Row Components

You can use the row component passed into any of Tabulator's callbacks to trigger selection of that row.

$("#example-table").tabulator({
        rowClick:function(e, row){
        //e - the click event object
        //row - row component

        row.toggleSelect(); //toggle row selected state on row click
    },
});

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

Get Selected Data

To get the data objects for the selected rows you can use the getSelectedData function.

This will return an array of the selected rows data objects in the order in which they were selected.

var selectedData = $("#example-table").tabulator("getSelectedData"); //get array of currently selected data.

Get Selected Row Components

To get the RowComponent's for the selected rows at any time you can use the getSelectedRows function.

This will return an array of RowComponent's for the selected rows in the order in which they were selected.

var selectedRows = $("#example-table").tabulator("getSelectedRows"); //get array of currently selected row components.

Callbacks

A range of callbacks are avaialble for row selection. See the Selection Callbacks section for more information.

Movable Rows and Columns Updated

Movable Rows

To allow the user to move rows up and down the table, set the movableRows parameter in the options:

$('#example-table').tabulator({
    movableRows: true, //enable user movable rows
})

This will allow users to drag rows around by clicking and dragging on any part of the row.

Callbacks

The rowMoved callback will be triggered when a row has been successfully moved. You can use this function to trigger any ajax requests or other updates needed upon a successfull row move.

$("#example-table").tabulator({
    rowMoved:function(row){
        //row - row component
    }
});

Row Handles

If you would prefer the user only be able to move a column around by one particular cell, the you can set the rowHandle property to true in the column definition object for that column to restrict the trigger for row movment to that cell only.

$('#example-table').tabulator({
    movableRows: true, //enable user movable rows
    columns:[
        {rowHandle:true, formatter:"handle", headerSort:false, frozen:true, width:30, minWidth:30},
        {title:"name", field:"name"} //normal column
    ]
})

Moving on Touch Devices

The jQuery library does not currently support touch events. To enable movable rows on a touch device, you will need to include the excellent touchpunch.js library which adds touch event support touch event support to jQuery.

Movable Rows and Grouping

If you move a row between groups, its values will be updated to match those of the new group.

If you move the last row in a group out of that group, that group will be removed.

Moving Rows Between Tables New

Tabulator also allows you to move rows between tables. To enable this you should supply either a valid jquery selector string or a jQuery selection to the movableRowsConnectedTables option

$('#example-table').tabulator({
    movableRows: true, //enable movable rows
    movableRowsConnectedTables: "#table2, #table3", //connect to these tables
})
$('#example-table').tabulator({
    movableRows: true, //enable movable rows
    movableRowsConnectedTables: $("#table2, #table3"), //connect to these tables
})

Connections to receiving tables are established when a row starts being dragged, so the receving tables do not need to exists when the sending table is created

Note: When moving rows between tables is enabled, you will no longer be able to move rows around inside the sending table.

Row Movement Lifecycle

When you move a row between table, a series of events take place. In the lifecycle below the sending table is where the row is being moved from, and the receiving tables are any tables that the sending table is connected to.

Sending Connections Started

The tabulator-movingrow-sending class is applied to the sending table element and the movableRowsSendingStart callback is called

Receiving Connections Started

The tabulator-movingrow-receiving class is applied to all receiving table elements and the movableRowsReceivingStart callback is triggered

Row Received

When the moving row is dropped on the receving table the movableRowsReceiver function is triggered, if it returns true the movableRowsReceived callback is triggered, otherwise the movableRowsSentFailed is triggered

Row Sent

If the row is successfully received then the movableRowsSender function is triggered and the movableRowsSent callback is triggered, if it failed then the movableRowsReceivedFailed callback is triggered

Close Sending Connection

The sending table closes its connections to other tables, removes the tabulator-movingrow-sending class from its table element and triggers the movableRowsSendingStop callback.

Close Receiving Connection

Each receving table then closes its connection, removes the tabulator-movingrow-receiving class from its table element and triggers the movableRowsReceivingStop callback

Receiver Function

The movableRowsReceiver option should be set on the receiving tables, and sets the action that should be taken when the row is dropped into the table.

There are several inbuilt receiver functions:

  • insert - inserts row next to the row it was dropped on, if not dropped on a row it is added to the table (default)
  • add - adds row to the table
  • update - updates the row it is dropped on with the sent rows data
  • replace - replaces the row it is dropped on with the sent row
$('#example-table').tabulator({
    movableRowsReceiver: "add", //add rows when dropped on the table
})

You can also pass a callback to the movableRowsReceiver option for custom receiver functionality. the callback must return a boolean to indicate whether the drop should be considered successfull or not (eg. you may want to reject a drop if it was not on a row)

//custom receiver function - update only one value of the toRow and only if the fromRow is dropped on a row
var customReceiver = function(fromRow, toRow, fromTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //fromTable - the jQuery element for the sending table

    if(toRow){
        toRow.update({"name":fromRow.getData().name});
        return true;
    }

    return false;
}

//set custom receiver
$('#example-table').tabulator({
    movableRowsReceiver: customReceiver,
})

Sender Function

The movableRowsSender option should be set on the sending table, and sets the action that should be taken after the row has been successfully dropped into the receiving table.

There are several inbuilt sender functions:

  • false - do nothing(default)
  • delete - deletes the row from the table
$('#example-table').tabulator({
    movableRowsSender: "delete", //remove the row from this table after it is successfully received
})

You can also pass a callback to the movableRowsSender option for custom sender functionality.

//custom receiver function - increment a moved column on the sent row
var customSender = function(fromRow, toRow, toTable){
    //fromRow - the row component from the sending table
    //toRow - the row component from the receiving table (if available)
    //toTable - the jQuery element for the receiving table

    fromRow.update({moved:fromRow.getData().moved + 1})
}

//set custom receiver
$('#example-table').tabulator({
    movableRowsSender: customSender,
})

Callbacks

A range of callbacks are avaialble for row movement between tables. See the Row Movement Callbacks section for more information.

Scroll To Row Updated

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 poition of the row, it should be a string with a value of either top, center, bottom or nearest, if ommitted 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 shoud scroll if the row is already visible, true to scroll, false to not, if ommitted it will be set to the value of the scrollToRowIfVisible option, which defaults to true

$("#example-table").tabulator("scrollToRow", 23, "center", false); //scroll row with id of 23 to the center if not already visible

The function will return true if it was successfull, or false if it was unable to scroll to the row for any reason.

Default ScrollTo Position New

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
$('#example-table').tabulator({
    scrollToRowPosition: "center", //position row in the center of the table when scrolled to
})

Default ScrollTo If Visible New

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 dont move
$('#example-table').tabulator({
    scrollToRowIfVisible: false, //prevent scrolling to a row if it is visible
})

Partially Visible Rows
If a row is not entierly visible, ie. it is partially scrolled out of view, it will be counted as not visible and the scroll action will occur.

Movable Columns

To allow the user to move columns along the table, set the movableColumns parameter in the options:

$('#example-table').tabulator({
    movableColumns: true, //enable user movable columns
})

This will allow users to drag columns around using the column headers at the top of the table.

Scroll To Column Updated

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 poition of the column, it should be a string with a value of either left, middle or right, if ommitted 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 shoud scroll if the column is already visible, true to scroll, false to not, if ommitted it will be set to the value of the scrollToColumnIfVisible option, which defaults to true

$("#example-table").tabulator("scrollToColumn", "age", "middle", false); //scroll column with field of "age" to the middle if not already visible

The function will return true if it was successfull, or false if it was unable to scroll to the column for any reason.

Default ScrollTo Position New

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
$('#example-table').tabulator({
    scrollToColumnPosition: "center", //position column in the center of the table when scrolled to
})

Default ScrollTo If Visible New

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 dont move
$('#example-table').tabulator({
    scrollToColumnIfVisible: false, //position column in the middle of the table when scrolled to
})

Partially Visible Columns
If a column is not entierly visible, ie. it is partially scrolled out of view, it will be counted as not visible and the scroll action will occur.

Callbacks

A range of callbacks are avaialble for row and column movements. See the Row Callbacks and Column Callbacks sections for more information.

Column Management

Set New Column Definitions

To update the current column definitions for a table use the setColumns function. This function takes a column definition array as its only argument.

//new column definition array
var newColumns = [
    {title:"Name", field:"name", sorter:"string", width:200},
    {title:"Age", field:"age", sorter:"number", align:"right", formatter:"progress"},
    {title:"Height", field:"height", formatter:"star", align:"center", width:100},
    {title:"Favourite Color", field:"col", sorter:"string"},
    {title:"Date Of Birth", field:"dob", sorter:"date", align:"center"},
],

$("#example-table").tabulator("setColumns", newColumns) //overwrite existing columns with new columns definition array

Add Column

If you wish to add a single column to the table, you can do this using the addColumn function.

$("#example-table").tabulator("addColumn", {title:"Age", field:"age"}, true, "name");

This function takes three arguments:

  • Columns Definition - The column definition object for the column you want to add.
  • Before (optional) - Determines how to position the new column. A value of true will insert the column to the left of exisiting columns, a value of false will insert it to the right. If a Position argument is supplied then this will determine whether the new colum is inserted before or after this column.
  • Position (optional) - The field to insert the new column next to, this can be any of the standard column component look up options.

Delete Column

To permanently remove a column from the table deleteColumn function. This function takes any of the standard column component look up options as its first parameter.

$("#example-table").tabulator("deleteColumn", "name");

Alternativly if you have the Column Component of the column you wish to delete, you can call the delete function directly on the component.

column.delete();

Get Column Definitions

To get the current column definition array (including any changes made through user actions, such as resizing or re-ordering columns), call the getColumnDefinitions function. this will return the current columns definition array.

var colDefs = $("#example-table").tabulator("getColumnDefinitions") //get column definition array

Get Column Components Updated

To get an array of Column Components for the current table setup, call the getColumns function. This will only return actual data columns not column groups.

var cols = $("#example-table").tabulator("getColumns") //get array of column components

To get a strutured array of Column Components that includes column groups, pass a value of true as an argument.

var cols = $("#example-table").tabulator("getColumns", true) //get a structured array of column components

This will return an array of Column Components for the top level columns, whether they are columns or column groups. You can then use the getSubColumns and getParentColumn functions on each component to navigate through the column hierachy.

Editable Column Titles

Column titles can be made user editable by setting the editableTitle parameter to true in a columns definition object.

{title:"Name", field:"name", editableTitle:true} //alow user to update this columns title

This will result in the columns title being displayed in an input element, that will let the user change the title.

After a the user changes a column title the colTitleChanged callback is triggered.

("#example-table").tabulator({
    colTitleChanged:function(value, col, cols){
        //value - the new column value
        //col - the updated column definition object for the affected column
        //cols - the updated column definition array for all columns in the table
    },
});

Column Visibility

Column visibility can be set in a number of different ways.

Column Definition Visibility

You can set the column visibility when you create the column definition array:

{title:"Name", field:"name", visible:false}, //create hidden column for the field "name"

By default columns are set with a visible parameter value of true.

Show Column

You can show a hidden column at any point using the showColumn function. Pass the field name of the column you wish to show as the first parameter of the function.

$("#example-table").tabulator("showColumn","name") //show the "name" column

Alternativly if you have the ColumnComponent of the column you wish to show, you can call the show function directly on the component.

column.show();

Hide Column

You can hide a visible column at any point using the hideColumn function. Pass the field name of the column you wish to hide as the first parameter of the function.

$("#example-table").tabulator("hideColumn","name") //hide the "name" column

Alternativly if you have the ColumnComponent of the column you wish to hide, you can call the hide function directly on the component.

column.hide();

Toggle Column

You can toggle the visibility of a column at any point using the toggleColumn function. Pass the field name of the column you wish to toggle as the first parameter of the function.

$("#example-table").tabulator("toggleColumn","name") ////toggle the visibility of the "name" column

Alternativly if you have the ColumnComponent of the column you wish to toggle, you can call the toggle function directly on the component.

column.toggle();

Callbacks

A range of callbacks are avaialble for columns. See the Column Callbacks section for more information.

CSS Classes & Theming Updated

As of version 2.1 all Tabulator elements are styled using a range CSS classes to make it easier for you to manipulate the look, feel and function of the table.

A SASS file is also provided for each stylesheet, containing a set of variables to make generating your own theme even easier. These can be found in the src/scss directory

Packaged Themes

As well as the default theme, tabulator comes with a number of pre packaged themes. To use one of these simply include the matching css file instead of the default tabulator.css

All stylesheets can be found in the /dist/css directory, with standard CSS and minified versions available.

For example to use the simple theme, you would need to use the following css link:

<link href="/dist/css/tabulator_simple.min.css" rel="stylesheet">

Alongside the default theme, the following packaged themes are available:

  • Simple - A plain, simplistic layout showing only basic grid lines. (/themes/tabulator_simple.css)
  • Midnight - A dark, stylish layout using simple shades of grey. (/themes/tabulator_midnight.css)
  • Modern - A neat, stylish layout using one primary color. (/themes/tabulator_modern.css)
  • Site - The theme used for tables on this site.

Framework Themes Updated

Tabulator also comes with a number of themes to ie in with popular frontend layout frameworks.

Bootstrap 3 Theme

A Bootstrap 3 compatible theme that can be included from:

<link href="/dist/css/bootstrap/tabulator_bootstrap.min.css" rel="stylesheet">

The stylesheet maps the standard bootstrap table styling onto Tabulator. If you have customised your bootstrap theme, then the /src/scss/bootstrap directory also contains a variables.scss file containing all the standard bootstrap variables. Make any changes in here to match your custom theme and recompile the tabulator_bootstrap.css file and Tabulator will now match your theme.

The theme also maps some of the standard table styling classes. You can use any of these classes on your tablutor element and get the same effect as bootstrap:

  • table-striped - alternating row colors
  • table-bordered - borders around table and between cells
  • table-condensed - minimal cell and header padding

You can also apply the following classes to rows using the rowFormatter to get the same results as in bootstrap:

  • active
  • success
  • info
  • warning
  • danger
$("#example-table").tabulator({
    rowFormatter:function(row){
        if(row.getData().age >= 18){
            row.getElement().addClass("success"); //mark rows with age greater than or equal to 18 as successfull;
        }
    },
});

For full details on the bootstrap table layout, checkout the Bootstrap Website.

Bootstrap 4 Theme New

A Bootstrap 4 compatible theme that can be included from:

<link href="/dist/css/bootstrap/tabulator_bootstrap4.min.css" rel="stylesheet">

The stylesheet maps the standard bootstrap table styling onto Tabulator. If you have customised your bootstrap theme, then the /src/scss/bootstrap directory also contains a variables4.scss file containing all the standard bootstrap variables. Make any changes in here to match your custom theme and recompile the tabulator_bootstrap4.css file and Tabulator will now match your theme.

The theme also maps some of the standard table styling classes. You can use any of these classes on your tablutor element and get the same effect as bootstrap:

  • thead-dark - inverted header colour scheme
  • table-dark - inverted colour scheme
  • table-light - light header on dark table body (when used with table-dark)
  • table-striped - alternating row colors
  • table-bordered - borders around table and between cells
  • table-borderless - no borders anywhere on the table
  • table-sm - minimal cell and header padding

You can also apply the following classes to rows or cells using the rowFormatter option or the formatter column definition property, to get the same results as in bootstrap:

  • table-primary
  • table-secondary
  • table-success
  • table-info
  • table-warning
  • table-danger
  • table-light
  • table-dark
  • table-active
  • bg-primary
  • bg-secondary
  • bg-success
  • bg-info
  • bg-warning
  • bg-danger
  • bg-light
  • bg-dark
  • bg-active
$("#example-table").tabulator({
    rowFormatter:function(row){
        if(row.getData().age >= 18){
            row.getElement().addClass("table-primary"); //mark rows with age greater than or equal to 18 as successfull;
        }
    },
});

For full details on the bootstrap table layout, checkout the Bootstrap 4 Website.

Semantic UI Theme

A Semantic UI compatible theme that can be included from:

<link href="/dist/css/semantic-ui/tabulator_semantic-ui.min.css" rel="stylesheet">

The stylesheet maps the standard semantic ui table styling onto Tabulator. If you have customised your theme, then the /src/scss/semantic-ui directory also contains the variables.scss and variables_table.scss files containing all the standard semantic ui variables. Make any changes in here to match your custom theme and recompile the tabulator_semantic-ui.css file and Tabulator will now match your theme.

The theme also mape some of the standard table styling classes. You can use any of these classes on your tablutor element and get the same effect as semantic ui:

  • striped - alternating row colors
  • celled - borders between cells
  • compact - minimal cell and header padding
  • very compact - almost no cell and header padding
  • padded - more cell and header padding
  • very padded - a lot more cell and header padding

The full range of colour classes can also be used:

  • inverted
  • red
  • orange
  • yellow
  • olive
  • green
  • teal
  • blue
  • violet
  • purple
  • brown
  • grey
  • black

You can also apply the following classes to rows or cells using the rowFormatter to get the same results as in semantic ui:

  • positive
  • negative
  • error
  • warning
  • active
  • disabled
$("#example-table").tabulator({
    rowFormatter:function(row){
        if(row.getData().age < 18){
            row.getElement().addClass("warning"); //mark rows with age less than 18 with a warning state;
        }
    },
});

For full details on the Semantic UI table layout, checkout the Semantic UI Website.

CSS Classes Updated

All elements of Tabulator have classes set to make theming your tables as easy as possible.

General Classes Updated

Class Element Description
tabulatorTabulator container element
tabulator-tableHolderContain table and scroll bars
tabulator-tableContain table rows
tabulator-loaderAjax loader message holder
tabulator-loader-msgAjax loader message
tabulator-loadingApplied to .tabulator-load-msg to style a loading message
tabulator-errorApplied to .tabulator-load-msg to style an error message
tabulator-placeholderThe containing element for the empty table placeholder
tabulator-movingApplied to rows and columns when they are being moved
tabulator-block-selectApplied to the .tabulator element when the mouse is dragging to prevent accidental text selection
tabulator-movingApplied to rows and columns when they are being moved
tabulator-movingrow-sendingApplied to table when it is sending a row to another table
tabulator-movingrow-receivingApplied to table when it is receiving a row from another table

Headers & Columns

Class Element Description
tabulator-headerTable header element
tabulator-headersHold all column headers inside table header
tabulator-calcs-holderHold column calculations row, appears in both header and footer
tabulator-colColumn header (in header row)
tabulator-col-contentHolds the contents for the column header
tabulator-col-titleHolds the text for the column header title
tabulator-col-groupMarks a column header as a group that contains other columns
tabulator-col-group-colsHolds the column headers contained in a column group
tabulator-handleInvisible resize handle on the right of each column header
tabulator-title-editorThe input box used for editing titles when the editableTitle option is set
tabulator-header-filterThe containing element for the header filter elements, when the headerFilter option is set
tabulator-sortableApplied to columns with header sorting enabled
tabulator-frozenThe containing element for all frozen columns
tabulator-frozen-leftApplied to frozen columns on the left edge of the table
tabulator-frozen-rightApplied to frozen columns on the right edge of the table
tabulator-row-resize-handleContainer for frozen rows in the header

Rows Updated

Class Element Description
tabulator-rowRow of table
tabulator-row-oddOdd numbered row
tabulator-row-evenEven numbered row
tabulator-cellData cell
tabulator-selectableStyling for selectable rows
tabulator-unselectableStyling for unselectable rows
tabulator-selectedCurrently selected row
tabulator-editingApplied to cells being edited and the rows that contain them
tabulator-validation-failApplied to cells being edited that have failed validation
tabulator-groupThe header element for a row group
tabulator-group-visibleApplied to .tabulator-group when the group is visible
tabulator-group-level-XApplied to .tabulator-group to denote its level in multi level grouping, the X is replaced with the number of that grouping level
tabulator-calcsA row that contains column calculations instead of data
tabulator-calcs-topA column calculations row at the top of a group
tabulator-calcs-bottomA column calculations row at the bottom of a group
tabulator-row-handleA cell that is setup as a row handle
tabulator-row-handle-boxcontaining element for the row handle icon
tabulator-row-handle-barone of the bars in the row handle icon
tabulator-row-resize-handleInvisible resize handle on the top and bottom of each row
tabulator-responsive-collapseElement to hold collapsed column data in responsive layout mode

Pagination

Class Element Description
tabulator-footerTabulator footer element
tabulator-paginatorContains the pagination controls
tabulator-pagesContains individual page buttons
tabulator-pagePage selection button

SASS Variables

The packaged SASS theme files is included in the project with a number of setup variables to make theming a table even easier.

General

Variable Default Value Description
backgroundColor#888The background colour of the tabulator element
borderColor#999The border colour of the tabulator element
textSize14The text size for all text in the tabulator

Headers & Columns

Variable Default Value Description
headerBackgroundColor#e6e6e6The background colour for header cells
headerTextColor#555The header cells text colour
headerBorderColor#aaaThe header cells border colour
headerSeperatorColor#999The header row bottom border colour
headerMargin4The size in pixels for the header cells margin
sortArrowActive#666The colour of the column sorter arrow when sorting is active on a column
sortArrowInactive#bbbThe colour of the column sorter arrow when sorting is not active on a column

Rows

Variable Default Value Description
rowBackgroundColor#fffThe background colour of the table rows
rowAltBackgroundColor#e0e0e0The background colour of the even numbered table rows
rowBorderColor#fffThe table row border colour
rowTextColor#333The table row text colour
rowHoverBackground#bbbThe table row background colour when hovered over.
rowSelectedBackground#9ABCEAThe table row background colour when selected.
rowSelectedBackgroundHover#769BCCThe table row background colour when selected and hovered over.
editBoxColor#1D68CDThe border colour of a cell being edited.

Pagination

Variable Default Value Description
footerBackgroundColor#e6e6e6The footer background colour
footerTextColor#555The footer text colour
footerBorderColor#aaaThe footer buttons border colour
footerSeperatorColor#999The footer element top border colour

Architecture Concepts New

When you load your data into Tabulator, a lot goes on behind the sceens to transform that raw data into an interactive table with all the features Tabulator has to offer.

This section aims to give you an overview of how Tabulator works its magic so you can have a better understanding of how to use it to its full potential.

Table Initialisation

When you first instatiate your tabulator it does through the following steps to turn a simple div element into a Tabulator.

Deprication Check

Check through the setup options for anything on the depricated functionality list, if it finds any, it triggers a console warning and then updates the setting to the correct format.

Bind Extensions

Find all the registered extensions and bind them to this table.

Check for HTML Table

Check if the table was created from an HTML table element, if so parse in data and setup options from the table.

Create Core Objects

Create the management objects that will handle the table columns, rows and footer.

Fire tableBuilding Event

The tableBuilding callback is triggered

Determine Render Mode

Check to see if a height has been set on the table, if it has enable the Virtual Dom rendering mode, otherwise fallback to the standard mode.

Detect Browser

Detect the current browser and engage any performance fallbacks needed (ie, simplify rendinging for older browsers like IE).

Configure Table

Use setup options to configure the table

Fire tableBuilt Event

The tableBuilt callback is triggered

Load Initial Data

Load the initial data into the table, this can either be from the data option, the ajaxURL option, or an empty array if nothing is set

Basic Data Lifecycle

When data is loaded into the table, Tabulator performs a series of actions on the data to transform it into the rows you see displayed on the table

Clear Old Data

If the data is loaded in a way that replaces the old data (for example calling the setData function), the previous rows are destroyed before the new data is loaded in.

Parse Data Find Out More

Check type of data and convert from JSON & HTML into an array of objects, then convert these objects into RowComponents.

Row Management Pipeline Find Out More

Process data to make sure it is correctly ordered for display, apply filters, sorters, groups, paging etc.

Rendering Find Out More

Display the rows on the table.

Data Parsing

When data is loaded into the table, either directly through one of the config options or the setData function, or through an ajax request Tabulator performs a series of operations on the data to transform it into the RowComponents that are used to build the table.

Parse Data

Check type of data and convert from JSON & HTML into an array of objects.

Mutate Data

Apply any matching mutators to the row data.

Create Row Component

Pass each data object in the array to a new RowComponent and create an empty row DOM element.

Initialize Extensions

Initialize row specific extensions such as Movable Rows and Selectable Rows.

Bind Events

Bind click an touch events to the row DOM element.

Store

Store the newly created RowComponent in an array of all table rows.

Delayed Row Rendering
It is important to note that no data is rendered directly to the display when it is parsed into the system. To speed up the parsing of data, it is attached to RowComponents but is only rendered later when that row is actually needed to be displayed in the Virtual DOM.

Row Management Pipeline

Before the rows can be displayed on the table, they must be processed to ensure that they arranged correctly, matching the current table setup.

The pipeline outlined below can be started at any point depending on the triggering event, for example if the grouping setup of the table is changed only the grouping part onwards is executed as the data before it in the pipeline will not have changed.

Filter Rows

Apply all filters (programatic and header filters) and remove rows that do not match.

Sort Rows

Reorder the filtered data by applying the sorters to it.

Handle Frozen Rows

Extract and frozen rows from the sorted rows and append them to the header.

Group Rows

If groups are enabled, group the rows and inject the group header elements into the row data.

Page Rows

If pagination is enable, only take the rows that correspond to the current page.

Virtual DOM Rendering

There are two rendering modes in Tabulator, Virtual DOM mode, which allows 100,000's of rows to be processed without performance overhead and standard mode, which is fallback incase the VIrutal DOM cant be used, it renders all the rows into the table as soon as they are pass through the row management pipeline.

As the standard render mode simply renders rows as they are loaded into the table there is minimal explantion needed. In this section We will cover the inner workings of the Vitual DOM mode in more detail.

Visible Row Window

To make the table more responsive the table only renders a subset of the total rows called the window.

The window contains all visible rows. In addition to these it also contains a table heights worth of rows above and below the visible rows, called buffers, these allows the user to scroll the table, with the rows being added and removed out of sight of the visible area.

The scroll bar is maintained by adding top and bottom padding to the window, equivalent to the remaining rows in the table above and below the window.

Scrolling the table

In this example we will talk about what happens when the table is scrolled, we will use a scroll down for the example, but the process can be reversed for scrolling up.

User scrolls the table

The user triggers a scroll event, with the mouse scroll wheel, scroll bar or down arrow key.

Add Next Row

When the user has scrolled down the height of the next row it is added to the bottom of the window.

The window's bottom padding is adjusted to compensate for the change in height.

Initialize Next Row

If the row has never been rendered before, or is dirty (eg. the data or layout has changed since it was last rendered) it is initialized. Its CellComponents are generated, the rowFormatter is called and its DOM element it filled.

If the row has already been initialised the existing element is displayed.

Remove Old Row

When the user has scrolled down the height of the first row in the window, the row is removed from the window. The elements are preserved incase it needs to be shown again, they are just removed from the DOM.

The window's top padding is adjusted to compensate for the change in height.

Table Fill

When the table is scrolled more than the height of the window in one go, or when the data is replaced (eg. the setData function is called), the window is emptied of all rows and the following method is used to rebuild the layout.

Clear the Window

Empty all rows from the window and clear all padding.

Find Top Row

Givent the current vertical scroll position of the table, work out what the top most visible row should be.

Generate Top Window Buffer

Working back from the top visible row, prepend enough rows to the top of the window to generate a buffer of 1x the table height.

If there are not enough rows to do this, go as far as the start of the row array and stop.

Add Visible Rows

Working from the top visible row, append enough rows to to the window to fill the visible table height.

If there are not enough rows, go as far as the end of the row array and stop

Generate Bottom Window Buffer

working from the bottom visible row, append enough rows to the window to generate a buffer of 1x the table height.

if there are not enough rows, fo as far as the end of the row array and stop

Initialize Rows

loop through all the rows in the window, if the row has never been rendered before, or is dirty (eg, the data or layout has changed since it was last rendered) it is initialized. Its CellComponents are generated, the rowFormatter is called and its DOM element it filled.

If the row has already been initialised the existing DOM is displayed

Pad Window

Add the nessisary top and bottom padding to position the window in the correct place in the table

Scroll to window

Adjust the vertical scroll position of the table to align the top row of the window with the top of the table element

Configuration Options

Details on how to configure the Virtual DOM can be Found Here.

Component Objects Updated

Component objects allow you to interact directly with various parts of your tables. They are usually passed in the arguments of callbacks and expose a range of functions that can be called directly on the object.

Row Component

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

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

        if(data.col == "blue"){
            row.getElement().css({"background-color":"#A6A6DF"}); //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 jQuery DOM element for the row.

var rowElement = row.getElement();

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 cells = 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 ros position in the table)

var rowIndex = row.getIndex();

Get Position

Use the getPosition function to retreive 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 retreive 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();

Scroll To

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

row.scrollTo();

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"

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

Normalize Height

If you are making manual adjustments to elements conained 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();

Column Component Updated

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

$("#example-table").tabulator({
    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 jQuery DOM element for the column.

var columnElement = column.getElement();

Get Definition

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

var columnDefinition = column.getDefinition();

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 Visibility

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

var visible = column.getVisibility();

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

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

Get Sub Columns New

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

var subColumns = column.getSubColumns();

Get Parent Column New

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

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. Very usefull 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 Element

The getElement function returns the jQuery DOM element for the cell.

var cellElement = cell.getElement();

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 programatically 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 programatically cancel a cell edit that is currently in progress by calling the cancelEdit function.

cell.cancelEdit();

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 navigat 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

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.

$("#example-table").tabulator({
    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 jQuery DOM element for the gruop header.

var groupElement = group.getElement();

Get Key

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

var key = group.getKey();

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 getVisibility function returns a boolean to show if the group is visible, a value of true means it is visible.

var visible = group.getVisibility();

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

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 iteslf. The following values can be used for each copmonent type:

Row

  • A RowComponent
  • The index value of the row
  • jQuery Element of the row

Column

  • A ColumnComponent
  • The field name of the column
  • jQuery Element of the column

Cell

Setup Options Updated

Tabulator has a wide range of setup options to help you customise the user experience of your tables. This section outlines all the available options and links to the relevant section in this documentation to show you how to use them.

Each of these options can be set in the constructor object when you define your Tabulator.

$("#example-table").tabulator({
    height:"300px", //set the table height option
});

General Table Configuration Updated

Option Data Type Default Value Description
heightstring/intfalseSets the height of the containing element, can be set to any valid height css value. If set to false (the default), the height of the table will resize to fit the table data.
virtualDombooleantrueEnable rendering using the Virtual DOM engine
virtualDomBufferintegerfalseManually set the size of the virtual DOM buffer
placeholderstring or element""placeholder element to display on empty table
footerElementJQuery Element(see documentation)Footer element for the table
tooltipsboolean/functionfalseFunction to generate tooltips for cells
tooltipGenerationModestring"load"When to regenerate cell tooltip value
historyboolean/functionfalseEnable user interaction history functionality
keybindingsboolean/functionfalseKeybinding configuration object
localestring/booleanfalseset the current localization language
langsobject(see documentation)hold localization templates
downloadDataFormatterfunctionfalsecallback function to alter table data before download

Columns Updated

Option Data Type Default Value Description
columnsarray[]Holder for column definition array
layoutstring"fitData"Layout mode for the table columns
layoutColumnsOnNewDatabooleanfalseChange column widths to match data when loaded into table
responsiveLayoutbooleanfalseAutomatically hide/show columns to fit the width of the Tabulator element
responsiveLayoutCollapseStartOpenbooleantrueshow collapsed column list
responsiveLayoutCollapseUseFormattersbooleantrueuse formatters in collapsed column lists
responsiveLayoutCollapseFormatterfunctioncreate contents of collapsed column list
columnMinWidthCSS width value40pxMinimum width for a column
resizableColumnsbooleantrueAllow user to resize columns (via handles on the left and right edges of the column header)
movableColumnsbooleanfalseAllow users to move and reorder columns
tooltipsHeaderboolean/functionfalseFunction to generate tooltips for column headers
columnVertAlignstringtopVertical alignment for contents of column header (used in column grouping)
headerFilterPlaceholderstring"filter column..."The placeholder text to be set in any header filter input elements
scrollToColumnPositionstring"left"Default column position after scrollToColumn
scrollToColumnIfVisiblebooleanfalseAllow currently visible columns to be scrolled to
columnCalcsstring/booleantrueWhere to show column calcs in table

Rows Updated

Option Data Type Default Value Description
rowFormatterfunction/booleanfalseFunction to alter layout of rows
addRowPosstring"bottom"The position in the table for new rows to be added, "bottom" or "top"
selectableboolean/integer/string"highlight"Enable/Disable row selection
selectableRollingSelectionbooleantrueAllow rolling selection
selectablePersistencebooleantrueMaintain selected rows on filter or sort
selectableCheckfunction(see documentation)Check if row should be selectable or unselectable
movableRowsbooleanfalseAllow users to move and reorder rows
movableRowsConnectedTablesstring/jQueryfalseConnection selector for receving tables
movableRowsSenderstring/function/booleanfalseSender function to be executed when row has been sent
movableRowsReceiverstring/function"insert"Sender function to be executed when row has been received
resizableRowsbooleanfalseAllow user to resize rows (via handles on the top and bottom edges of the row)
scrollToRowPositionstring"top"Default row position after scrollToRow
scrollToRowIfVisiblebooleanfalseAllow currently visible rows to be scrolled to

Data Updated

Option Data Type Default Value Description
indexstringidThe field to be used as the unique index for each row
dataarray[]Array to hold data that should be loaded on table creation
ajaxURLstring/booleanfalseURL for remote Ajax data loading
ajaxParamsobject{}Parameters to be passed to remote Ajax data loading request
ajaxConfigstring/object"GET"The HTTP request type for Ajax requests or config object for the request
ajaxFilteringbooleanfalseSend filter config to server instead of processing locally
ajaxSortingbooleanfalseSend sorter config to server instead of processing locally
ajaxProgressiveLoadbooleanfalseProgressively load data into the table in chunks
ajaxProgressiveLoadDelayinteger0Delay in milliseconds between each progressive load request
ajaxProgressiveLoadScrollMarginintegerfalseThe remaning distance in pixels between the scroll bar and the bottom of the table before an ajax is triggered
ajaxLoaderboolean/functiontrueShow loader while data is loading, can also take a function that must return a boolean
ajaxLoaderLoadingstringhtml (see below)html for loader element
ajaxLoaderErrorstringhtml (see below)html for the loader element in the event of an error

When loading data, Tabulator can display a loading overlay over the table. This consists of a modal background and a loader element. The loader element can be set globally in the options and should be specified as a div with a display style of inline-block.

Default loader element

<div style='display:inline-block; border:4px solid #333; border-radius:10px; background:#fff; font-weight:bold; font-size:16px; color:#000; padding:10px 20px;'>Loading Data</div>

Default loader error element

<div style='display:inline-block; border:4px solid #D00; border-radius:10px; background:#fff; font-weight:bold; font-size:16px; color:#590000; padding:10px 20px;'>Loading Error</div>

Initial Data Sorting

You can set initial sorters, specifying what sort should be applied when data is first loaded into the table.

Option Data Type Default Value Description
initialSortarray[]Array of sorters to be applied on load.

Groups

Option Data Type Default Value Description
groupBystring/function/arrayfalseString/function to select field to group rows by
groupHeaderfunction/array(see documentation)function to layout group header row
groupStartOpenboolean/function/arraytrueBoolean/function to set the open/closed state of groups when they are first created
groupToggleElementstring/boolean"arrow"Set which element triggers a group visibility toggle
groupClosedShowCalcsbooleanfalseshow/hide column calculations when group is closed

Pagination Updated

Option Data Type Default Value Description
paginationstringfalseChoose pagination method, "local" or "remote"
paginationSizeinteger10Set the number of rows in each page
paginationElementJQuery Element(generated tabulator footer)The element to contain the pagination selectors
paginationDataReceivedobject{
"current_page":"current_page",
"last_page":"last_page",
"data":"data",
}
Lookup list to link expected data feilds from the server to their function
paginationDataSentobject{
"page":"page",
"size":"size",
"sorters":"sorters",
"filters":"filters",
}
Lookup list to link fields expected by the server to their function
paginatorfunctionnullFunction used to build pagination request URL string
paginationAddRowstring"page"Set where rows should be added to the table

Persistent Configuration

Option Data Type Default Value Description
persistenceIDstringnullID tag used to identify persistent storage information
persistenceModeboolean/stringtrueStore persistence information in a cookie or localStorage
persistentLayoutbooleanfalseEnable persistsnt storage of column layout information
persistentSortbooleanfalseEnable persistsnt storage of sorting information
persistentFilterbooleanfalseEnable persistsnt storage of filtering information

Clipboard New

Option Data Type Default Value Description
clipboardbooleanfalseEnable clipboard extension
clipboardCopySelectorstring/function"active"Clipboard copy selector function
clipboardCopyFormatterstring/function"table"Clipboard copy formatter function
clipboardCopyHeaderbooleantrueEnable progressive rendering
clipboardPasteParserstring/functionfalseClipboard paste parser function
clipboardPasteActionstring/functionfalseClipboard paste action function

Callbacks & Events Updated

Tabulator features a range of callbacks to allow you to handle user interaction and system events.

These callbacks can all be set in the options object when you create your Tabulator.

Table Callbacks

Table Building

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

$("#example-table").tabulator({
    tableBuilding:function(){
    },
});

Table Built

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

$("#example-table").tabulator({
    tableBuilt:function(){
    },
});

Column Callbacks

Column Header Click

The headerClick callback is triggered when a user left clicks on a column or group header, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", headerClick:function(e, column){
        //e - the click event object
        //column - column component
    },
}

Column Header Double Click

The headerDblClick callback is triggered when a user double clicks on a column or group header, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", headerDblClick:function(e, column){
        //e - the click event object
        //column - column component
    },
}

Column Header Right Click

The headerContext callback is triggered when a user right clicks on a column or group header, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", headerContext:function(e, column){
        //e - the click event object
        //column - column component
    },
}

Column Header Tap

The headerTap callback is triggered when a user taps on the column header on a touch display, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", headerTap:function(e, column){
        //e - the tap event object
        //column - column component
    },
}

Column Header Double Tap

The headerDblTap callback is triggered when a user taps on the column header on a touch display twice in under 300ms, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", headerDblTap:function(e, column){
        //e - the tap event object
        //column - column component
    },
}

Column Header Tap Hold

The headerTapHold callback is triggered when a user taps on the column header on a touch display and holds their finger down for over 1 second, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", headerTapHold:function(e, column){
        //e - the tap event object
        //column - column component
    },
}

Column Moved

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

$("#example-table").tabulator({
    columnMoved:function(column, columns){
        //column - column component of the moved column
        //columns- array of columns in new order
    }
});

Column Resized

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

$("#example-table").tabulator({
    columnResized:function(column){
        //column - column component of the resized column
    }
});

Column Visibility Changed

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

$("#example-table").tabulator({
    columnVisibilityChanged:function(column, visible){
        //column - column component
        //visible - is column visible (true = visible, false = hidden)
    },
});

Column Title Changed

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

$("#example-table").tabulator({
    columnTitleChanged:function(column){
        //column - column component
    },
});

Row Callbacks

Row Click

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

$("#example-table").tabulator({
        rowClick:function(e, row){
        //e - the click event object
        //row - row component
    },
});

Row Double Click

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

$("#example-table").tabulator({
        rowDblClick:function(e, row){
        //e - the click event object
        //row - row component
    },
});

Row Context Menu

The rowContext callback 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 callback.

$("#example-table").tabulator({
    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 callback is triggered when a user taps on a row on a touch display.

$("#example-table").tabulator({
        rowTap:function(e, row){
        //e - the tap event object
        //row - row component
    },
});

Row Double Tap

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

$("#example-table").tabulator({
        rowDblTap:function(e, row){
        //e - the tap event object
        //row - row component
    },
});

Row Tap Hold

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

$("#example-table").tabulator({
        rowTapHold:function(e, row){
        //e - the tap event object
        //row - row component
    },
});

Row Added

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

$("#example-table").tabulator({
    rowAdded:function(row){
        //row - row component
    },
});

Row Updated

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

$("#example-table").tabulator({
    rowUpdated:function(row){
        //row - row component
    },
});

Row Deleted

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

$("#example-table").tabulator({
    rowDeleted:function(row){
        //row - row component
    },
});

Row Moved

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

$("#example-table").tabulator({
    rowMoved:function(row){
        //row - row component
    }
});

Row Resized

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

$("#example-table").tabulator({
    rowResized:function(row){
        //row - row component of the resized row
    }
});

Cell Callbacks Updated

Cell Click Updated

The cellClick callback is triggered when a user left clicks on a cell, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", cellClick:function(e, cell){
        //e - the click event object
        //cell - cell component
    },
}

The cellClick callback can also be set globally.

$("#example-table").tabulator({
    cellClick:function(e, cell){
        //e - the click event object
        //cell - cell component
    },
});

Cell Double Click Updated

The cellDblClick callback is triggered when a user double clicks on a cell, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", cellDblClick:function(e, cell){
        //e - the click event object
        //cell - cell component
    },
}

The cellDblClick callback can also be set globally.

$("#example-table").tabulator({
    cellDblClick:function(e, cell){
        //e - the click event object
        //cell - cell component
    },
});

Cell Right Click Updated

The cellContext callback is triggered when a user right clicks on a cell, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", cellContext:function(e, cell){
        //e - the click event object
        //cell - cell component
    },
}

The cellContext callback can also be set globally.

$("#example-table").tabulator({
    cellContext:function(e, cell){
        //e - the click event object
        //cell - cell component
    },
});

Cell Tap Updated

The cellTap callback is triggered when a user taps on a cell in this column on a touch display, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", cellTap:function(e, cell){
        //e - the tap event object
        //cell - cell component
    },
}

The cellTap callback can also be set globally.

$("#example-table").tabulator({
    cellTap:function(e, cell){
        //e - the tap event object
        //cell - cell component
    },
});

Cell Double Tap Updated

The cellDblTap callback is triggered when a user taps on a cell in this column on a touch display twice in under 300ms, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", cellDblTap:function(e, cell){
        //e - the tap event object
        //cell - cell component
    },
}

The cellDblTap callback can also be set globally.

$("#example-table").tabulator({
    cellDblTap:function(e, cell){
        //e - the tap event object
        //cell - cell component
    },
});

Cell Tap Hold Updated

The cellTapHold callback 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, it can be set on a per column basis using the option in the columns definition object.

{title:"Name", field:"name", cellTapHold:function(e, cell){
        //e - the tap event object
        //cell - cell component
    },
}

The cellTapHold callback can also be set globally.

$("#example-table").tabulator({
    cellTapHold:function(e, cell){
        //e - the tap event object
        //cell - cell component
    },
});

Cell Editing

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

$("#example-table").tabulator({
    cellEditing:function(cell){
        //cell - cell component
    },
});

The cellEditing callback can also be set in the column defintion object of a column

{title:"Name", field:"name", cellEditing:function(cell){
        //cell - cell component
    },
}

Cell Edit Cancelled

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

$("#example-table").tabulator({
    cellEditCancelled:function(cell){
        //cell - cell component
    },
});

The cellEditCancelled callback can also be set in the column defintion object of a column

{title:"Name", field:"name", cellEditCancelled:function(cell){
        //cell - cell component
    },
}

Cell Edited

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

$("#example-table").tabulator({
    cellEdited:function(cell){
        //cell - cell component
    },
});

The cellEdited callback can also be set in the column defintion object of a column

{title:"Name", field:"name", cellEdited:function(cell){
        //cell - cell component
    },
}

Data Callbacks

Data Loading

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

$("#example-table").tabulator({
    dataLoading:function(data){
        //data - the data loading into the table
    },
});

Data Loaded

The dataLoaded callback is triggered when a new set of data is loaded into the table.

$("#example-table").tabulator({
    dataLoaded:function(data){
        //data - all data loaded into the table
    },
});

Data Edited

The dataEdited callback is triggered whenever the table data is changed by the user. Triggers for this include editing any cell in the table, adding a row and deleting a row.

$("#example-table").tabulator({
    dataEdited:function(data){
        //data - the updated table data
    },
});

HTML Importing

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

$("#example-table").tabulator({
    htmlImporting:function(){
    },
});

HTML Imported

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

$("#example-table").tabulator({
    htmlImported:function(){
    },
});

Ajax Callbacks

Ajax Request

The ajaxRequesting callback is triggered when ever an ajax request is made.

$("#example-table").tabulator({
    ajaxRequesting:function(url, params){
        //url - the URL of the request
        //params - the parameters passed with the request
    },
});

Returning a value of false from this callback will abort the ajax request

Ajax Response

The ajaxResponse callback is triggered when a successful ajax request has been made. This callback can also be used to modify the received data before it is parsed by the table. If you use this callback it must return the data to be parsed by Tabulator, otherwise no data will be rendered.

$("#example-table").tabulator({
    ajaxResponse:function(url, params, response){
        //url - the URL of the request
        //params - the parameters passed with the request
        //response - the JSON object returned in the body of the response.

        return response; //return the response data to tabulator
    },
});

Ajax Error

The ajaxError callback is triggered there is an error response to an ajax request.

$("#example-table").tabulator({
    ajaxError:function(xhr, textStatus, errorThrown){
        //xhr - the XHR object
        //textStatus - error type
        //errorThrown - text portion of the HTTP status
    },
});

Filter Callbacks

Data Filtering

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

$("#example-table").tabulator({
    dataFiltering:function(filters){
        //filters - array of filters currently applied

    },
});

Data Filtered

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

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

Sorting Callbacks

Data Sorting

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

$("#example-table").tabulator({
    dataSorting:function(sorters){
        //sorters - an array of the sorters currently applied
    },
});

Data Sorted

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

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

Layout Callbacks

Render Started

The renderStarted callback 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

$("#example-table").tabulator({
    renderStarted:function(){
    },
});

Render Complete

The renderComplete callback is triggered after the table has been rendered

$("#example-table").tabulator({
    renderComplete:function(){
    },
});

Pagination Callbacks

Page Loaded

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

$("#example-table").tabulator({
    pageLoaded:function(pageno){
        //pageno - the number of the loaded page
    }
});

Localization

Table Localized

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

$("#example-table").tabulator({
    localized:function(locale, lang){
        //locale - a string representing the current locale
        //lang - the language object for the current locale
    },
});

Group Callbacks

Data Grouping

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

$("#example-table").tabulator({
    dataGrouping:function(){

    },
});

Data Grouped

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

$("#example-table").tabulator({
    dataGrouped:function(groups){
        //groups - array of top level group components
    },
});

Group Visibility Changed

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

$("#example-table").tabulator({
    groupVisibilityChanged:function(group, visible){
        //group - group component
        //visible - is group visible (true = visible, false = hidden)
    },
});

Group Click

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

$("#example-table").tabulator({
        groupClick:function(e, group){
        //e - the click event object
        //group - group component
    },
});

Group Double Click

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

$("#example-table").tabulator({
        groupDblClick:function(e, group){
        //e - the click event object
        //group - group component
    },
});

Group Context Menu

The groupContext callback 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 callback.

$("#example-table").tabulator({
    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 callback is triggered when a user taps on a group header on a touch display.

$("#example-table").tabulator({
        groupTap:function(e, group){
        //e - the tap event object
        //group - group component
    },
});

Group Double Tap

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

$("#example-table").tabulator({
        groupDblTap:function(e, group){
        //e - the tap event object
        //group - group component
    },
});

Group Tap Hold

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

$("#example-table").tabulator({
        groupTapHold:function(e, group){
        //e - the tap event object
        //group - group component
    },
});

Selection Callbacks

Row Selected

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

$("#example-table").tabulator({
    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 programatically.

$("#example-table").tabulator({
    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 jQuery elements for each of the rows in order of selection as the second argument.

$("#example-table").tabulator({
    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 Callbacks New

Sending Start

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

$("#example-table").tabulator({
    movableRowsSendingStart:function(toTables){
        //toTables - array of receiving table elements
    }
});

Row Sent

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

$("#example-table").tabulator({
    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 jQuery element for the receiving table
    }
});

Row Sent Failed

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

$("#example-table").tabulator({
    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 jQuery element for the receiving table
    }
});

Sending Stop

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

$("#example-table").tabulator({
    movableRowsSendingStop:function(toTables){
        //toTables - array of receiving table elements
    }
});

Receiving Start

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

$("#example-table").tabulator({
    movableRowsReceivingStart:function(fromRow, fromTable){
        //fromRow - the row component from the sending table
        //fromTable - the jQuery element for the sending table
    }
});

Row Received

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

$("#example-table").tabulator({
    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 jQuery element for the sending table
    }
});

Row Received Failed

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

$("#example-table").tabulator({
    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 jQuery element for the sending table
    }
});

Receiving Stop

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

$("#example-table").tabulator({
    movableRowsReceivingStop:function(fromTable){
        //fromTable - the jQuery element for the sending table
    }
});

Validation Callbacks

Validation Failed

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

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

History Callbacks

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

The history callbacks 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 thier assoicated 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.

$("#example-table").tabulator({
    historyUndo:function(action, component, data){
        //action - the action that has been undone
        //component - the Component object afected by the action (colud be a row or cell component)
        //data - the data being changed
    },
});

Redo Occurred

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

$("#example-table").tabulator({
    historyRedo:function(action, component, data){
        //action - the action that has been redone
        //component - the Component object afected by the action (colud be a row or cell component)
        //data - the data being changed
    },
});

Clipboard Callbacks New

Data Copied to Clipboard

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

$("#example-table").tabulator({
    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 succesfully pasted into the table.

$("#example-table").tabulator({
    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 atempt to paste data into the table has failed because it was rejected by the paste parser.

$("#example-table").tabulator({
    clipboardPasteError:function(clipboard){
        //clipboard - the clipboard string that was rejected by the paste parser
    },
});

Download Callbacks New

Mutate Data Before Download

If you want to make any changes to the table data before it is parsed into the download file you can pass a mutator function to the downloadDataFormatter callback.

In the example below we map the numerical age column into a string of "adult" or "child" based on the age value

$("#example-table").tabulator({
    downloadDataFormatter:function(data){
        //data - active table data array

        data.forEach(function(row){
            row.age = row.age >= 18 ? "adult" : "child";
        });

        return data;
    }
});

Intercept & Manipulate Download Blob New

The downloadReady callback allows you to intercept the download file data before the users is prompted to save the file.

In order for the download to proceed the downloadReady callback is expected to return a blob of file to be downloaded.

If you would prefer to abort the download you can return false from this callback. This could be useful for example if you want to send the created file to a server via ajax ranther than allowing the user to download the file.

$("#example-table").tabulator({
    downloadReady:function(fileContents, blob){
        //fileContents - the unencoded contents of the file
        //blob - the blob object for the download

        //custom action to send blob to server could be included here

        return blob; //must return a blob to proceed with the download, return false to abort download
    }
});

Download Complete New

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

$("#example-table").tabulator({
    downloadComplete:function(){
    }
});

Key Bindings Updated

If you give a table focus by clicking on it, you can then interact with the table using the a number of different keyboard short cuts.

Action Default Key Combination (keycode) Function
navPrev ctrl + tab ("ctrl + 9") Shift focus to the next editable cell on the left, if none available move to the right most editable cell on the row above
navNext tab ("9") Shift focus to the next editable cell on the right, if none available move to left most editable cell on the row below
navLeft Shift focus to next editable cell on the left
navRight Shift focus to next editable cell on the right
navUp up arrow ("38") Shift focus to the same cell in the row above
navDown down arrow ("40") Shift focus to the same cell in the row below
undo ctrl + z ("ctrl + 90") Undo last user data edit
redo ctrl + y ("ctrl + 89") Redo last user data edit
scrollPageUp Page Up ("33") scroll page up by table height
scrollPageDown Page Down ("34") scroll page down by table height
scrollToStart Home ("36") scroll to first row
scrollToEnd End ("35") scroll to last row
copyToClipboard ctrl + c ("ctrl + 67") copy table data to clipboard

Customize Key Bindings

If you would prefer to use different key combinations then that is no problem, you can use the keybindings option to change any of the above bindings.

The keybindings option takes an object that should consist of properties with the name of the action you wish to bind and a value of the key code string.

The key code should consist of the keycodes for the keys to be pressed, seperated by the + symbol. The exceptions to this are ctrl and shift which should be used to check that the ctrl or shift keys are pressed as well.

The example below shows how to change the key bindings for the redo function to user the ctrl and r keys:

$("#example-table").tabulator({
    keybindings:{
        "redo" : "ctrl + 82", //bind redo function to ctrl + r
    },
});

Disable A Default Key Binding

To disable any of the default keybindings, pass a value of false to is property in the keybindings option:

$("#example-table").tabulator({
    keybindings:{
        "navUp" : false, //disable navUp keybinding
    },
});

Disable All Key Bindings

To disable all key bindings set the keybindings option to false

$("#example-table").tabulator({
    keybindings:false, //disable all key bindings
});

Clipboard New

The clipboard extension provides a range of functions that allow data to be copied out of the table into the clipboard and to be pasted into the table from the clipboard.

You can enable clipboard functionality using the clipboard config option. It can take one of four possible values:

  • true - enable clipboard copy and paste
  • "copy" - enable only copy functionality
  • "paste" - enable only paste funcitonality
  • false - disable all clipboard functionality (default)
$("#example-table").tabulator({
    clipboard:true, //enable clipboard functionality
});

Copying Table Data

If the table has focus, the copyToClipboard keybinding which is by default set to the ctrl + c key combination, will trigger a copy of table to the clipboard, which data is copied depends on the state of the table.

More information on how to configure this option can be found in the Keybindings Documentation

When copying data out of the table, the raw row data will be formatted to match the current order of the columns in the table. Row data in columns that are not currently visible will not be copied to the clipboard.

Column Header Titles

$("#example-table").tabulator({
    clipboardCopyHeader:false, //disable header titles in copied data
});

By default Tabulator will include the column header titles in any clipboard data, this can be turned off by passing a value of false to the clipboardCopyHeader property:

Copy Selector

The copy selector is a function that is used to choose which data is copied into the clipboard. Tabulator comes with a few different selectors built in:

  • active - Copy all table data currently displayed in the table to the clipboard (default)
  • table - Copy all table data to the clipboard, including data that is currently filtered out
  • selected - Copy the currently selected rows to the clipboard, including data that is currently filtered out

Tabulator will try to use the best selector to match your table setup. If any text is selected on the table, then it will be that text which is copied. If the table has selectable rows enabled, the it will be the currently selected rows copied to the clipboard in the order in which they were selected. Otherwise the currently visible data in the table will be copied.

These selectors can also be used when programatically triggering a copy event. in this case if the selector is not speicified it will default to the value set in the clipboardCopySelector property (which is active by default).

$("#example-table").tabulator({
    clipboardCopySelector:"table", //change default selector to active
});

You can also pass a custom selector function into the clipboardCopySelector property, it should take one argument of a boolean that if true means the column headers should be include in the data and return an array of row data objects:

$("#example-table").tabulator({
    clipboardCopySelector:function(showHeaders){
        return this.table.getData();
    }
});

Copy Formatter

The copy formatter is used to take the row data provided by the selector and turn it into a text string for the clipboard.

There is one built in copy formatter called table, if you have extended the clipboard extension and want to change the default you can use the clipboardCopyFormatter property. you can also pass in a formatting function directly into this property.

$("#example-table").tabulator({
    clipboardCopyFormatter:"cusstomFormatter", //use a custom built in formatter
});

You can also pass a custom formatter function into the clipboardCopyFormatter property, it should take one argument of the row data array from the copy selector function and should return a string that will be inserted into the clipboard:

$("#example-table").tabulator({
    clipboardCopyFormatter:function(rowData){
        return JSON.stringify(rowData);
    }
});

The in-built formatter will create table formatted text string that can be pasted into any standard speadsheet system like Excel or Google Sheets. Each column is separated by a tab and each row by a new line.

Clipboard Accessors

You can use the accessorClipboard and accessorClipboardParams options on a column definition to alter the value of data in a column before it is added to the clipboard.

The example below will transform all ages into a boolean, showing if they are over 18 or not. The accessorClipboardParams is used to pass the age limit to the accessor so the same accessor function can be used on multiple columns with different age limits:

var ageAccessor = function(value, data, type, params, column){
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", accessorClipboard:ageAccessor, accessorClipboardParams:{legalAge:18} }

Full details of how accessors work can be found in the Accessors Documentation.

Trigger Copy Programmatically

The copyToClipboard function allows you to copy the current table data to the clipboard. It the first argument lets use to choose which data is copied to the clipboard. it can be one of three options:

The first argument is the copy selector, you can choose from any of the built in options or pass a function in to the argument, that must return the selected row components.

If you leave this argument undefined, Tabulator will use the value of the clipboardCopySelector property, which has a default value of table

The second argument sets whether the column headers should be included in the copied data, true to include the headers (default) and false to hide them.

$("#example-table").tabulator("copyToClipboard", "selection", true); //copy the currently selected rows to the clipboard and include the column headers

Pasting Data Into the table

You can paset data into the table by making sure it has focus and pressing ctrl + p, there is no keybinding for this as the paste action is triggered by the paste event from the browse.

When data is pasted into the table, it is validated and converted into rows by the paste parser, then a paste action is triggered.

Paste Parser

Tabulator has one built in paste parser, that is designed to take a table formatted text string from the clipboard and turn it into row data. it breaks the tada into rows on a newline character \n and breaks the rows down to columns on a tab character \t.

It will then attempt to work out which columns in the data correspond to columns in the table. It tries three different ways to acheive this. First it checks the values of all columns in the first row of data to see if they match the titles of columns in the table. If any of the columns dont match it then tries the same approach but with the column fields. If either of those options match, Tabulator will map those columns to the incomming data and import it into rows. If there is no match then Tabulator will assume the columns in the data are in the same order as the visible columns in the table and import them that way.

The inbuilt parser will reject any clipboard data that does not contain at least one row and two columns, in that case the clipboardPasteError will be triggered.

If you extend the clipboard extension to add your own parser, you can set it to be used as default with the clipboardPasteParser property.

$("#example-table").tabulator({
    clipboardPasteParser:"customParser", //use a custom built in parser
});

You can also pass a custom parser function into the clipboardPasteParser property, it should take one argument of the string of clipboard data and return an array of row data objects that will be passed to the paste action. If the clipboard data isnt valid it should return false.

$("#example-table").tabulator({
    clipboardPasteParser:function(clipboard){

        //turn clipboard data into array

        return clipboardArray; //return array
    }
});

Paste Action

Once the data has been parsed into row data, it will be passed to a paste action to be added to the table. There are three inbuilt paste actions:

  • insert - Inserts data into the table using the addRows function (default)
  • update - Updates data in the table using the updateOrAddData function
  • replace - replaces all data in the table using the setData function

You can set which action should be performed using the clipboardPasteAction property.

$("#example-table").tabulator({
    clipboardPasteAction:"replace", //use replace action on paste
});

You can also pass a custom action function into the clipboardPasteAction property, it should take one argument of the row data from the paste parse function and trigger an action on the table and where possible return the row objects that are created

$("#example-table").tabulator({
    clipboardPasteAction:function(rowData){
        return this.table.updateData(rows);
    }
});

Clipboard Mutators

You can use the mutatorClipboard and mutatorClipboardParams options on a column definition to alter the value of data in a column as it is pasted into the table.

The example below will transform all ages into a boolean, showing if they are over 18 or not. The mutatorClipboardParams is used to pass the age limit to the accessor so the same accessor function can be used on multiple columns with different age limits:

var ageAccessor = function(value, data, type, params, column){
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", mutatorClipboard:ageAccessor, mutatorClipboardParams:{legalAge:18} }

Note: The mutateClipboard is called before the paste action is triggered, which may result in a different mutator being triggered after mutateClipboard.

Callbacks

A range of callbacks are avaialble for the clipboard. See the Clipboard Callbacks section for more information.

Download Table Data Updated

Tabulator allows you to download the table data as a file directly from your browser, no server needed.

The download will contain the text values of all data currently visible in the table, matching the current column layout, column titles, sorting and filtering.

You have a choice of four file types to choose from:

To trigger a download, call the download function, passing the file type (from the above list) as the first argument, and an optional second argument of the file name for the download (if this is left out it will be "Tabulator.ext"). The optional third argument is an object containing any setup options for the formatter, such as the delimeter choice for CSV's).

$("#example-table").tabulator("download", "csv", "data.csv"); //download table data as a CSV formatted file with a file name of data.csv

CSV Download

Custom CSV Delimiters

By default CSV files are created using a comma (,) delimiter. If you need to change this for any reason the you can pass the options object with a delimiter property to the download function which will then use this delimiter instead of the comma.

$("#example-table").tabulator("download", "csv", "data.csv", {delimiter:"."}); //download a CSV file that uses a fullstop (.) delimiter

XLSX Download Updated

The XLSX downloader requires that the SheetJS Library be inlcuded on your site, this can be included with the following script tag.
<script type="text/javascript" src="http://oss.sheetjs.com/js-xlsx/xlsx.full.min.js"></script>

Sheet Name New

You can set the name of the sheet in the xlsx download, using the sheetName property in the options object

$("#example-table").tabulator("download", "xlsx", "data.xlsx", {sheetName:"MyData"}); //download a Xlsx file that has a sheet name of "MyData"

Valid Characters
The sheet name must be a vaild Excel sheet name, and cannot include any of the following characters \, /, *, [, ], :, ?

Muti Table Download New

You can pull the data from multiple Tabulators into one xlsx file, using the sheets property of the options object.

This accepts an object, with the keys of each property being the sheet name, and the values being the tables to draw the data from, this can either be a string representing the query selector, or a JQuery wrapped DOM Element. If you pass a value of true it will use the current table. The order of the keys determines the order of the sheets

var sheets = {
    "Accounts Data": "#accounts-table", //first tab with table set using a query selector
    "Example Data": true, //second tab, generated from this table
    "Finance Data" : $("#finance-table"), //third tab with table set to JQuery element
};

$("#example-table").tabulator("download", "xlsx", "AllData.xlsx", {sheets:sheets}); //download a Xlsx file that has a tab for each table

PDF Download New

The PDF downloader requires that the jsPDF Library and jsPDF-AutoTable Plugin be inlcuded on your site, this can be included with the following script tags.
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/1.3.5/jspdf.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jspdf-autotable/2.3.2/jspdf.plugin.autotable.js"></script>

Setup Options

There are a number of options you can pass into the PDF downloader to configure the output

  • orientation - the orientation of the page, either portrait or landscape (default value of landscape)
  • title - optional page title
  • autoTable - an optional object that can be used to configure advanced styling on the table if needed, this can take ay of the standard AutoTable options
$("#example-table").tabulator("download", "pdf", "data.pdf", {
    orientation:"portrait", //set page orientation to portrait
    title:"Dynamics Quotation Report", //add title to report
    autoTable:{ //advanced table styling
        styles: {
            fillColor: [100, 255, 255]
        },
        columnStyles: {
            id: {fillColor: 255}
        },
        margin: {top: 60},
    },
);

Custom File Formatter

If you want to create a custom file type from the table data then you can pass a function to the type argument, instead of a string value. At the end of this function you must call the setFileContents function, passing the formatted data and the mime type.

//custom file formatter
var fileFormatter = function(columns, data, options, setFileContents){
    //columns - column definition array for table (with columns in current visible order);
    //data - currently displayed table data
    //options - the options object passed from the download function
    //setFileContents - function to call to pass the formatted data to the downloader

    //create a list of all name fields
    var names = [];

    data.forEach(function(row){
        names.push(row.name);
    })

    //trigger file download, passing the formatted data and mime type
    setFileContents(names.join(", "), "text/plain");
}

//trigger file download
$("#example-table").tabulator("download", fileFormatter, "test.txt");

Note: You can find out more about data URI's Here.

Hide Column In Download

If you dont want to show a particular column in the downloaded data you can set the download property in its column definition object to false:

$("#example-table").tabulator({
    columns:[
        {title:"Hidden Column", field:"secret", download:false} //hide data in download
    ]
});

Change Column Title in Download

You can add a custom column title to be used in the downloaded data instead of the usual title by setting the downloadTitle property in the column defintion object:

$("#example-table").tabulator({
    columns:[
        {title:"Name", field:"name", downloadTitle:"Full Name"} //change column title to "Full Name" in download
    ]
});

Download Accessors New

You can use the accessorDownload and accessorDownloadParams options on a column definition to alter the value of data in a column before it is added to the download.

The example below will transform all ages into a boolean, showing if they are over 18 or not. The accessorDownloadParams is used to pass the age limit to the accessor so the same accessor function can be used on multiple columns with different age limits:

var ageAccessor = function(value, data, type, params, column){
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", accessorDownload:ageAccessor, accessorDownloadParams:{legalAge:18} }

Full details of how accessors work can be found in the Accessors Documentation.

Format Data Before Download Updated

If you want to make any bulk changes to the table data before it is parsed into the download file you can pass a mutator function to the downloadDataFormatter option in the table definition.

In the example below we map the numerical age column into a string of "adult" or "child" based on the age value

$("#example-table").tabulator({
    downloadDataFormatter:function(data){
        //data - active table data array

        //change data

        //return data for download
        return data;
    }
});

This callback is called after the column accessors are applied.

Intercept & Manipulate Download Blob New

The downloadReady callback allows you to intercept the download file data before the users is prompted to save the file.

In order for the download to proceed the downloadReady callback is expected to return a blob of file to be downloaded.

If you would prefer to abort the download you can return false from this callback. This could be useful for example if you want to send the created file to a server via ajax ranther than allowing the user to download the file.

$("#example-table").tabulator({
    downloadReady:function(fileContents, blob){
        //fileContents - the unencoded contents of the file
        //blob - the blob object for the download

        //custom action to send blob to server could be included here

        return blob; //must return a blob to proceed with the download, return false to abort download
    }
});

Callbacks New

A range of callbacks are avaialble for downloads. See the Download Callbacks section for more information.

Localization

If you want to make your table accessible to users from a wide variety of languages then Tabulators localization features are for you.

Using the langs option you can specify the localized content for the table in any number of languages.

You can store as many languages as you like, creating an object inside the langs object with a property of the locale code for that language. A list of locale codes can be found here.

At present there are three parts of the table that can be localised, the column headers, the header filter placeholder text and the pagination buttons. To localize the pagination buttons, create a pagination property inside your language object and give it the properties outlined below.

If you wish you can also localize column titles by adding a columns property to your language object. You should store a property of the field name of the column you wish to change, with a value of its title. Any fields that match this will use this title instead of the one provided by the column definition array.

$("#example-table").tabulator({
    locale:true,
    langs:{
        "en-gb":{
            "columns":{
                "name":"Name", //replace the title of column name with the value "Name"
            },
            "ajax":{
                "loading":"Loading", //ajax loader text
                "error":"Error", //ajax error text
            },
            "groups":{ //copy for the auto generated item count in group header
                "item":"item", //the singluar for item
                "items":"items", //the plural for items
            },
            "pagination":{
                "first":"First", //text for the first page button
                "first_title":"First Page", //tooltip text for the first page button
                "last":"Last",
                "last_title":"Last Page",
                "prev":"Prev",
                "prev_title":"Prev Page",
                "next":"Next",
                "next_title":"Next Page",
            },
            "headerFilters":{
                "default":"filter column...", //default header filter placeholder text
                "columns":{
                    "name":"filter name...", //replace default header filter text for column name
                }
            }
        }
    },
});

Setting the Locale

You can set the current local in one of two ways. If you want to set it when the table is created, simply include the locale option in your Tabulator constructor. You can either pass in a string matching one of the language options you have defined, or pass in the boolean true which will cause Tabulator to auto-detect the browsers language settings from the navigator.language object.

$("#example-table").tabulator({
    locale:true, //auto detect the current language.
});

You can also set the language at any point after the table has loaded using the setLocale function, which takes the same range of values as the locale setup option mentioned above.

$("#example-table").tabulator("setLocale", "fr"); //set locale to french

Note: if Tabulator cant find a match, it will try and find the next best thing. For example if you were trying to set the locale to Belgian French "fr-be", if that option had not been defined, then Tabulator would go on to look for an"fr" option instead. if no matching locale is found then Then tabulator will default to using its built-in English language text.

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

$("#example-table").tabulator({
    localized:function(locale, lang){
        //locale - a string representing the current locale
        //lang - the language object for the current locale
    },
});

Getting the Current Locale

It is possible to retrieve the locale code currently being used by Tabulator using the getLocale function:

$("#example-table").tabulator("getLocale"); //return string for current locale code

Extending Localization

As well as the default columns and pagination properties required in the language object, you can also add any additional properties you like to the object to be used in localising other elements.

$("#example-table").tabulator({
    langs:{
        "en-gb":{
            "custom":{
                "site_name":"What A Great Table Based Site!!!",
            },
            "columns":{
                "name":"Name", //replace the title of column name with the value "Name";
            },
            "pagination":{
                "first":"First", //text for the first page button
                "first_title":"First Page", //tooltip text for the first page button
                "last":"Last",
                "last_title":"Last Page",
                "prev":"Prev",
                "prev_title":"Prev Page",
                "next":"Next",
                "next_title":"Next Page",
            },
        }
    },
});

You can then access these at any point using the getLang function, which will return the language object for the currently active locale.

$("#example-table").tabulator("getLang"); //return current lang object

Accessibility

Tabulator makes full use of aria accessibility tags to make the table machine readable by screen readers and other digital accessibility equipment.

The following role tags are used:

  • grid - Marks the element containing the tabulator as a grid
  • columngroup - Marks any column group title cells
  • columnheader - Marks each column header cell
  • row - Marks each row of the table
  • rowgroup - Marks any sections of grouped rows
  • rowheader - Marks the header of row group sections
  • gridcell - Marks each cell of the table
  • alert - Marks ant popup messages such as the ajax loader message
  • button - used to mark the pagination controls as buttons

In addition a number of other tags are used as needed throughout Tabulator:

  • aria-label - Used to hold cell value on graphically formatted cells. also used to give useful information on pagination controls
  • aria-sort - Shows current sort property of each column
  • aria-disabled - Shows the disabled state of pagination controls
  • aria-checked - Shows the checked state of cells that use a tick formatter
  • aria-valuemin - Shows the minimum possible value on the progressbar editor
  • aria-valuemax - Shows the maximum possible value on the progressbar editor
  • aria-valuenow - Shows the current value on the progressbar editor

Extensions Updated

Tabulator is built in a modular fashion with a core codebase providing basic table rendering functionality and a series of extensions that provide all of its wonderfull features.

All of the available extensions are installed by default to ensure that you can provide your users with the richest experience possible with minimal setup.

Creating a Custom Tabulator Build

If you want to run a minimal installation of Tabulator, using only the extensions needed for your project then you will need to rebuild a custom distribution using the steps below.

Tabulator's codebase is composed of a number of files located in the /src folder, and is built using the Gulp Task Runner. The gulpfile.js file that controls the build can be found in the root directory.

As gulp is an Node.js tool, you will first need to make sure you have Node.js installed.

Once installed you will then need to install the gulp plugin by opening a console window and typing the following command:

npm install gulp-cli -g

You will then need to setup the project by opening a console window in the root of the Tabulator directory and typing the following command:

npm install

You are now ready to make a custom build. The /src/extensions_enabled.js file lists all extensions that will be installed in the build (they are supposed to be in comments). To remove an extension from your build, simply delete its line in the file.

Once you are happy with the list of extensions that are going to be installed you need to trigger the build process. To do this open a console in the root of the Tabulator directory and run the following command:

gulp

Wait for the command to finish processing, then the /dist folder will contain your own custom build of Tabulator!

Extending Extensions

A lot of the extensions come with a range of default settings to make setting up your table easier, for example the sorters, formatters and editors that ship with Tabulator as standard.

If you are using a lot of custom settings over and over again (for example a custom sorter). you can end up re-delcaring it several time for different tables. To make your life easier Tabulator allows you to extend the default setup of each extension to make your custom options as easily accessible as the defaults.

Using the extendExtension function on the global Tabulator variable allows you to globally add these options to all tables.

The function takes three arguments, the name of the extension, the name of the property you want to extend, and an object containing the elements you want to add in your extension. In the example below we extend the format extension to add two new default formatters:

Tabulator.extendExtension("format", "formatters", {
    bold:function(cell, formatterParams){
        return "<strong>" + cell.getValue() + "</strong>"; //make the contents of the cell bold
    },
    uppercase:function(cell, formatterParams){
        return cell.getValue().toUpperCase(); //make the contents of the cell uppercase
    }
});

These formatters can then be access like any of the default formatters in the column definition object:

{title:"name", field:"name", formatter:"bold"},
{title:"Car Registration", field:"reg", formatter:"uppercase"},

The extendExtension function must be called on Tabulator after the tabulator.js file is included but before any tables are instantiated.

Note: if you use a property in your extension object that is already in use, the exising property will be overwritten.

Available Extensions Updated

This section will take you through all of the available extensions and how to extend them further with your own custom functionality.

As mentioned above, Tabulator comes with all extensions installed by default.

Accessors (included in tabulator.js by default)

The accessor extension allows for manipulation of data as it is retrieved from Tabulator.

More information on these functions can be found in the Accessors Documentation.

This can be extended to add custom accessor functions to the default list:

Tabulator.extendExtension("accessor", "accessors", {
    roundDown:function(value, data, accessorParams){
        return Math.floor(value); //return the new value for the cell data.
    }
});

You can use an accessor defined in the extension by passing the name to the accessor property in the column definition object.

$("#example-table").tabulator({
    columns:[
        {field:"tax", title:"Tax (£)", accessor:"roundDown"},
    ],
});

Ajax Requests (included in tabulator.js by default)

The ajax extension allows for loading data from remote sources using ajax requests.

More information on these functions can be found in the Ajax Documentation.

The default ajax configuration object can be extended to changed the default request behaviour. the example below will change the default request type to POST and the contentType header to application/JSON.

Tabulator.extendExtension("ajax", "defaultConfig", {
    type:"POST",
    contentType : "application/json; charset=utf-8"
});

Clipboard New(included in tabulator.js by default)

The clipboard extension allows data to be copied and pasted to and from the clipboard.

More information on these functions can be found in the Clipboard Documentation.

Column Calculation (included in tabulator.js by default)

The column calculation extension allows for automatic column calculation rows to be generated in the header and footer of the table.

More information on these functions can be found in the Column Calculations Documentation.

This can be extended to add custom calculation functions to the default list:

Tabulator.extendExtension("columnCalcs", "calculations", {
    "adult":function(values, data, calcParams){
        //values - array of column values
        //data - all table data
        //calcParams - params passed from the column defintion object

        var count = 0;

        values.forEach(function(value){
            if(value > 18){
                count ++;
            }
        });

        return calc;
    }
});

Comms New(included in tabulator.js by default. Mandatory extension - cannot be removed)

The comms extension handles inter-table communication.

The extension is used as part of Movable Rows and Downloads.

Download (included in tabulator.js by default)

The download extension allows for downloading data from the table into a file.

More information on these functions can be found in the Download Documentation.

This can be extended to add custom download functions to the default list:

Tabulator.extendExtension("download", "downloaders", {
    string:function(columns, data, options){
        var fileContents = data.toString();
        return 'data:application/txt;charset=utf-8,' + encodeURIComponent(fileContents);
    }
});

You can now use this in the download function:

$("#example-table").tabulator("download", "string", "data.txt");

Edit (included in tabulator.js by default)

The edit extension allows the user to change data in cells, header filters are also dependant on this extension.

More information on these functions can be found in the Editing Data Documentation.

This can be extended to add custom editor functions to the default list:

Tabulator.extendExtension("edit", "editors", {
    uppercaseInput:function(cell, onRendered, success, cancel, editorParams){

        //create and style input
        var input = $("<input type='text'/>");

        input.css({
            "padding":"4px",
            "width":"100%",
            "box-sizing":"border-box",
        })
        .val(cell.getValue().toUpperCase());

        onRendered(function(){
            input.focus();
        });

        //submit new value on blur
        input.on("change blur", function(e){
            success(input.val());
        });

        //submit new value on enter
        input.on("keydown", function(e){
            if(e.keyCode == 13){
                success(input.val());
            }
        });

        return input;
    },
});

You can use an editor defined in the extension by passing the name to the editor property in the column definition object.

$("#example-table").tabulator({
    columns:[
        {field:"tax", title:"Tax (£)", editor:"uppercaseInput"},
    ]
});

Filter Data (included in tabulator.js by default)

The filter extension allows for filtering of the rows that appear in the table..

More information on these functions can be found in the Filter Documentation.

This can be extended to add custom filter functions to the default list:

Tabulator.extendExtension("filter", "filters", {
    "===":function(filterVal, rowVal){
        return rowVal === filterVal ? true : false;
    }
});

You can now use this in any of the filter functions:

$("#example-table").tabulator("setFilter", "age", "===", 10);

Format Data (included in tabulator.js by default)

The format extension allows different display options for data in the table.

More information on these functions can be found in the Formatter Documentation.

This can be extended to add custom formatter functions to the default list:

Tabulator.extendExtension("format", "formatters", {
    file:function(cell, formatterParams){
        return "<img class='fileicon' src='/images/fileicons/" + cell.getValue() + ".png'></img>";
    },
});

You can use a formatter defined in the extension by passing the name to the formatter property in the column definition object.

$("#example-table").tabulator({
    columns:[
        {field:"Photo", title:"photo", formatter:"file"},
    ],
});

Frozen Columns (included in tabulator.js by default)

The frozen column extension allows columns to be held in place while the table is horizontally scrolled.

More information on these functions can be found in the Frozen Columns Documentation.

Frozen Rows (included in tabulator.js by default)

The frozen row extension allows rows to be held in place in the header while the table is vertically scrolled.

More information on these functions can be found in the Frozen Rows Documentation.

Group Rows (included in tabulator.js by default)

The group rows extension allows rows to be grouped togeather by a column value.

More information on these functions can be found in the Grouping Documentation.

History (included in tabulator.js by default)

The history extension allows the Tabulator to track user interaction with table data, and makes the undo and redo function available.

More information on these functions can be found in the History Documentation.

HTML Table Import (included in tabulator.js by default)

The allows HTML tables to be converted to Tabulators.

More information on these functions can be found in the HTML Import Documentation.

Key Bindings (included in tabulator.js by default)

The key bindings extension allows user interaction with the table through keyboard shortcuts.

More information on these functions can be found in the Key Bindings Documentation.

Any of the default keybindings options can be extended:

Tabulator.extendExtension("keybindings", "bindings", {
    navPrev:"shift + 9",
});

The default list of keybinding actions and their functions can be extended:

Tabulator.extendExtension("keybindings", "actions", {
    "deleteSelectedRows":function(){ //delete selected rows
        var rows = this.table.getSelectedRows();

        rows.forEach(function(row){
            row.delete();
        });
    },
});

Layout (included in tabulator.js by default. Mandatory extension - cannot be removed)

The layout extension handles column layout modes

More information on this functionaluty can be found in the Layout Documentation.

Localization (included in tabulator.js by default. Mandatory extension - cannot be removed)

The localization extension allows for changing the text of tabulator control elements to match the language on the computer viewing them.

More information on these functions can be found in the Localization Documentation.

This can be extended to add custom language definitions to the default list:

Tabulator.extendExtension("localize", "langs", {
    "en":{
        "columns":{
        },
        "ajax":{
            "loading":"Loading",
            "error":"Error",
        },
        "pagination":{
            "first":"First",
            "first_title":"First Page",
            "last":"Last",
            "last_title":"Last Page",
            "prev":"Prev",
            "prev_title":"Prev Page",
            "next":"Next",
            "next_title":"Next Page",
        },
        "headerFilters":{
            "default":"filter column...",
            "columns":{}
        }
    },
});

This will then be available to the locale auto-detect as well as the setLocale function.

$("#example-table").tabulator("setLocale", "en");

Movable Columns (included in tabulator.js by default)

The movable columns extension allows the user to drag and drop columns in any order they like.

More information on these functions can be found in the Movable Column Documentation.

Movable Rows Updated(included in tabulator.js by default)

The movable rows extension allows the user to drag and drop rows in any order they like.

More information on these functions can be found in the Movable Rows Documentation.

This extension can be extended to add custom receiver functions to the default list:

Tabulator.extendExtension("moveRow", "receivers", {
    nameUpdate:function(fromRow, toRow, fromTable){
        if(toRow){
            toRow.update({"name":fromRow.getData().name});
            return true;
        }
        return false;
    }
});

You can use a receiver defined in the extension by passing the name to the movableRowsReceiver option.

$('#example-table').tabulator({
    movableRowsReceiver: "nameUpdate",
})

This extension can also be extended to add custom sender functions to the default list:

Tabulator.extendExtension("moveRow", "senders", {
    incrementMoved:function(fromRow, toRow, fromTable){
        fromRow.update({moved:fromRow.getData().moved + 1})
    }
});

You can use a sender defined in the extension by passing the name to the movableRowsSender option.

$('#example-table').tabulator({
    movableRowsSender: "incrementMoved",
})

Mutators (included in tabulator.js by default)

The mutator extension allows for manipulation of data as it is entered into Tabulator.

More information on these functions can be found in the Mutators Documentation.

This can be extended to add custom mutator functions to the default list:

Tabulator.extendExtension("mutator", "mutators", {
    tooManyCars:function(value, data, type, mutatorParams){
        return value > 5;
    },
});

You can use a mutator defined in the extension by passing the name to the mutator property in the column definition object.

$("#example-table").tabulator({
    columns:[
        {field:"tax", title:"Tax (£)", mutator:"tooManyCars"},
    ],
});

Pagination (included in tabulator.js by default)

The pagination extension allows rows to be split up into pages for navigation rather than using a vertical scroll bar.

More information on these functions can be found in the Pagination Documentation.

Any of the default paginationDataSent options can be extended:

Tabulator.extendExtension("page", "paginationDataSentNames", {
    "page":"pageNo",
});

Any of the default paginationDataReceived options can also be extended:

Tabulator.extendExtension("page", "paginationDataReceivedNames", {
    "last_page":"max_page",
});

Persistent Config (included in tabulator.js by default)

The persistence extension allows the layout of columns and the current sorters and filters to be stored in local storage or cookies so that a users preferences can be remembered every time they reload the page.

More information on these functions can be found in the Persistent Config Documentation.

Resizable Columns (included in tabulator.js by default)

The resizable columns extension allows the user to resize columns by dragging on the edge of the columns.

More information on these functions can be found in the Resizable Columns Documentation.

Resizable Rows (included in tabulator.js by default)

The resizable rows extension allows the user to resize rows by dragging on the top or bottom edges of a row.

More information on these functions can be found in the Resizable Rows Documentation.

Resizable Table (included in tabulator.js by default)

The table resize extension allows the table to automatically redraw its contents to fit its container when the table container is resized.

More information on these functions can be found in the Table Resize Documentation.

Responsive Layout (included in tabulator.js by default)

The responsive layout extension hides and shows columns to ensure that they do not excede the width of the table. Great for use on mobile devices.

More information on these functions can be found in the Responsive Layout Documentation.

Selectable Rows (included in tabulator.js by default)

The selectable rows extension allows the user to select a number of rows to take action on them.

More information on these functions can be found in the Selectable Rows Documentation.

Sorting Data (included in tabulator.js by default)

The sorting extension allows for reordering of rows in the table based on a column value.

More information on these functions can be found in the Sorting Documentation.

This can be extended to add custom sorter functions to the default list:

Tabulator.extendExtension("sort", "sorters", {
    datetime:function(a, b){
       a = moment(a, "DD/MM/YYYY hh:mm");
       b = moment(b, "DD/MM/YYYY hh:mm");
       return a - b;
    },
});

You can use a sorter defined in the extension by passing the name to the sorter property in the column definition object.

$("#example-table").tabulator({
    columns:[
        {field:"start", title:"Start Time", sorter:"datetime"},
    ],
});

Validate Data (included in tabulator.js by default)

The validate extension allows for validation of editied data before it is stored in the table.

More information on these functions can be found in the Validation Documentation.

This can be extended to add custom validator functions to the default list:

Tabulator.extendExtension("validate", "validators", {
    divTen:function(cell, value, parameters){
       //cell - the cell component for the edited cell
       //value - the new input value of the cell
       //parameters - the parameters passed in with the validator

       return !value % 10; //only allow values that are divisible by 10;
    },
});

Default Options

If you always pass the same setup options to your Tabulator constructor object, you can also make these default by Aextending the jQuery widget, these will then automatically apply to any new Tabulator's unless the value is overwritten in construction object when you create a specific Tabulator.

This code must be inserted after the tabulator.js file is included but before any tables are instantiated.

For example the below code will cause all Tabulators to have resizable columns by default.

$.widget("ui.tabulator", $.ui.tabulator, {
    options: {
        resizableColumns:true,
    },
});

Deprecated Functionality Updated

The following functionality has been depricated and will be removed in version 4.0

Download Data Mutator New

Deprecated Function

Setting the data download mutation function using the downloadDataMutator option:

$("#example-table").tabulator({
    downloadDataMutator:function(){},
});

Replacement Function

This has been replaced with the downloadDataFormatter option:

$("#example-table").tabulator({
    downloadDataFormatter:function(){},
});

Mutation Type New

Deprecated Function

Binding the mutator callback to a given type of mutation using the mutateType option:

{title:"age", field:"age", mutator:ageMutator, mutatorParams:{limit:18}, mutateType:"edit"}

Replacement Function

You should now use the mutator option matching the type of event you want to bind to:

$("#example-table").tabulator({
    {title:"age", field:"age", mutatorEdit:ageMutator, mutatorEditParams:{limit:18}}
});

Persistence ID

Deprecated Function

Setting the persistent storage ID using the persistentLayoutID option:

$("#example-table").tabulator({
    persistentLayoutID:"table1",
});

Replacement Function

This has been replaced with the persistenceID option:

$("#example-table").tabulator({
    persistenceID:"table1",
});

Persistence Mode

Deprecated Function

Enabling column layout persistence and setting the persistent storage mode using the persistentLayout option:

$("#example-table").tabulator({
    persistentLayout:"cookie", //enable persistent column layout and set id
});

Replacement Function

You should now set the storage mode using the persistenceMode option and enable persistent column layouts with the persistentLayout option:

$("#example-table").tabulator({
    persistenceMode:"cookie", //set persistent storage mode
    persistentLayout:true, //enable persistent column layout
});

Email Formatter

Deprecated Function

Creating a mailto link using the email formatter:

{title:"Email", field:"email", formatter:"email"}

Replacement Function

This has been replaced with the link formatter with the new formatterParams of urlPrefix set to mailto::

{title:"Email", field:"email", formatter:"link", formatterParams:{urlPrefix:"mailto:"}}

fitColumns Setup Option

Deprecated Function

Setting the layout mode to fitColumns using the fitColumns option:

$("#example-table").tabulator({
    fitColumns:true, //enable fit columns layout mode
});

Replacement Function

This has been replaced with the layout option which allows the mode to be set to a number of different options including fitColumns:

$("#example-table").tabulator({
    layout:"fitColumns", //enable fitColumns layout mode
});

Get Filters

Deprecated Function

Getting the current filters using the getFilter function:

var filters = $("#example-table").tabulator("getFilter");

Replacement Function

This has been replaced with the getFilters function:

var filters = $("#example-table").tabulator("getFilters");

Get Sorters

Deprecated Function

Getting the current sorters using the getSort function:

var sorters = $("#example-table").tabulator("getSort");

Replacement Function

This has been replaced with the getSorters function:

var sorters = $("#example-table").tabulator("getSorters");

Header Tooltip

Deprecated Function

Setting a columns header tooltip using the tooltipHeader property in its column definition array:

{title:"name", field:"name", width:40, align:"center", tooltipHeader:true},

Replacement Function

This has been replaced with the headerTooltip property:

{title:"name", field:"name", width:40, align:"center", headerTooltip:true},

Ajax Sort Parameters

Ajax sorting now sends all current sorts instead of just the first, for more information checkout the Ajax Sorting Documentation

Deprecated Function

Setting the sort and sort_dir properties in the paginationDataSent option:

$("#example-table").tabulator({
    paginationDataSent:{
        "sort":"sort",
        "sort_dir":"sort_dir",
    }
});

Replacement Function

Sort data is now passed as an array to the sorters pproperty of the paginationDataSent option:

$("#example-table").tabulator({
    paginationDataSent:{
        "sorters":"sorters",
    }
});

Ajax Filter Parameters

Ajax sorting now sends all current filters instead of just the first, for more information checkout the Ajax Filtering Documentation

Deprecated Function

Setting the filter, filter_value and filter_type properties in the paginationDataSent option:

$("#example-table").tabulator({
    paginationDataSent:{
        "filter":"filter",
        "filter_value":"filter_value",
        "filter_type":"filter_type",
    }
});

Replacement Function

Filter data is now passed as an array to the filters pproperty of the paginationDataSent option:

$("#example-table").tabulator({
    paginationDataSent:{
        "filters":"filters",
    }
});