Version 6.3 Released!

Click to checkout the new features
Old Documentation
You are browsing documentation for an old version of Tabulator. Consider upgrading your project to Tabulator 6.3

Release Notes

Data Tree Layout

For nested data sets Tabulator now allows you to structure your rows as a tree, allowing users to collapse and expand nested sets of rows.

Loading Example...
Source Code

HTML

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

JavaScript

var table = new Tabulator("#example-table", {
    height:"311px",
    data:tableDataNested,
    dataTree:true,
    dataTreeStartExpanded:true,
    columns:[
    {title:"Name", field:"name", width:200, responsive:0}, //never hide this column
    {title:"Location", field:"location", width:150},
    {title:"Gender", field:"gender", width:150, responsive:2}, //hide this column first
    {title:"Favourite Color", field:"col", width:150},
    {title:"Date Of Birth", field:"dob", align:"center", sorter:"date", width:150},
    ],
});

Nested Table Data

var tableDataNested = [
    {name:"Oli Bob", location:"United Kingdom", gender:"male", col:"red", dob:"14/04/1984", _children:[
        {name:"Mary May", location:"Germany", gender:"female", col:"blue", dob:"14/05/1982"},
        {name:"Christine Lobowski", location:"France", gender:"female", col:"green", dob:"22/05/1982"},
        {name:"Brendon Philips", location:"USA", gender:"male", col:"orange", dob:"01/08/1980", _children:[
            {name:"Margret Marmajuke", location:"Canada", gender:"female", col:"yellow", dob:"31/01/1999"},
            {name:"Frank Harbours", location:"Russia", gender:"male", col:"red", dob:"12/05/1966"},
        ]},
    ]},
    {name:"Jamie Newhart", location:"India", gender:"male", col:"green", dob:"14/05/1985"},
    {name:"Gemma Jane", location:"China", gender:"female", col:"red", dob:"22/05/1982", _children:[
        {name:"Emily Sykes", location:"South Korea", gender:"female", col:"maroon", dob:"11/11/1970"},
    ]},
    {name:"James Newman", location:"Japan", gender:"male", col:"red", dob:"22/03/1998"},
];

To enable data trees in your table, set the dataTree property to true in your table constructor:

var table = new Tabulator("#example-table", {
    dataTree:true,
});

In order to build a table with nested data you must structure your data in a certain way.

If a row is to have child rows, these child data objects must be provided as an array to the rows _children property:

[
    {id:1, name:"Billy Bob", age:"12" "_children":[
        {id:2, name:"Mary May", age:"1"}, //child rows nested under billy bob
        {id:3, name:"Christine Lobowski", age:"42"},
        {id:4, name:"Brendon Philips", age:"125", "_children":[
            {id:5, name:"Margret Marmajuke", age:"16"}, //child rows nested under brendon philps
            {id:6, name:"Frank Peoney", age:"12"},
        ]},
    ]},
    {id:7, name:"Jenny Jane", age:"1"},
    {id:8, name:"Martha Tiddly", age:"42", "_children":[
        {id:9, name:"Frasier Franks", age:"125"}, //child row nested under martha tiddly
    ]},
    {id:10, name:"Bobby Green", age:"11"},
]

For full details checkout the Tree Structure and Nested Data Documentation.

Vertical Column Headers

Table headers can now be set to have a vertical text orientation.

Loading Example...
Source Code

HTML

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

JavaScript

var table = new Tabulator("#example-table", {
    height:"311px",
    columns:[
        {title:"Name", field:"name", headerSort:false, headerVertical:true},
        {title:"Progress", field:"progress", sorter:"number", align:"left", formatter:"progress",  editable:true, headerSort:false, headerVertical:true},
        {title:"Gender", field:"gender", headerSort:false, headerVertical:true},
        {title:"Rating", field:"rating", align:"center", headerSort:false, headerVertical:true},
        {title:"Date Of Birth", field:"dob", align:"center", sorter:"date", headerSort:false, headerVertical:true},
        {title:"Driver", field:"car", align:"center", formatter:"tickCross", headerSort:false, headerVertical:true},
    ],
});

To enable this, set the headerVertical column definition property to true

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

The headerVertical property can take one of three values:

  • false - vertical columns disabled (default value)
  • true - vertical columns enabled
  • "flip" - vertical columns enabled, with text direction flipped by 180 degrees

