Setup Updated

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="tabulator.css" rel="stylesheet">
<script type="text/javascript" src="tabulator.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

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

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/2.12.0/tabulator.min.css" rel="stylesheet">
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/tabulator/2.12.0/tabulator.min.js"></script>

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

jQuery Dependences New

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
  • :data Selector
  • scrollParent
Movable Rows/Columns
  • Draggable
  • Droppable
  • Selectable
  • Sortable
  • Mouse

An opmimized jQuery UI library can be downloaded here.

Define Column Headers 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", sortable:true, sorter:"string", width:200, editable:true},
        {title:"Age", field:"age", sortable:true, sorter:"number", align:"right", formatter:"progress"},
        {title:"Gender", field:"gender", sortable:true, sorter:"string", onClick:function(e, val, cell, row){console.log("cell click")},},
        {title:"Height", field:"height", sortable:true, formatter:"star", align:"center", width:100},
        {title:"Favourite Color", field:"col", sorter:"string", sortable:false},
        {title:"Date Of Birth", field:"dob", sortable:true, sorter:"date", align:"center"},
        {title:"Cheese Preference", field:"cheese", sortable:true, sorter:"boolean", align:"center", formatter:"tickCross"},
    ],
});

There are a number of parameters that can be passed in with each column to determine how it is displayed:

  • 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
  • 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 colMinWidth)
  • 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)
  • sortable - determines if the user can sort data by this column (see Sorting Data for more details)
  • sorter - determines how to sort data in this column (see Sorting Data for more details)
  • formatter - set how you would like the data to be formatted (see Formatting Data for more details)
  • onClick - callback for when user clicks on a cell in this column (see Callbacks for more details)
  • onDblClick - callback for when user double clicks on a cell in this column (see Callbacks for more details)
  • onContext - callback for when user right clicks on a cell in this column (see Callbacks for more details)
  • headerOnClick New - callback for when user clicks on the header for this column (see Callbacks for more details)
  • headerOnDblClick New - callback for when user double clicks on the header for this column (see Callbacks for more details)
  • headerOnContext New - callback for when user right clicks on the header for this column (see Callbacks for more details)
  • editable - (boolean, default - false) determines if this data is editable by the user. will use the editor that matches the formatter by default. (see Manipulating Data for more details)
  • editor - set the editor to be used when editing the data. (see Manipulating Data for more details)
  • visible - (boolean, default - true) determines if the column is visible. (see Column Visibility for more details)
  • cssClass - sets css classes on header and cells in this column. (value should be a string containing space seperated class names)
  • tooltip - sets the on hover tooltip for each cell in this column (see Formatting Data for more details)
  • tooltipHeader - 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)
  • headerFilter - filtering of columns from elements in the header (see Header Filtering for more details)
  • mutator - function for manipulating column values as they are parsed into the table (see Mutators for more details)
  • mutateType - defines whether mutation should occur on data parsing, cell editing or both (see Mutators for more details)
  • accessor - function to alter column values before they are read out the table using the getData function (see Accessors for more details)

Column Grouping Updated

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 colVertAlign 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({
    colVertAlign:"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 New

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

  • headerOnClick - callback for when user clicks on the header for this column group (see Callbacks for more details)
  • headerOnDblClick - callback for when user double clicks on the header for this column group (see Callbacks for more details)
  • headerOnContext - 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 Updated

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 must be present for each row of data, which must 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.
});

If the index is missing from the provided data, tabulator will generate one from the position of the data in the original array.

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 data using AJAX Updated

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 New

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 paramter.

$("#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 Updated

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

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

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

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

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-fitcolumns="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({
    fitColumns:true, //example option (sets column widths to fill table)
    columns:[ //set column definitions for imported table data
        {title:"Name", sortable:true, editable:true},
        {title:"Age", sortable:true, sorter:"number"},
        {title:"Gender", sortable:true},
        {title:"Height", sortable:true, sorter:"number"},
        {title:"Favourite Color", sortable:true},
        {title:"Date of Birth", sortable:true, sorter:"date"},
    ],
});

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

Pagination

Tabulator allows for pagination of table data, displaying only a section of data at a time, allowing for smaller tables without scroll bars.

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 aditional configuration needed.

Note: Changing the filter or sorting 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 paramter. You can also pass an optional object to ajaxParams for any paramters 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 paramter.

$("#example-table").tabulator({
    pagination:"remote", //enable remote pagination
    ajaxURL:"http://testdata.com/data", //set url for ajax request
    ajaxParams:{token:"ABC123"}, //set any standard paramters to pass with the request
    paginationSize:5, //optional paramter 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 currently sorted field (if data is sorted by user)
  • sort_dir - the current sort direction (if data is sorted by user)
  • filter - the currently filtered field (if data is filtered by user)
  • filter_value - the current filter value (if data is filtered by user)
  • filter_type - the current filter type (if data is filtered by user)

If you need to change the names of any of these paramters 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"
    } ,
});

