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

Table Layout

Fit Columns to Data and Stretch Last Column

The new fitDataStretch layout mode functions in the same way as the fitDataFill mode, but instead of stretching the empty row to fill the table it stretches the last visible column.

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

Persistent Config

Ther persistence system has received an overhaul in this release, providing a more consistent way to configure table persistence and allow even more table options to be persisted between sessions.

Checkout the Upgrade Guide for more information on how to move over to the new system.

By setting the persistence property to true the table will persist the sort, filter, group (groupBy, groupStartOpen, groupHeader), pagination (paginationSize), and column (title, width, visibility, order) configuration of the table

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

For more granular control of what is persisted you can pass an object to the persistence property:

var table = new Tabulator("#example-table", {
    persistence:{
        sort: true, //persist column sorting
        filter: true, //persist filter sorting
        group: true, //persist row grouping
        page: true, //persist page
        columns: true, //persist columns
    }
});

Persistent Sort

You can ensure the data sorting is stored for the next page load by setting the sort property of the persistence option to true

This will persist all active column sorts on the table

var table = new Tabulator("#example-table", {
    persistence:{
        sort: true, //persist sort
    }
});

Note: Only built-in sorters can be stored (including module), custom sorter functions cannot be persistently stored.

Persistent Filter

You can ensure the data filtering is stored for the next page load by setting the filter property of the persistence option to true

This will persist all active column filters on the table

var table = new Tabulator("#example-table", {
    persistence:{
        filter: true, //persist filter
    }
});

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

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

Persistent Row Grouping

You can ensure the row grouping settings are stored for the next page load by setting the group property of the persistence option to true

This will persist the current values of the groupBy, groupStartOpen, groupHeader options

var table = new Tabulator("#example-table", {
    persistence:{
        group: true, //persist row grouping
    }
});

If you want more control over which group options are persisted you can pass an object to the group property:

var table = new Tabulator("#example-table", {
    persistence:{
        group:{
            groupBy: true, //persist only the groupBy setting
            groupStartOpen: false,
            groupHeader: false,
        }
    }
});

Persistent Pagination

You can ensure the pagination settings are stored for the next page load by setting the page property of the persistence option to true

This will persist the current values of the paginationSize option and the currently selected page

var table = new Tabulator("#example-table", {
    persistence:{
        page: true, //persist pagination settings
    }
});

If you want more control over which page options are persisted you can pass an object to the group property:

var table = new Tabulator("#example-table", {
    persistence:{
        page: {
            size:true, //persist the current page size
            page:false, //do not persist the current page
        }
    }
});

Persistent Column Layout

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

This will persist the current values of the title, width, visible options as well as the order of the columns

var table = new Tabulator("#example-table", {
    persistence:{
        columns: true, //persist column layout
    }
});

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

Custom Column Definition Monitoring

If you would prefer to persist additional column definition properties you can instead pass an array of the definition property keys to be watched, these will be stored whenever the column definitions are updated:

var table = new Tabulator("#example-table", {
    persistence:{
        columns: ["width", "visible", "frozen"], //persist changes to the width, visible and frozen properties
    }
});

Note: If you are going to use this mode of operation the property must exist in the column definition when the column is first initialized. Tabulator can only monitor properties that have been changed not those that have been added.

Custom Persistence Functions

If you would like to use an alternative storage method to cookies or local storage, you can override the modules reader and writer functions using the persistenceWriterFunc and persistenceReaderFunc options. It is important that if you use this method that you use both of the options defined below as one is needed to store the config data and the other to retrieve it.

When storing persistence data Tabulator stores one object per type of data being recorded (sort, filter, group, page, columns). This approach ensures itdoes not have to regenerate the entire persistence object when one value changes. The reader and writer functions handle this by being passed in the type as an argument to the functions.

Tabulator will also set a persistence ID for the table to ensure that if you have multiple tables on a page the persistence from one table is not loaded into another, this is passed into the id argument of the functions.

Persistence Data Writer Function

The persistenceWriterFunc function will receive three arguments, the persistance id of the table, the type of data to be written and an object or array representing the data

var table = new Tabulator("#example-table", {
    persistenceWriterFunc:function(id, type, data){
        //id - tables persistence id
        //type - type of data being persisted ("sort", "filter", "group", "page" or "columns")
        //data - array or object of data

        localStorage.setItem(id + "-" + type, JSON.stringify(data));
    },
});

Persistence Data Reader Function

