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

Persistent Configuration

Overview

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

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

Persistence Types

Tabulator can persist a variety of different table configuration options. By setting the persistence property to true the table will persist the sort, filter, headerFilter, group (groupBy, groupStartOpen, groupHeader), pagination (paginationSize, currently selected page), 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 filters
        headerFilter: true, //persist header filters
        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 Filters

You can ensure that programatic 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 filters
    }
});

Built In Filters
Only built-in filters can be stored (including module), custom filter functions cannot be persistently stored.

Header Filters
This option only perists filters set programatically, eg using the setFilter function. If you want to persist header filters, you need to use the headerFilter option.

Persistent Heeader Filters

You can ensure the data header filters are stored for the next page load by setting the headerFilter property of the persistence option to true

This will persist all active column header filters on the table

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

Built In Filters
Only built-in filters can be stored (including module), custom filter functions cannot be persistently stored.

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.

Persistence Mode

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

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

Custom Persistence Modes

You can extend the table with your own persistence modes by extending the reader and writer objects on the module. See the Persistence Module Documentation for more information

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

Persistence ID

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

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

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

var table = new Tabulator("#example-table", {
    persistence:true, //enable persistence
    persistenceID:"example1", //id string, can only be numbers, letters, hyphens and underscores.
});

Manual Column Layout

Get Column Layout Information

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

var columnLayout = table.getColumnLayout();

Set Column Layout

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

table.setColumnLayout(columnLayout);
Donate