If you need to have more complex control over the request URL, you can pass a callback to the paginator paramter 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 paramter
        //pageNo - the requested page number
        //pageSize - the value of the paginationSize paramter
        //ajaxParams - the value of the ajaxParams parameter

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

Returned Data

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

{
    "last_page":15, //the total number of available pages
    "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 paramters 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"
    } ,
});

Remote Pagination with Progressive Rendering

An alternative to using the page control buttons would be to use progressive rendering, where as the user scrolls through the table new pages of data are automatically requested from the server and added to the bottom of the table.

For more details on how to do this, have a look at the documentation for Progressive Rendering with Ajax Pagination

Local Pagination

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

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

Additional Features

A number of aditional features 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

pageLoaded Callback

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

$("#example-table").tabulator({
    pagination:"local",
    pageLoaded:function(pageno){
        alert("Number of loaded page:" + pageno);
    }
});

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

Table Layout

Tabulator will arrange your data to fit as neatly as possible into the space provided. It has two different layout styles:

  • Fit columns to data (default)
  • Fit columns to container

Fit Columns to Data

This is the default table layout style and will cause columns to resize to fit the widest element they contain (unless a column width was set in the column options). If the width of all columns exceeds the width of the containing element, a scroll bar will appear.

Fit Columns to Container

This option will resize columns so that they fit perfectly inside the width of the container.

If a width is specified on any columns, where possible the columns will be set at this width and other columns will be resized around them. If there is not enough space to fit all the columns in, then all column widths are ignored and they are sized equally.

In this layout style at least one column must not have a width specified so it can be resized to fill any spare space.

to enable this layout mode set the fitColumns option to true when you create your Tabulator.

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

Responsive Layout

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.

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

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: At present responsive layout will only function once a data has been set on a table.

Resizable Columns

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