The persistenceReaderFunc function will receive two arguments, the persistance id of the table, and the type of data to be written. This function must synchronously return the data in the format in which it was passed to the persistenceWriterFunc function. It should return a value of false if no data was present

var table = new Tabulator("#example-table", {
    persistenceReaderFunc:function(id, type){
        //id - tables persistence id
        //type - type of data being persisted ("sort", "filter", "group", "page" or "columns")

        var data = localStorage.getItem(id + "-" + type);

        return data ? JSON.parse(data) : false;
    },
});

Table Redraw Blocking

By default Tabulator will redraw part of the table when changes are made to visible data (eg. adding rows, deleting rows, sorting, etc). When carrying out lots of actions in quick succession this can cause a degradation of table performance as the table is redrawn several times.

To get around this you can use the blockRedraw and restoreRedraw functions to temporarily disable all table redraw actions while you are manipulating the table data.

Start by calling the blockRedraw function, this will prevent actions from triggering an update of the Virtual DOM:

table.blockRedraw(); //block table redrawing

When you have completed your required actions, call the restoreRedraw function. This will restore automatic table redrawing and trigger an appropriate redraw if one was needed as a result of any actions that happened while the redraw was blocked.

table.restoreRedraw(); //restore table redrawing

Table Resizing While the table redraw has been disabled, resizing the tables containing element may result in visual corruption of the table until the restoreRedraw function is called

Redraw Block Duration It is recommended that you only block table redrawing for short durations while you are performing update actions. leaving the table redraw blocked for long periods of time may result in visual corruption of the table and a poor user experience.

Finding Tables

When you first create a table, the constructor function returns the instance of that table to a variable:

var table = new Tabulator("#example-table", {
    height:"300px", //set the table height option
});

Sometimes you may want to access this table but not have easy access to the variable that the table was stored in.

The good news is that Tabulator keeps track of all tables that it creates and you can use the findTable function on the Tabulator prototype to lookup the table object for any existing table using the element they were created on.

The findTable function will accept a valid CSS selector string or a DOM node for the table as its first argument.

var table = Tabulator.prototype.findTable("#example-table"); // find table object for table with id of example-table

The findTable function will return an array of matching tables. If no match is found it will return false

Themes

Materialize Theme

Tabulator now comes with a Materialize compatible theme that can be included from: 

<link href="/dist/css/materialize/tabulator_materialize.min.css" rel="stylesheet">

The stylesheet maps the standard Materialize table styling onto Tabulator. If you have customised your Materialize theme, then the /src/scss/materialize directory also contains a variables.scss file containing all the standard materialize variables. Make any changes in here to match your custom theme and recompile the tabulator_materialize.css file and Tabulator will now match your theme.

The theme also maps some of the standard table styling classes. You can use any of these classes on your Tabulator element and get the same effect as materialize:

  • striped - alternating row colors

Formatting

Title Formatter

the titleFormatter functions now accept the onRendered callback function as thier fourth argument.

Formatters

Link Formatter

A download property has been added to the link formatter formatterParams object to all setting of the download attribute on the anchor tag.

The property can have one of three values:

  • true - a boolean value of true will mark the link as a download and use the filename provided by the server
  • string - a string for the filename of the downloaded file
  • function - a callback that will be passed in the cell component as an argument and should return the file name for the downloaded file
{title:"Example", field:"example", formatter:"link", formatterParams:{
    download:true, //treat the link as a download
}}

Responsive Collapse Formatter

Updates have been made to the responsive collapse layout option, wheb using a column with the responsiveCollapse formatter to provide a toggle for the collapsed data.

The column with the responsiveCollapse formatter will now automatically be hidden when no columns have been collapsed, and become visible when columns are collapsed.

Row Number Formatter

The rownum formatter will now keep consistent numbering when sorting or filtering rows

Editing

Mobile Editing

Tabulator can now detect when it is being run on a mobile device.

There was previously an issue where if the table was set to a percentage height and an input editor was used, when the input element got focus the virtual keyboard appeard, reszing the table, causing the table to be redrawn, causing the edit to be cancled.

Now when Tabulator detects it is running on a mobile device it will automatically block table redraws when an editor is active to prevent interference from the devices virtual keyboard.

Edit Mutator Data

Edit mutators are now passed the full updated data object for each row when an update is triggered, instead of an object containing just the updated properties.

Editors

Number Editor