React Component

There is now a react component available for Tabulator to make it even easier to integrate interactive tables with your react project.

For full details checkout the Framework Documentation.

Search Table Data

A couple of new search functions have been added to allow you to looup row components and row data by the data it contains.

Each search function allows you to specify filters, exactly like those used by the setFilter function, any matching data or row components are then returned

Search for Row Components

The searchRows function allows you to retrieve an array of row components that match any filters you pass in. it accepts the same arguments as the setFilter function.

var rows = table.searchRows("age", ">", 12);//get row components for all rows with an age greater than 12

Search for Row Data

The searchData function allows you to retrieve an array of table row data that match any filters you pass in. it accepts the same arguments as the setFilter function.

var data = table.searchData("age", ">", 12);//get row data for all rows with an age greater than 12

Sorting

Sort Order

The new sortOrderReverse option lets you reverse the sort ordering when applying multiple sorters to match the sorting order of other table systems like excel.

var table = new Tabulator("#example-table", {
    sortOrderReverse:true,
});

Disable Multi Column Header Sort

You can now disable multi column header sorting by setting the columnHeaderSortMulti option to false

var table = new Tabulator("#example-table", {
    columnHeaderSortMulti:false,
});

Row Components

New Functions

The row component has been updated to include some additional functionality

Get Next Row

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

var nextRow = row.getNextRow();

Get Previous Row

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

var prevRow = row.getPrevRow();

Formatters

Updated Formatters

Tick Cross

The tickCross formatter now has param tickElement and crossElement params to allow for easier customisation of the formatter 

{title:"Example", field:"example", formatter:"tickCross", formatterParams:{
    tickElement:"<i class='fa fa-check'></i>",
    crossElement:"<i class='fa fa-times'></i>",
}}

Setting either of these properties to false will prevent that icon being shown.

The formatter has optional properties for the formatterParams object:

Depricated Formatters

Tick

The tick formatter has been depricated, you should now use the tickCross formatter with the crossElement formatterParams set to false to replicate its functionality.

Editors

New Editors

autocomplete

The new autocomplete editor allows users to lookup values from an autocomplete list

{title:"Example", field:"example", editor:"autocomplete", editorParams:{values:["red", "green", "blue", "orange"]}}

Updated Editors

Tick Cross

The tickCross editor now has tristate functionality built in, great for wheny ou want to use it as a header filter.

Tristate functionality can be enabled by setting the new tristate parameter to true, you can also choose the default value for the indeterminate state with the intederminateState param (defaults to null)

{title:"Driver", field:"driver", editor:"tickCross", editorParams:{tristate:true, indeterminateValue:"unsure"}}

Select

The select editor has been rebuilt, and no longer uses a standard select element. This allows it to open the moment a user clicks on the cell, rather than requiring a second click to open the list

You can now pass a boolean value of true to the values property of the editorParams object to auto populate the select list with all the values of the cells column.

{title:"Example", field:"example", editor:"select", editorParams:{values:true}}

When passing values into the select editor, they must now be passed into the values property rather than directly into the editorParams object.

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

Number

The number formatter has been updated so success is now strictly triggered, (eg, changing the cells value from undefined to 0 will now trigger a successful edit)

Text Area

The textarea formatter has been updated so success is now strictly triggered, (eg, changing the cells value from undefined to 0 will now trigger a successful edit)

Depricated Editors

Tick

The tick editor has been depricated, you should now use the tickCross editor.

Table Download

Download Grouped Column Headers and Row Groups

Tabulator will now include column groups and row groups in download output (some downloaders will not be able to show allfeatures due to the limitiations of the file formats)

You can choose to remove column headers groups and row groups in the output data by setting the values in the downloadConfig option in the table definition:

var table = new Tabulator("#example-table", {
    downloadConfig:{
        columnGroups:false, //include column groups in column headers for download
        rowGroups:false, //do not include row groups in download
    },
});

PDF jsPDF Param

A new jsPDF property has been added to the downloader params for the pdf downloader, this allows you to configure the setup object that is passed into the jsPDF constructor

table.download("pdf", "data.pdf", {
    orientation:"portrait", //set page orientation to portrait
    title:"Dynamics Quotation Report", //add title to report
    jsPDF:{
        unit:"in", //set units to inches
    },
});