To disable this option globally set the colResizable option to false when you create your Tabulator.

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

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 colMinWidth 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({
    colMinWidth: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 .tabulator-header .tabulator-col-row-handle {
    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 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.

Redrawing the table

If the size of the element containing the Tabulator changes it is necessary to redraw the table to make sure the columns fit the new dimensions.

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

Progressive Rendering

Progressive rendering allow large data sets to be loaded into Tabulator without blocking the UI.

It works by rendering blocks of rows progressively as you scroll down the table rather than all at once. On smaller tables this wont be noticeable at all but on tables with more than 200 rows it should significantly improve loading times.

If you wish to enable progressive rendering on your table, set the progressiveRender option to true.

$("#example-table").tabulator({
    progressiveRender:true, //enable progressive rendering
});

By default data is progressively rendered to the table 20 rows at a time when the vertical scroll bar scroll position is less than 200px from the bottom of the table.

It is possible to configure the progressive rendering system using the progressiveRenderSize and progressiveRenderMargin options.

$("#example-table").tabulator({
    progressiveRenderSize:500, //sets the number of rows to render per block (default = 20)
    progressiveRenderMargin:350, //distance in px before end of scroll before progressive render is triggered (default = 200)
});

Note: You must have the height option set for your table for progressive rendering to work. If your table does not have a height set then all the rows will be rendered in one go.

Progressive Rendering with Ajax Pagination

If you are loading from a remote data source then in is possible to combine progressive rendering with ajax pagination to make successive calls to the server to fill the table as you scroll rather than trying to load the data all in one go.

To do this you need to set the progressiveRender option to a value of "remote" and set the ajaxURL option to the url of the remote data source.

$("#example-table").tabulator({
    progressiveRender:"remote", //enable progressive rendering
    ajaxURL:"/data/page", //set the ajax URL
});

For a full overview of the remote pagination paramaters have a look at the Remote Pagination Documentation

Note: To ensure the best user experience it is recomended that the number of rows returned by the server for each page at least fills the hight of the table, while the system can handle smaller sizes it will result in a lot of ajax calls in very quick succession.

Sorting Data Updated

Sorting of data by column is enabled by default on all columns. It is possible to turn sorting on or off globally using the sortable option when you create your Tabulator.

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

you can set sorting on a per column basis using the sortable option in the column data.

{title:"Name", field:"name", sortable:true, sorter:"string"}

Sorter type

By default all data is sorted as a string. if you wish to specify a different sorting method then you should include the sorter option in the column data.

Tabulator comes with a number of preconfigured sorters including:

  • string - sorts column as strings of characters
  • number - sorts column as numbers (integer or float, will also handle numbers using "," seperators)
  • alphanum - sorts column as alpha numeric code
  • boolean - sorts column as booleans
  • date - sorts column as dates (for this you will need to set the date format using the dateFormat option when you create your table. default format is "dd/mm/yyyy")
  • time - sorts column as time (formatted as hh:mm)

Custom Sorters Updated

You can define a custom sorter function in the sorter option:

{title:"Name", field:"name", sortable:true, sorter:function(a, b, aData, bData, field, dir){
        //a, b - the two values being compared
        //aData, bData - the row objects for the values being compared (useful if you need to access additional fields in the row data for the sort)
        //field - the name of the column being sorted
        //dir - the direction of the sort ("asc" or "desc")

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

Sort Data on Load

When data is loaded into the table it can be automatically sorted by a specified field, this field can be set in the options using the sortBy and sortDir parameters. (see Initial Data Sorting for more details)

$("#example-table").tabulator({
    sortBy:'name', // when data is loaded into the table, sort it by name
    sortDir:'asc', //when data is loaded into the table, sort it in ascending order.
});

Trigger Sorting Programmatically

You can trigger sorting using the sort function

$("#example-table").tabulator("sort", "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("sort", [
    {field:"age", dir:"asc"}, //sort by this first
    {field:"height", dir:"desc"}, //then sort by this second
]);

Get Currently Sorted Column

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

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

This will return an object with two properties, 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.

{
    field:"name",
    dir:"asc",
}

If a the table is not currently sorted then the value of both of these properties will be false.

Formatting Data

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 data.

You can pass an optional additional parameter with 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)
  • money - formats a number into currency notation (eg. 1234567.8901 -> 1,234,567.89)
  • email - renders data as an anchor with a mailto: link to the given value
  • link - renders data as an anchor with a link to the given value
  • 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 - 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)
  • 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.

Custom Formatters

You can define a custom formatter function in the formatter option:

{title:"Name", field:"name", formatter:function(value, data, cell, row, options, formatterParams){
        //value - the value of the cell
        //data - the data for the row the cell is in
        //cell - the DOM element of the cell
        //row - the DOM element of the row
        //options - the options set for this tabulator
        //formatterParams - parameters set for the column
        return "<div></div>"; // must return the html or jquery element of the html for 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)

Icon/Button Columns

You can create icon/button columns, by not specifying the field parameter in the column data 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(value, data, cell, row, options){ //plain text value
    return "<i class='fa fa-print'></i>"
};

//column definition in the columns array
{formatter:printIcon, width:40, align:"center", onClick:function(e, cell, val, row){alert("Printing row data for: " + row.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 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, data){
        //row - JQuery object for row
        //data - the data for the row

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

ToolTips

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:
$("#example-table").tabulator({
    tooltips:function(field, value, data){
        //field - field name of the cell's column
        //value - value of the cell
        //data - data for the cell's row

        //function should return a string for the tooltip of false to hide the tooltip
        return  field + " - " + value; //return cells "field - value";
    },
});

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

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", tooltipHeader:true},

The tooltip tooltipHeader 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:
$("#example-table").tabulator({
    tooltips:function(col){
        //col - column definition object

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

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

Grouping Data

With Tabulator you can group rows together using the groupBy option.

To group by a field, set this option to the name of the field to be grouped.

groupBy:"gender",

To group by more complex operations you should 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){
    //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

    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){
    //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

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

Filtering Data

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.

$("#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)

By default tabulator will assume you want to use the "=" comparison unless otherwise stated. This allows for the short hand use of the function:

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

You can only have one filter active at a time, calling setFilter a second time will over write the previous filter.

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

Custom Filter Functions

If you want to perform a more complicated filter then you can pass a callback function to the setFilter Method

function customFilter(data){
    //data - the data for the row being filtered
    return data.name == "bob" && data.height < 3; //must return a boolean, true if it passes the filter.
}

$("#example-table").tabulator("setFilter", customFilter);

Get Current Filter

To find out what filter is currently applied to the table you should use the getFilter method.

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

If there is no filter set, this will return false, otherwise it will return an object with the filter information.

{
    "field":"age",
    "type":">",
    "value":10,
}

Clearing Filters

To remove filters from the table you should use the clearFilter method.

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

alternatively you can also call the setFilter method with no parameters to clear the filter.

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

Header Filtering Updated

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.

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

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.

Filter Comparison Types

The type of comparison function used on the filter value is dependent on the type of element used for the header filter.

Standard input elements use a case insensitive comparison where even a partial match counts as successful, 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 exact match is needed for the comparison to be successful.

Placeholder Text Updated

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 headerFilterColumnPlaceholders option.

Pass an object containing key value pairs for each column you want to set the placholder text for. If a column is not in this object it will use the default text specified in the headerFilterPlaceholder option.

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

Editing & Manipulating Data Updated

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 editable parameter in the column definition. (see Define Column Headers 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.

{title:"Rating", field:"rating", editor:"star"}

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.
  • 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)

You can define a custom editor function in the editor option:

{title:"Gender", field:"gender", editor:function(cell, value, data){
        //cell - JQuery object for current cell
        //value - the current value for current cell
        //data - the data for the current row

        //create and style editor
        var editor = $("<select><option value=''></option><option value='male'>male</option><option value='female'>female</option></select>");
        editor.css({
            "padding":"3px",
            "width":"100%",
            "box-sizing":"border-box",
        })

        //Set value of editor to the current value of the cell
        editor.val(value);

        //set focus on the select box when the editor is selected (timeout allows for editor to be added to DOM)
        if(cell.hasClass("tabulator-cell")){ //check to make sure this editor isnt being used as a header filter
            setTimeout(function(){
                editor.focus();
            },100);
        }

        //when the value has been set, trigger the cell to update
        editor.on("change blur", function(e){
            cell.trigger("editval", editor.val());
        });

        //return the editor element
        return editor;
    },
}

Returning a value of false from this function will abort the edit and prevent the cell from being selected.

Data Mutation

Note: 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)

Updating 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}

Update or Add Data New

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

Note: 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 Updated

Retreive All Data

You can retreive 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

Retreive Row Data New

The getRowData function will return the row data object for a single row. The first argument will take either the index of the row data or the jQuery object representing the row element.

var rowData = $("#example-table").tabulator("getRowData", 1); //return data for row with index of 1

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 either of the above functions. (see Accessors for more details)

Emptying the Table

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

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

Row Manipulation Updated

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

Add Row Updated

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). You can either pass the index of the existing row or its jQuery object to this argument:

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

Note: 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 of this function should be the index of the row you want to update (the index field being defined by the index option in the tabulator constructor, which defaults to "id"), alternativly you could pass a jQuery object of the row itself.

The second function should be the updated data object for the row. as per 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.

Note: 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 New

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.

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

Get Row Element New

You can use the getRow function to return the jQuery object for a specific row element. Pass the index of the rows data object into the first argument.

var rowElement = $("#example-table").tabulator("getRow", 4);

If a row with a matching index is not found, the function will return false.

Delete Row

You can delete any row in the table using the deleteRow function;

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

You can either pass the function the id of the row you wish to delete or the data object that represents that row.

Mutators & Accessors

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

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 data.

{title:"Has Too Many Cars", field:"cars", mutator:function(value, type, data){
        //value - original value of the cell
        //type - the type of mutation occuring (data|edit)
        //data - the data for the row

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

Mutation Type

By default mutators are applied to data when it is parsed into the table with the setData function and when a user edits a cell. If you only want your mutators to be applied in one of these cases, you can use the mutateType option to specify when you want your mutator to be used.

{title:"Has Too Many Cars", field:"cars", mutateType:"data",  mutator:tooManyCarsMutator} //mutate only parsed data not cell edits.

mutateType can have one of three values:

  • data - Only mutate data when using the setData function.
  • edit - Only mutate data when a user edits a cell.
  • all - Mutate data on setData and cell edit.

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

Accessors are used to alter data as it leaves the table through the getData function. For example if you wanted to make sure that any float values in a column were rounded down to integers before you retrieved the data, you could use an accessor.

{title:"Tax Owed (£)", field:"tax", accessor:function(value, data){
        //value - original value of the cell
        //data - the data for the row

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

Accessors will only be applied to the data returned by the getData function and will not affect the data used by the table itself.

Selectable Rows Updated

You can make your tables rows selectable using the selectable option. This will allow 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.

$("#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 selectablePersistance option to false.

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

Selection Changed Event

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){
        //data - array of data objects for the selected rows in order of selection
        //rows - array of jQuery elements for the selected rows in order of selection
    },
});

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 id for the row, the data object for the row, or the jQuery element of that row 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

Deselect Row

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

To deselect a specific row you can pass the id for the row, the data object for the row, or the jQuery element of that row 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

Enable/Disable Selection Per Row

The selectableCheck option can be set with a function to check if a row should be selectable or not. It should return true for selectable or false for unselectable.

$("#example-table").tabulator({
    selectable:true,
    selectableCheck:function(data, row){
        //data - data object for this row
        //row - jQuery element for this row

        return data.age > 50; //only allow rows with an age greater than 50 to be selected.
    },
});

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

Get Selected Data

To get the data objects for the selected rows at any time 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.

Scroll To Row New

If you want to trigger an animated scroll to a row then you can use the scrollToRow function:

$("#example-table").tabulator("scrollToRow", 23);

You can either pass the function the id of the row you wish to scroll to or the jQuery object that represents that row.

Movable Rows and Columns

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, by default this is set to false
})

This will allow users to drag rows around using the handle on the left hand side of each row.

If you would like to use a custom handle for a row then set the movableRowHandle parameter with the HTML for the handle graphic.

$('#example-table'),tabulator({
    movableRows: true, //enable user movable rows, by default this is set to false
    movableRowHandle: "<div style='height:10px; width:10px; background:#f00;'></div>", //custom handle html
})

Note: When grouping is enabled, rows can only be moved within their own group.

Row Moved Event

When a row has been successfully moved, the rowMoved callback will be triggered.

$("#example-table").tabulator({
    rowMoved:function(id, data, row, index){
        //id - the id of the row
        //data - the data for the row
        //row - the DOM element of the row
        //index - new position of row in table
    }
});

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 Columns

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

$('#example-table'),tabulator({
    movableCols: true, //enable user movable rows, by default this is set to false
})

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

Note: icon/button columns and row handle columns are not movable.

Column Moved Event

When a column has been successfully moved, the colMoved callback will be triggered.

$("#example-table").tabulator({
    colMoved:function(field, columns){
        //field- the filed name of the moved column
        //columns- the updated columns config array
    }
});

Set New Column Definitions

To update the current column definitions for a table use the setColumns function. this function takes two parameters. the first should be the new columns definition array. The second is a boolean value that determines the type of column update you wish to use. If you set this to false, the current column definition array will be completely overwritten. Set it to true and only the column layout information (width, order, visibility) will be overwritten, perfect for loading user layout preferences from an external store.

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

$("#example-table").tabulator("setColumns", newColumns , false) //completely 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 either the field value of the column you wish to insert next to, or its index in the column definition array (starting from zero).

Delete Column

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

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

You can pass either the field value of the column you wish to delete, or its index in the column definition array (starting from zero).

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 getColumns function. this will return the current columns definition array.

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

Persistent Column Layout

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

To enable column layout persistence, use the persistentLayout parameter. This can take one of 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

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

If you are planning on having multiple tables on the same page using column 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 Tabulator, Tabulator will automatically use this id as a reference for the storage 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 persistentLayoutID to a unique storage id for that table.

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

Note: If you update the column definition array after the the layout has been stored you may have to change the storage id to clear out the old column layout information.

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 Function

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

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

Hide Column Function

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

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

Toggle Column Function

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

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

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

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.
tooltipsboolean/functionfalseFunction to generate tooltips for cells
dateFormatstringdd/mm/yyyyThe date format that should be used when sorting date fields

Columns Updated

Option Data Type Default Value Description
columnsarray[]Holder for column definition array
fitColumnsbooleanfalseResize column widths to horizontally fill the table
responsiveLayoutbooleanfalseAutomatically hide/show columns to fit the width of the Tabulator element
colMinWidthCSS width value40pxMinimum width for a column
colResizablebooleantrueAllow user to resize columns (via handles on the left and right edges of the column header)
movableColsbooleanfalseAllow users to move and reorder columns
tooltipsHeaderboolean/functionfalseFunction to generate tooltips for column headers
colVertAlignstringtopVertical 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
headerFilterColumnPlaceholdersobject{}The placeholder text to be set per column in their header filter input element

Rows

Option Data Type Default Value Description
rowFormatterfunction/booleanfalseFunction to alter layout of rows
groupBystring/functionfalseString/function to select field to group rows by
groupHeaderfunction(see documentation)function to layout group header row
groupStartOpenboolean/functiontrueBoolean/function to set the open/closed state of groups when they are first created
addRowPosstring"bottom"The position in the table for new rows to be added, "bottom" or "top"
selectableboolean/integer/string"highlight"Enable/Disable row selection
selectableCheckfunction(see documentation)Check if row should be selectable or unselectable
movableRowsbooleanfalseAllow users to move and reorder rows
movableRowHandlestringhtml (see below)html for the movable row handle

Default movable row handle

<div style='margin:0 10%; width:80%; height:3px; background:#666; margin-top:3px;'></div><div style='margin:0 10%; width:80%; height:3px; background:#666; margin-top:2px;'></div><div style='margin:0 10%; width:80%; height:3px; background:#666; margin-top:2px;'></div>

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
showLoaderbooleantrueShow loader while data is loading
loaderstringhtml (see below)html for loader element
loaderErrorstringhtml (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>

Global Data Sorting

You can set the table sorting options on a global level, specifying what sort should be applied when data is first loaded into the table.

Option Data Type Default Value Description
sortablebooleantrueenable sorting in all columns
sortBystring"id"The name of the field to be sorted.
sortDirstring"desc"The direction of the sort (asc or desc).

Pagination

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",
"sort":"sort",
"sort_dir":"sort_dir",
"filter":"filter",
"filter_value":"filter_value",
"filter_type":"fitler_type",
}
Lookup list to link fields expected by the server to their function
paginatorfunctionnullFunction used to build pagination request URL string

Persistent Layout

Option Data Type Default Value Description
persistentLayoutboolean/stringfalseEnable persistsnt storage of column layout information in a cookie or localStorage
persistentLayoutIDstringID tag used to identify persistent storage information

Progressive Render Updated

Option Data Type Default Value Description
progressiveRenderbooleanfalseEnable progressive rendering
progressiveRenderSizeinteger20Set the number of rows to be rendered in each block
progressiveRenderMargininteger200The distance in pixels from the end of the scroll before the progressive render is triggered

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 LESS file is also provided for each stylesheet, containing a set of variables to make generating your own theme even easier. This can be found in tabulator.less

Packaged Themes

As well as the default theme, tabulator comes with a number of pre packaged themes, located in the /themes directory of the package. To use one of these simply include the matching css file instead of the default tabulator.css

For example to use the simple theme, you would need to use the following css link:
<link href="/themes/tabulator_simple.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)
  • Autumn - A colorful, bright layout using shades of orange and brown. (/themes/tabulator_autumn.css)

Bootstrap Theme New

Tabulator also includes a Bootstrap 3 compatible theme that can be included from:

<link href="/themes/bootstrap/tabulator_bootstrap.css" rel="stylesheet">

The stylesheet maps the standard bootstrap table styling onto Tabulator. If you have customised your bootstrap theme, then the /themes/bootstrap directory also contains a variables.less 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 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 bootstrap:

  • table-striped - alternating row colors
  • table-bordered - borders arround 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, data){
        if(data.age >= 18){
            row.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.

Semantic UI Theme New

Tabulator also includes a Semantic UI compatible theme that can be included from:

<link href="/themes/semantic-ui/tabulator_semantic-ui.css" rel="stylesheet">

The stylesheet maps the standard semantic ui table styling onto Tabulator. If you have customised your theme, then the /themes/semantic-ui directory also contains the variables.less and variables_table.less 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, data){
        if(data.age < 18){
            row.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

All elements of Tabulator have classes set to make theming your tables as easy as possible.

General Classes

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-arrowSorting arrows, used in column and group headers

Headers & Columns

Class Element Description
tabulator-headerColumn header row
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-frozenThe containing element for all frozen columns
tabulator-frozen-leftThe containing element for frozen columns on the left edge of the table
tabulator-frozen-rightThe containing element for frozen columns on the right edge of the table

Rows Updated

Class Element Description
tabulator-rowRow of table
tabulator-row-movingThe placeholder for a row as it is being moved by the user.
tabulator-row-handleHandle for moving the row if movableRows is enabled
tabulator-row-editingRow contains a cell being edited
tabulator-cellData cell
tabulator-selectableStyling for selectable rows
tabulator-unselectableStyling for unselectable rows
tabulator-selectedCurrently selected row
tabulator-editingThe cell currently being edited
tabulator-groupA group of rows (including group header)
tabulator-group-headerContains header for a group
tabulator-group-bodyContains all data rows for a group

Pagination

Class Element Description
tabulator-footerTabulator footer element
tabulator-paginatorContains the pagination controls
tabulator-pagesContains individual page buttons
tabulator-pagePage selection button

tabulator.less

A LESS file is included in the project with a number of variables setup 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

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.

Column Header Click New

The headerOnClick 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 data.

{title:"Name", field:"name", headerOnClick:function(e, header, field, columnDef){
        //e - the click event object
        //header - the DOM element of the column header
        //field - the field name of the column
        //columnDef - the column definition object for the column
    },
}

Column Header Double Click New

The headerOnDblClick 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 data.

{title:"Name", field:"name", headerOnDblClick:function(e, header, field, columnDef){
        //e - the couble click event object
        //header - the DOM element of the column header
        //field - the field name of the column
        //columnDef - the column definition object for the column
    },
}

Column Header Right Click New

The headerOnContext 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 data.

{title:"Name", field:"name", headerOnContext:function(e, header, field, columnDef){
        //e - the couble click event object
        //header - the DOM element of the column header
        //field - the field name of the column
        //columnDef - the column definition object for the column
    },
}

Cell Click

The onClick 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 data.

{title:"Name", field:"name", onClick:function(e, cell, value, data){
        //e - the click event object
        //cell - the DOM element of the cell
        //value - the value of the cell
        //data - the data for the row the cell is in
    },
}

Cell Double Click

The onDblClick 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 data.

{title:"Name", field:"name", onDblClick:function(e, cell, value, data){
        //e - the couble click event object
        //cell - the DOM element of the cell
        //value - the value of the cell
        //data - the data for the row the cell is in
    },
}

Cell Right Click

The onContext 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 data.

{title:"Name", field:"name", onContext:function(e, cell, value, data){
        //e - the couble click event object
        //cell - the DOM element of the cell
        //value - the value of the cell
        //data - the data for the row the cell is in
    },
}

Row Click

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

$("#example-table").tabulator({
        rowClick:function(e, id, data, row){
        //e - the click event object
        //id - the id of the row
        //data - the data for the row
        //row - the DOM element of the row
    },
});

Row Double Click

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

$("#example-table").tabulator({
        rowDblClick:function(e, id, data, row){
        //e - the couble click event object
        //id - the id of the row
        //data - the data for the row
        //row - the DOM element of the row
    },
});

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, id, data, row){
        //e - the click event object
        //id - the id of the row
        //data - the data for the row
        //row - the DOM element of the row

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

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(data, row){
        //data - the data for the row
        //row - DOM element for the row
    },
});

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(index, data, row){
        //index - the index for the updated row
        //data - the updated data for the row
        //row - DOM element for the updated row
    },
});

Row Deleted

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

$("#example-table").tabulator({
    rowDeleted:function(id){
        //id - the id of the row
    },
});

Row Moved

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

$("#example-table").tabulator({
    rowMoved:function(id, data, row, index){
        //id - the id of the row
        //data - the data for the row
        //row - the DOM element of the row
        //index - new position of row in table
    }
});

Cell Edit

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

$("#example-table").tabulator({
    cellEdited:function(id, field, value, oldValue, data, cell, row){
        //id - the id of the row
        //field - field of the cell
        //value - the new value for the cell
        //oldValue - the old value for the cell
        //data - the data for the row
        //cell - the DOM element of the cell
        //row - the DOM element of the row
    },
});

Column Moved

The colMoved callback will be triggered when a column has been successfully moved, .

$("#example-table").tabulator({
    colMoved:function(field, columns){
        //field- the filed name of the moved column
        //columns- the updated columns config array
    }
});

Column Title Changed

The colTitleChanged 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({
    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
    },
});

Data Loading

The dataLoading callback is triggered when the setData function is called.

$("#example-table").tabulator({
    dataLoading:function(data, params){
        //data - the data or url passed to the setData function
        //params - the params object passed to the setData function
    },
});

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

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

Data Loading Error

The dataLoadError callback is triggered when a there is an error AJAX loading data. The arguments are passed straight from the AJAX error function.

$("#example-table").tabulator({
    dataLoadError:function(xhr, textStatus, errorThrown){
        //xhr - the XHR object
        //textStatus - error type
        //errorThrown - text portion of the HTTP status
    },
});

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

Data Filtering

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

$("#example-table").tabulator({
    dataFiltering:function(field, type, value){
        //field - the field being filtered
        //type - the type of filter being used
        //value - the value of the filter
    },
});

Data Filtered

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

$("#example-table").tabulator({
    dataFiltered:function(data, field, type, value){
        //data - the subset of the total table data that has passed the filter and is now visible
        //field - the field being filtered
        //type - the type of filter being used
        //value - the value of the filter
    },
});

Data Sorting

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

$("#example-table").tabulator({
    dataSorting:function(sortList, dir){
        //sortList - the field name or array of fields being sorted
        //dir - the direction of the sort
    },
});

Data Sorted

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

$("#example-table").tabulator({
    dataSorted:function(sortList, dir){
        //sortList - the field name or array of fields being sorted
        //dir - the direction of the sort
    },
});

Render Started Updated

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(sortList, dir){
    },
});

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

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

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(){
    },
});

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){
        //data - array of data objects for the selected rows in order of selection
        //rows - array of jQuery elements for the selected rows in order of selection
    },
});

