DataTables logo DataTables

This site contains the legacy documentation for DataTables v1.9 and earlier for reference only.
DataTables 1.9 was End Of Life in 2014. Do not use it for new work.
The current release of DataTables can always be found on DataTables.net.

Options

Where the DataTables features can be considered rough grain tuning of your DataTables integration, there are many other parameters which will let you obtain the fine grain tuning you might need to make the integration truly seamless. Almost every function that DataTables provides can be fine tuned in some manner using the initialisation options shown below.

bDestroy
Show details

Replace a DataTable which matches the given selector and replace it with one which has the properties of the new initialisation object passed. If no table matches the selector, then the new DataTable will be constructed as per normal.
Default: false
Type: boolean
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "sScrollY": "200px",
       "bPaginate": false
     } );
     
     // Some time later....
     $('#example').dataTable( {
       "bFilter": false,
       "bDestroy": true
     } );
   } );
bRetrieve
Show details

Retrieve the DataTables object for the given selector. Note that if the table has already been initialised, this parameter will cause DataTables to simply return the object that has already been set up - it will not take account of any changes you might have made to the initialisation object passed to DataTables (setting this parameter to true is an acknowledgement that you understand this). bDestroy can be used to reinitialise a table if you need.
Default: false
Type: boolean
Code example: 
   $(document).ready( function() {
     initTable();
     tableActions();
   } );
   
   function initTable ()
   {
     return $('#example').dataTable( {
       "sScrollY": "200px",
       "bPaginate": false,
       "bRetrieve": true
     } );
   }
   
   function tableActions ()
   {
     var oTable = initTable();
     // perform API operations with oTable 
   }
bScrollAutoCss
Show details

Deprecated Indicate if DataTables should be allowed to set the padding / margin etc for the scrolling header elements or not. Typically you will want this.

Please note that this option has now been deprecated and will be removed in the next version of DataTables. Using CSS with `!important` can be used to achieve the same effect.
Default: true
Type: boolean
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "bScrollAutoCss": false,
       "sScrollY": "200px"
     } );
   } );
bScrollCollapse
Show details

When vertical (y) scrolling is enabled, DataTables will force the height of the table's viewport to the given height at all times (useful for layout). However, this can look odd when filtering data down to a small data set, and the footer is left "floating" further down. This parameter (when enabled) will cause DataTables to collapse the table's viewport down when the result set will fit within the given Y height.
Default: false
Type: boolean
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "sScrollY": "200",
       "bScrollCollapse": true
     } );
   } );
bSortCellsTop
Show details

Allows control over whether DataTables should use the top (true) unique cell that is found for a single column, or the bottom (false - default). This is useful when using complex headers.
Default: false
Type: boolean
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "bSortCellsTop": true
     } );
   } );
iCookieDuration
Show details

Duration of the cookie which is used for storing session information. This value is given in seconds.
Default: 7200 (2 hours)
Type: int
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "iCookieDuration": 60*60*24; // 1 day
     } );
   } )
iDeferLoading
Show details

When enabled DataTables will not make a request to the server for the first page draw - rather it will use the data already on the page (no sorting etc will be applied to it), thus saving on an XHR at load time. iDeferLoading is used to indicate that deferred loading is required, but it is also used to tell DataTables how many records there are in the full table (allowing the information element and pagination to be displayed correctly). In the case where a filtering is applied to the table on initial load, this can be indicated by giving the parameter as an array, where the first element is the number of records available after filtering and the second element is the number of records without filtering (allowing the table information element to be shown correctly).
Default: null
Type: int
Code example: 
   // 57 records available in the table, no filtering applied
   $(document).ready( function() {
     $('#example').dataTable( {
       "bServerSide": true,
       "sAjaxSource": "scripts/server_processing.php",
       "iDeferLoading": 57
     } );
   } );

 
   // 57 records after filtering, 100 without filtering (an initial filter applied)
   $(document).ready( function() {
     $('#example').dataTable( {
       "bServerSide": true,
       "sAjaxSource": "scripts/server_processing.php",
       "iDeferLoading": [ 57, 100 ],
       "oSearch": {
         "sSearch": "my_filter"
       }
     } );
   } );
iDisplayLength
Show details

Number of rows to display on a single page when using pagination. If feature enabled (bLengthChange) then the end user will be able to override this to a custom setting using a pop-up menu.
Default: 10
Type: int
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "iDisplayLength": 50
     } );
   } )
iDisplayStart
Show details

Define the starting point for data display when using DataTables with pagination. Note that this parameter is the number of records, rather than the page number, so if you have 10 records per page and want to start on the third page, it should be "20".
Default: 0
Type: int
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "iDisplayStart": 20
     } );
   } )
iScrollLoadGap
Show details