The new verticalNavigation option in the editorParam property for the number editor allows you to control what happens when the user presses the up and down arrow keys while using this editor. it can have one of two values:

  • editor - the arrow keys increase/decrease the value in the editor and do not navigate the table(default)
  • table - the arrow keys will navigate to the prev/next row and will not affect the cell value
{title:"Example", field:"example", editor:"number", editorParams:{
    verticalNavigation:"table", //up and down arrow keys navigate away from cell without changing value
}}

Textarea Editor

The new verticalNavigation option in the editorParam property for the textarea editor allows you to control what happens when the user presses the up and down arrow keys while using this editor. it can have one of three values:

  • hybrid - the arrow keys move the cursor around the text area, when the cursor reaches the start or end of the contents of the text area it navigates to the next row of the table (default)
  • editor - the arrow keys move the cursor around the textarea contents but do not navigate round the table
  • table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor
{title:"Example", field:"example", editor:"textarea", editorParams:{
    verticalNavigation:"editor", //navigate cursor around text area without leaving the cell
}}

Select Editor

The new verticalNavigation option in the editorParam property for the select editor allows you to control what happens when the user presses the up and down arrow keys while using this editor. it can have one of three values:

  • editor - value selection up and down the list, will not navigate round the table (default)
  • table - the arrow keys will navigate to the prev/next row and will not change the selected value in the list
  • hybrid - the arrow keys move the value selection up and down the list, when it reaches the end of the list it moves on to the adjacent row
{title:"Example", field:"example", editor:"select", editorParams:{
    verticalNavigation:"hybrid", //navigate to new row when at the top or bottom of the selection list
}}

Autocomplete Editor

The new verticalNavigation option in the editorParam property for the autocomplete editor allows you to control what happens when the user presses the up and down arrow keys while using this editor. it can have one of three values:

  • editor - value selection up and down the list, will not navigate round the table (default)
  • table - the arrow keys will navigate to the prev/next row and will not change the selected value in the list
  • hybrid - the arrow keys move the value selection up and down the list, when it reaches the end of the list it moves on to the adjacent row
{title:"Example", field:"example", editor:"autocomplete", editorParams:{
    verticalNavigation:"hybrid", //navigate to new row when at the top or bottom of the selection list
}}

Rows

Row Grouping

Click Callbacks

The groupClick, groupDblClick and groupContext callbacks now have a this scope of the table.

Visible Row Range Lookup

Functions for retreiving row and row data such as getRows, getData, and getDataCount now accept a string argument instead of a boolean. By default these functions will return based on all rows held in the table, to restrict the rows returened you can pass a an argument to the functions with one of the following values:

  • active - only return rows that pass the current filters
  • visible - only return rows currently visible in the table viewport
var rows = table.getRows("visible"); //retrieve row components for all rows currently visible in the table viewport

Delete Multiple Rows

You can now delete multiple rows at once by passing an array of row component look up options to the deteleRow function

table.deleteRow([15,7, 9]); //delete rows with ids of 15, 7 and 9

Clipboard

Visible Copy Selector

A new visible cope selector has been added to allow clipboard copying of only the rows currently visisible in the table viewport

var table = new Tabulator("#example-table", {
    clipboardCopySelector:"visible", //copy only the rows currently visible in the table viewport to the clipboard
});

Pagination

Initial Load Page

By default Tabulator will load the first page of data when the table is initially loaded. You can use the paginationInitialPage option to specify that a specific page should be loaded when the table first loads.

var table = new Tabulator("#example-table", {
    pagination:"local", //enable local pagination.
    paginationInitialPage:2, // this option can take any positive integer value (default = 1)
});

Columns

Promise Returns

The addColumn and deleteColumn table functions now return a promise. As does the delete function on the column component.

table.deleteColumn("name")
.then(function(){
    //success
})
.catch(function(error){
    //failure
})

Resize Handle Double Click Propagation

Double click on the column resize handles no longer proagate through to the cell or row to be consistent with the click event handlers.

Assign Class to Column Group Header

The cssClass option is now available on column groups to set classes on the column group header

var table = new Tabulator("#example-table", {
    columnHeaderVertAlign:"bottom", //align header contents to bottom of cell
    columns:[
        {title:"Name", field:"name", width:160},
        {
            title:"Work Info",
            cssClass:"custom-group-class", //add custom class to column group header element
            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},
            ],
        },
    ],
});

Vertical Column Header Alignment

The columnVertAlign option has been renamed to columnHeaderVertAlign to make it clearer that it only affects the column headers

var table = new Tabulator("#example-table", {
    columnHeaderVertAlign:"bottom", //align header contents to bottom of cell
});