Downloading Table Data

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:

  • csv - Comma seperated value file
  • json - JSON formatted text file
  • xls - Excel File (coming soon)
  • xlsx - Excel File (coming soon)

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

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

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. This function must return a data URI string for the file.

//custom file formatter
var fileFormatter = function(columns, data, options){
    //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

    //create a list of all name fields
    var names = [];

    data.forEach(function(row){
        names.push(row.name);
    })

    //return data URI formatted string
    return 'data:text/plain;charset=utf-8,' + encodeURIComponent(names.join(", "));
}

//trigger file download
$("#example-table").tabulator("download", fileFormatter, "test.txt");

Note: You can find out more about data URI's Here.

Extending Tabulator

If you are using multiple Tabulators across your site, you can often end up declaring the same options or custom formatters, sorter and editors multiple times. To make your code more manageable you can extend Tabulator with your custom options using jQuery's widget extension options.

This allows you to define your standard config once in one file and then have it automatically apply to any Tabulators that you create.

The below code outlines the basic template for the extension and should be included in your project after the tabulator.js file has been loaded but before any Tabulators are created.

$.widget("ui.tabulator", $.ui.tabulator, {
    options: {
        //default options are set here
    },
    sorters:{
        //additional sorters can be added here
    },
    formatters:{
        //additional formatters can be added here
    },
    editors:{
        //additional editors can be added here
    },
    mutators:{
        //additional mutators can be added here
    },
    accessors:{
        //additional accessors can be added here
    }
});