The scroll gap is the amount of scrolling that is left to go before DataTables will load the next 'page' of data automatically. You typically want a gap which is big enough that the scrolling will be smooth for the user, while not so large that it will load more data than need.
Default: 100
Type: int
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "bScrollInfinite": true,
       "bScrollCollapse": true,
       "sScrollY": "200px",
       "iScrollLoadGap": 50
     } );
   } );
iTabIndex
Show details

By default DataTables allows keyboard navigation of the table (sorting, paging, and filtering) by adding a tabindex attribute to the required elements. This allows you to tab through the controls and press the enter key to activate them. The tabindex is default 0, meaning that the tab follows the flow of the document. You can overrule this using this parameter if you wish. Use a value of -1 to disable built-in keyboard navigation.
Default: 0
Type: int
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "iTabIndex": 1
     } );
   } );
oSearch
Show details

This parameter allows you to define the global filtering state at initialisation time. As an object the "sSearch" parameter must be defined, but all other parameters are optional. When "bRegex" is true, the search string will be treated as a regular expression, when false (default) it will be treated as a straight string. When "bSmart" DataTables will use it's smart filtering methods (to word match at any point in the data), when false this will not be done.
Default:
Type:
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "oSearch": {"sSearch": "Initial search"}
     } );
   } )
sAjaxDataProp
Show details

By default DataTables will look for the property 'aaData' when obtaining data from an Ajax source or for server-side processing - this parameter allows that property to be changed. You can use Javascript dotted object notation to get a data source for multiple levels of nesting.
Default: aaData
Type: string
Code example: 
   // Get data from { "data": [...] }
   $(document).ready( function() {
     var oTable = $('#example').dataTable( {
       "sAjaxSource": "sources/data.txt",
       "sAjaxDataProp": "data"
     } );
   } );
   
 
   // Get data from { "data": { "inner": [...] } }
   $(document).ready( function() {
     var oTable = $('#example').dataTable( {
       "sAjaxSource": "sources/data.txt",
       "sAjaxDataProp": "data.inner"
     } );
   } );
sAjaxSource
Show details

You can instruct DataTables to load data from an external source using this parameter (use aData if you want to pass data in you already have). Simply provide a url a JSON object can be obtained from. This object must include the parameter 'aaData' which is the data source for the table.
Default: null
Type: string
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "sAjaxSource": "http://www.sprymedia.co.uk/dataTables/json.php"
     } );
   } )
sCookiePrefix
Show details

This parameter can be used to override the default prefix that DataTables assigns to a cookie when state saving is enabled.
Default: SpryMedia_DataTables_
Type: string
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "sCookiePrefix": "my_datatable_",
     } );
   } );
sDom
Show details

This initialisation variable allows you to specify exactly where in the DOM you want DataTables to inject the various controls it adds to the page (for example you might want the pagination controls at the top of the table). DIV elements (with or without a custom class) can also be added to aid styling. The follow syntax is used:

  • The following options are allowed:
    • 'l' - Length changing
      • 'f' - Filtering input
    • 't' - The table!
    • 'i' - Information
    • 'p' - Pagination
    • 'r' - pRocessing
  • The following constants are allowed:
    • 'H' - jQueryUI theme "header" classes ('fg-toolbar ui-widget-header ui-corner-tl ui-corner-tr ui-helper-clearfix')
    • 'F' - jQueryUI theme "footer" classes ('fg-toolbar ui-widget-header ui-corner-bl ui-corner-br ui-helper-clearfix')
  • The following syntax is expected:
    • '<' and '>' - div elements
    • '<"class" and '>' - div with a class
    • '<"#id" and '>' - div with an ID
  • Examples:
    • '<"wrapper"flipt>'
    • 'ip>'
Default: lfrtip (when bJQueryUI is false) or <"H"lfr>t<"F"ip> (when bJQueryUI is true)
Type: string
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "sDom": '<"top"i>rt<"bottom"flp><"clear">'
     } );
   } );
sPaginationType
Show details

DataTables features two different built-in pagination interaction methods ('two_button' or 'full_numbers') which present different page controls to the end user. Further methods can be added using the API (see below).
Default: two_button
Type: string
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "sPaginationType": "full_numbers"
     } );
   } )
sScrollXInner
Show details

This property can be used to force a DataTable to use more width than it might otherwise do when x-scrolling is enabled. For example if you have a table which requires to be well spaced, this parameter is useful for "over-sizing" the table, and thus forcing scrolling. This property can by any CSS unit, or a number (in which case it will be treated as a pixel measurement).
Default: blank string - i.e. disabled
Type: string
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "sScrollX": "100%",
       "sScrollXInner": "110%"
     } );
   } );
sServerMethod
Show details

Set the HTTP method that is used to make the Ajax call for server-side processing or Ajax sourced data.
Default: GET
Type: string
Code example: 
   $(document).ready( function() {
     $('#example').dataTable( {
       "bServerSide": true,
       "sAjaxSource": "scripts/post.php",
       "sServerMethod": "POST"
     } );
   } );