Clipboard

Tabulator will now include column headers groups and row groups in the clipboard output.

You can choose to remove column headers groups and row groups in the output data by setting the values in the clipboardCopyConfig option in the table definition:

var table = new Tabulator("#example-table", {
    clipboardCopyConfig:{
        columnHeaders:false, //don't include column headers in clipboard output
        rowGroups:false, //do not include row groups in clipboard output
    },
});

Filters

Disable Live Filtering of Header Filters

By default if an input element is used as a header filter element, the table will be filtered in real time as the user types in the input element.

If you would prefer that the input element behave like a standard editor without live updating the table, you can now set the headerFilterLiveFilter column definition property to false

{title:"Name", field:"name", headerFilter:"input", headerFilterLiveFilter:false}

Ajax

Default Ajax Headers and Cookies

By default Tabulator will now send the following headers with any ajax request:

Header Value
X-Requested-With XMLHTTPRequest
Accept application/json

Any credentials stored in cookies with the page will also be sent with the request.

Content Type

When using a request method other than "get" Tabulator will now send any parameters with a content type of form data. You can change the content type with the ajaxContentType option. This will ensure parameters are sent in the format you expect, with the correct headers.

var table = new Tabulator("#example-table", {
    ajaxURL:"http://www.getmydata.com/now", //ajax URL
    ajaxConfig:"post", //ajax HTTP request type
    ajaxContentType:"json", // send parameters to the server as a JSON encoded string
});

The ajaxContentType option can take one of two values:

  • "form" - send parameters as form data (default option)
  • "json" - send parameters as JSON encoded string

Group Values

By default Tabulator will create groups for rows based on the values contained in the row data. if you want to explicitly define which field values groups should be created for at each level, you can now use the groupValues option.

This option takes an array of value arrays, each item in the first array should be a list of acceptable field values for groups at that level

var table = new Tabulator("#example-table", {
    groupBy:["color", "age"],
    groupValues:[
        ["red", "blue", "green"], //create groups for color values of "red", "blue", and "green",
        [10, 20, 30], //create sub groups for ages of 10, 20 and 30
    ],
});

Rows with values not in the arrays will not be show in the table. In this mode empty groups will remain visible in the table.

If you want to only specify groups for some of the levels, you can pass a value of false into the levels where you want Tabulator to decide on the grouping.

var table = new Tabulator("#example-table", {
    groupBy:["color", "age"],
    groupValues:[
        false, //createany groups needed for the colors field
        [10, 20, 30], //create sub groups for ages of 10, 20 and 30
   ],
});

Row Selection

The new selectableRangeMode option allows you choose a new click mode of row range selection.

If you would prefere to select a range of row by clicking on the first row then holding down shift and clicking on the end row then you can achieve this by setting the selectableRangeMode to click

var table = new Tabulator("#example-table", {
  selectableRangeMode:"click",
});

Nested Data Custom Field Separator

When using nested data, if you need to use the . character as part of your field name, you can change the separator to any other character using the nestedFieldSeparator option

var table = new Tabulator("#example-table", {
    nestedFieldSeparator:"|", //change the field separator character to a pipe
    columns:[
        {title:"Name", field:"user|name"},  //link column to name property of user object
    ],
});

By setting the nestedFieldSeparator to false you can disable nested data parsing. In this case all fields will be assumed to be directly on the row object regardless of characters in the field name

var table = new Tabulator("#example-table", {
    nestedFieldSeparator:false, //disable nested data parsing
});

Styling

the footerActiveColor SCSS vairable has been added to all themes to make it possible to set the text color for active pagination buttons.

Return Type Warnings

Console warning have been added notify developers when the wrong tepe of objects are returned from editors and formatters.

Bug Fixes

The following minor bugs have been fixed:

  • html sanitization has been removed from the image formatter to prevent corruption of links
  • image formatter no longer sanitizes url string
  • fixed row deselection on deletion
  • validators now correctly pull in parameters
  • arrays in row data are no longer converted to objects when retured from the getData function
  • a typo preventing the keybindings extension from being pulled in on npm run on linux has been resolved
  • the clopboard module now correctly handles text selection
  • option groups in the select editor how display correctly

Donate