Default Options

Any options that you would usually set when you create your Tabulator can be set in the extension options object, these will automatically apply to any new Tabulator's unless the value is overwritten when you create a specific Tabulator.

For example the below code will cause all Tabulators to have non-resizable columns.

$.widget("ui.tabulator", $.ui.tabulator, {
    options: {
        colResizable:false,
    },
});

Additional Sorters

If you use any custom sorters regularly, you can add them to the extension and then assign them using their name in the column definition array.

$.widget("ui.tabulator", $.ui.tabulator, {
    sorters: {
        //datetime sort using moment.js
        datetime:function(a, b){
            a = moment(a, "DD/MM/YYYY hh:mm");
            b = moment(b, "DD/MM/YYYY hh:mm");
            return a - b;
        },
    },
});

Using a sorter defined in the extension is as simple as passing the name to the sorter parameter in the column definition array.

$("#example-table").tabulator({
    columns:[
        {field:"name", title:"Name"},
        {field:"start", title:"Start Time", sorter:"datetime"},
    ],
});

Additional Formatters

If you use any custom formatters regularly, you can add them to the extension and then assign them using their name in the column definition array.

$.widget("ui.tabulator", $.ui.tabulator, {
    formatters: {
        //show file icon based on extension type
        file:function(value, data, cell, row, options){ //plain text value
            return "<img class='fileicon' src='/images/fileicons/" + value + ".png'></img>";
        },
    },
});