Update Column Definition

You can update the definition of a column with the updateColumnDefinition function. The first argument can be any any of the standard column component look up options. The second argument should be an object containing the properties of the column that you want to change. Any properties defined on the original column definition and not contained in the update object will be unchanged.

table.updateColumnDefinition("name", {title:"Updated Title"}) //change the title on the name column

Alternatively if you have the Column Component of the column you wish to update, you can call the updateDefinition function directly on the component.

column.updateDefinition({title:"Updated Title"}) //change the column title

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

Returned Promise

The updateColumnDefinition and updateDefinition methods return a promise, this can be used to run any other commands that have to be run after the column has been updated. By running them in the promise you ensure they are only run after the table has been redrawn. The promise will resolve with the updated column component for the column as an argument

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

AJAX

URLs with Parameters

The ajaxURL option can now handle urls that contain existing parameters

var table = new Tabulator("#example-table", {
    ajaxURL:"http://www.getmydata.com/now?data=today", //ajax URL with parameter after the "?"
});

Row Selection

Multiple Row Selection

If you want to select multiple rows you can now pass one of 4 options into the selectRow function:

  • array - pass an array of row component look up options into the first parameter
  • "all" - pass a string of all to select all rows in the table
  • "active" - pass a string of active to select only active rows (rows that match the current filters)
  • "visible" - pass a string of visible to select only rows currently visible in the table viewport
table.selectRow("visible"); //select all rows currently visible in the table viewport

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

Downloading

Download Data Set

By default the download function will include only the active rows in the download output (those that match the current filters). An optional fourth argument to the download function now allows you to specify the data set you wish to download, you can choose from one of three options:

  • active - include the active (filtered) rows only in the download output (default)
  • all - include all rows in the download output regardless of whether they are filtered or not
  • visible - include only rows currently visible in the table viewport
table.download("csv", "data.csv", {}, "visible"); //include only rows visible in the table viewport in the download output

Grouped Data
The all option is not available for grouped data. This is because grouping is carried out after filtering in Tabulators data processing pipeline, so only filtered data ever makes it into groups.

HTML Downloader

A new html downloader has been added to allow users to download the table as a simple HTML file

table.download("html", "data.html"); // download table as HTML file

Styling

By default the HTML output is a simple unstyled table. if you would like to match the current table styling you can set the style property to true in the options object

table.download("html", "data.html", {style:true}); //download a html table with matching styling

XLSX Downloader

SheetsJS Options

You can now configure the workbook created by SheetJS using the native SheetJS workbook setup options with the optional documentProcessingcallback. This function is called when the workbook is ready to be created. The first argument is the workbook object complete with all the sheet data. It must return the updated workbook

table.download("xlsx", "data.xlsx",{
    documentProcessing:function(workbook){
        //workbook - sheetJS workbook object

        //set some properties on the workbook file
        workbook.Props = {
            Title: "SheetJS Tutorial",
            Subject: "Test",
            CreatedDate: new Date(2017,12,19)
        };

        return workbook;
    }
}); //download a xlsx file using SheetJS properties

HTML Output

CSS Class Duplication

The HTML Table Export module has been updated, now css classes applied with the cssClass column definition property will be duplicated through to the module output.

In practice this means that the getHtml function and the print styling output will now copy the css classes to cells and column headers.

Callbacks

Scrolling Callbacks

Vertical Scroll

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

var table = new Tabulator("#example-table", {
    scrollVertical:function(top){
        //top - the current vertical scroll position
    },
});

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

Horizontal Scroll

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

var table = new Tabulator("#example-table", {
    scrollHorizontal:function(left){
        //left - the current horizontal scroll position
    },
});

Bug Fixes

The following minor bugs have been fixed:

  • The onRendered function is now correctly called on cell formatters when the cell is redrawn
  • Fix progress formatter rendering issues on firefox
  • Fixed missing semi colons in the bulma theme variables.scss file
  • Fixed error when using clipboard functionality on tables with grouped columns
  • The clickable area around the group header arrow toggle has been expanded to make it easier to click on
  • Fixed regression in the jQuery wrapper that was preventing it from working in web browsers
  • Removed duplicate call to the values function on the select editor on initial open
  • Tabbing between editors in IE has now been fixed
  • Fixed passive event listere warning on new row creation
  • Fixed memory leak when clearing header filters
  • Fixed issue with clipboard module not correctly appling accessors to clipboard data

Donate