{hero}

state()

Since: DataTables 1.10.1

Get / set the state of the table.

Description

The "state" of a DataTable refers to properties that define its current display, such as pagination parameters, ordering and filtering. While you can use individual API methods to get and set properties (e.g. order()) this method provides a collected API that will give and take information about the table as a whole. Please note also that it does work without stateSave being enabled.

The data object has the following format, but please be aware that plug-ins and extensions to DataTables can modify this structure by adding data as they require for their own state information.

{
    "time":   {number}               // Time stamp of when the object was created
    "start":  {number}               // Display start point
    "length": {number}               // Page length
    "order":  {array}                // 2D array of column ordering information (see `order` option)
    "search": {
        "search":          {string}  // Search term
        "regex":           {boolean} // Indicate if the search term should be treated as regex or not
        "smart":           {boolean} // Flag to enable DataTables smart search
        "caseInsensitive": {boolean} // Case insensitive flag
    },
    "columns" [
        {
            "visible": {boolean}     // Column visibility
            "search":  {}            // Object containing column search information. Same structure as `search` above
        }
    ]
}

If using this method as a setter, you will very likely want to call draw(), passing in false to the method, to ensure that the table is redrawn with the new state (and that the correct paging is shown).

Types

function state()

Description:

Get the state of the DataTables

Returns:

State saved object

function state( set [, ignoreTime ] )

Description:

Set the state of the DataTables

Parameters:
Returns:

DataTables API instance

Examples

Get the saved page length from the state object:

alert('Saved page length is: ' + table.state().length);

Get the table state, change it and load it back:

var table = new DataTable('#myTable');
var state = table.state();

state.start = 10;

table.state(start).draw(false);

Related

The following options are directly related and may also be useful in your application development.