Using a formatter defined in the extension is as simple as passing the name to the formatter parameter in the column definition array.

$("#example-table").tabulator({
    columns:[
        {field:"ext", title:"Icon", formatter:"file"},
        {field:"name", title:"File Name"},
    ],
});

Additional Editors

If you use any custom editors regularly, you can add them to the extension and then assign them using their name in the column definition array.

$.widget("ui.tabulator", $.ui.tabulator, {
    editors: {
        //variant of input editor for handling currency
        money:function(cell, value){
            //create and style input
            var input = $("<input type='text'/>");
            input.css({
                "padding":"4px",
                "width":"100%",
                "box-sizing":"border-box",
                "text-align":"right",
            })
            .val(value);

            if(cell.hasClass("tabulator-cell")){
                setTimeout(function(){
                    input.focus();
                },100);
            }

            input.inputmask("currency");

            //submit new value on blur
            input.on("blur", function(e){
                cell.trigger("editval", input.val());
            });

            //submit new value on enter
            input.on("keydown", function(e){
                if(e.keyCode == 13){
                    cell.trigger("editval", input.val());
                }
            });

            return input;
        },
    },
});

Using a editor defined in the extension is as simple as passing the name to the editor parameter in the column definition array.

$("#example-table").tabulator({
    columns:[
        {field:"item", title:"item"},
        {field:"cost", title:"Cost", editor:"moeny"},
    ],
});

