stateSave

State saving - restore table state on page reload.

Description

Enable or disable state saving. DataTables stores state information such as pagination position, display length, filtering and sorting. When this initialisation option is active and the end user reloads the page the table's state will be altered to match what they had previously set up.

Data storage for the state information in the browser is performed by use of the localStorage or sessionStorage HTML5 APIs. The stateDuration parameter is used to indicate to DataTables which API should be used (localStorage: 0 or greater, or sessionStorage: -1). The stateDuration parameter can also be used to indicate how long a saved state should be considered valid for. Please refer to stateDuration for additional details.

To be able to uniquely identify each table's state data, information is stored using a combination of the table's DOM id and the current page's pathname. If the table's id changes, or the page URL changes, the state information will be lost.

If you do not wish to use localStorage or sessionStorage, alternative options such as saving the state on a server through Ajax can be used through the stateSaveCallback and stateLoadCallback options.

Child rows state can also be maintained, but this requires some work to be done by the developer. There is a requestChild that is triggered whenever DataTables wants to insert a child row into the table. The developer must set a callback function for this event that deals with the display of the childrow. It is also worth noting that for this to work the rows have to have ids, and that this functionality is only available in version 1.11.0 and above.

Note: As of 1.11.0 the datatables state is stored regardless of the stateSave option. This data is only used to revert to a state when the stateSave option is enabled - otherwise it is not used.

Type

This option can be given in the following type(s):

• boolean

Default

• Value: false

Examples

new DataTable('#myTable', {
	stateSave: true
});

new DataTable('#myTable', {
	stateSave: true,
	stateSaveCallback: function (settings, data) {
		localStorage.setItem(
			'DataTables_' + settings.sInstance,
			JSON.stringify(data)
		);
	},
	stateLoadCallback: function (settings) {
		return JSON.parse(localStorage.getItem('DataTables_' + settings.sInstance));
	}
});

Related

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