Additional Mutators

If you use any mutators regularly, you can add them to the extension and then assign them using their name in the column definition array.

$.widget("ui.tabulator", $.ui.tabulator, {
    mutators: {
        tooManyCars:function(value, type, data){
            return value > 5; //return the new value for the cell data.
        },
    },
});

Using a mutator defined in the extension is as simple as passing the name to the mutator parameter in the column definition array.

$("#example-table").tabulator({
    columns:[
        {field:"cars", title:"Cars", mutator:"tooManyCars"},
    ],
});

Additional Accessors

If you use any accessors regularly, you can add them to the extension and then assign them using their name in the column definition array.

$.widget("ui.tabulator", $.ui.tabulator, {
    accessors: {
        roundDown:function(value, data){
            return Math.floor(value); //return the new value for the cell data.
        },
    },
});

Using a accessor defined in the extension is as simple as passing the name to the accessor parameter in the column definition array.

$("#example-table").tabulator({
    columns:[
        {field:"tax", title:"Tax (£)", accessor:"roundDown"},
    ],
});

Localization Updated

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"
            },
            "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

Deprecated Functionality

The following sections have been updated and now have elements of obsolete functionality that have been deprecated and will be removed in version 3.0.

Pagination

Deprecated Function

The use of a boolean value to enable local pagination through the pagination option:

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

Replacement Function

This has been replaced with using a string to choose between local and remote pagination options:

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

Persistent Column Layout

Deprecated Function

Enabling persistent column layouts using the columnLayoutCookie and columnLayoutCookie options:

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

Replacement Function

This has been replaced with using the persistentLayout and persistentLayoutID options:

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

Set Ajax Request Type New

Deprecated Function

Setting the AJAX request type using the ajaxType option:

$("#example-table").tabulator({
    ajaxType:"POST", //ajax HTTP request type
});

Replacement Function

This has been replaced with the ajaxConfig option which allows the type to be set as well as all other ajax config options:

$("#example-table").tabulator({
    ajaxConfig:"POST", //ajax HTTP request type
});