Frequently Asked Questions

DataTables is a complex piece of software and undoubtedly questions will arise from its use. Some of these questions have already been posed and answered, the most common of which are shown here.

Getting help

Q. I have a question - how can I get help?
A. The best place to get help for DataTables is on this site. There is extensive documentation on DataTables in the manual, reference, examples, these FAQs and in the forum. If you can't find the answer to your question on the site already, please post it in the forum. When posting a question about an existing table, please link to a test case showing the issue, or at the very least use the DataTables debugger to provide information about the table.

Q. I need to get an answer to this question as soon as possible!
A. Post your question in the forum as normal, and then use the support page to purchase a support package for DataTables. Purchasing support ensures you will receive assistance with the problem you are having, and also helps support the DataTables project as a whole.

Q. How quickly can I expect a reply to my forum post?
A. The best way to ensure that you get a reply to your question is to purchase a support option. Posting a test case will also ensure that all the information required for the problem is available. Response times will of course vary, but one will come normally within a day, but it can sometimes take longer. If this is the case please don't be offended!

Most common FAQs

Q. I get an error message stating that an API method is not available
A. Very likely you are using a jQuery object rather than a DataTables API instance. The form $().dataTable() will return a jQuery object, while $().DataTable() returns a DataTables API instance. Please see the API documentation for further information.

Q. My events don't work on the second page
A. When attaching events to cells in a table controlled by DataTables, you need to be careful how it is done. Because DataTables removes nodes from the DOM, events applied with a static event listener might not be able to bind themselves to all nodes in the table. To overcome this, simply use jQuery delegated event listener options, as shown in this example. Additionally, you could use my Visual Event bookmarklet to help debug event issues.

Q. I get a JSON parsing error
A. This is due to incorrect JSON data being passed back from the server. Please refer to this technical note on how to debug and resolve this issue.

Q. "Requested unknown parameter" error
A. When DataTables requests a property that is not present in the data source for the table, you get this error. It can be caused by specifying an incorrect number of columns, missing parameters and colspan / rowspan in the body. Please refer to this technical note on how to debug and resolve this issue.

Q. I get a Javascript error in IE, but not in Firefox, Chrome etc.
A. The majority of the time, this is caused by a 'floating' comma at the end of an array. IE will throw a warning for this, other browsers automatically delete it.

Q. I append a row to the table using DOM/jQuery, but it is removed on redraw.
A. The issue here is that DataTables doesn't know about your manipulation of the DOM structure - i.e. it doesn't know that you've added a new row, and when it does a redraw it will remove the unknown row. To add, edit or delete information from a DataTable you must use the DataTables API (specifically the row.add(), row().data() and row().remove() methods to add, edit and delete rows.

Q. Does DataTables work with platform X / server framework Y
A. DataTables is a Javascript library, so the server-side environment doesn't matter. As long as it can construct valid HTML or JSON DataTables can read via Ajax it will work.

Q. Why doesn't the table update if I modify the HTML?
A. This is similar to the previous question. When you initialise the DataTable, the table's contents are cached for speed optimisations - therefore any changes to the HTML after this won't be reflected in the DataTable. To update the table, use one of the following API methods: cell().data(), cells().data(), row().data() or rows().data(). If you can't avoid updating the HTML directly, you can invalidate the cache for that cell or row with cell().invalidate() and row().invalidate() (or their plural equivalents), or you can destroy the DataTable with destroy() and re-initialise.

Q. How do I sort dates and times?
A. Dates and times come in all sorts of different formats, from computer readable only to locale specific formats. DataTables has built in support for ISO6801 formatted dates and times with auto locale formatting, and support for formatted dates and times through integration with Moment.js and Luxon. The correct method to have DataTables understand your date / time information is dependent upon how the data is loaded and displayed:

Q. How do I keep the table sorted on the third click of a column header?
A. By default DataTables will cycle through ascending ordering, descending ordering and no ordering, repeating as needed. This is controlled with by the columns.orderSequence option. You can selectively disable that for specific columns, but to disable it completely for all tables on the page you can set the default as showing in the columns.orderSequence documentation.

General initialisation

Q. DataTables is running slow. How can I speed it up?
A. There are several ways in which you can speed up DataTables. Often the first thing to do is enable paging (paging) if it has been disabled as this simply reduces the amount of data to be displayed. Its also worth noting that scrolling (scrollX and scrollY) can have a significant impact on draw performance for tables with lots of columns, due to the calculations involved. Beyond that, the method you are using for loading the data will typically have the most significant impact on performance.

Client-side processing - DOM sourced data: ~5'000 rows. Speed options: orderClasses.
Client-side processing - Ajax sourced data (ajax): ~50'000 rows. Speed options: deferRender
Server-side processing (serverSide): millions of rows.

Note that older browsers such as IE6/7 might have lower numbers than those given above. Additionally, if you are using Firefox and using Firebug, turn off Firebug as this can have a negative impact on performance.

Q. My table isn't working!?
A. Have you got a thead and tbody defined as DataTables requires (manual - installation)? Is your HTML valid (W3C validator)? Are you seeing any Javascript errors?

Q. My styles aren't showing up / my table isn't styled.
A. Have you included the demo CSS for DataTables on your page (and got the paths correct!)?

Q. How can I move the table controls?
A. You can move the elements that DataTables puts around the table by using the dom initialisation parameter.

Q. Can I define my columns in Ajax loaded JSON?
A. This is not currently a native feature in DataTables (although it is likely to be added in future). Instead, you would need to load the JSON data using $.ajax and assign the column definition array using the columns option.

Q. How can I show the page length select when using Buttons?
A. This question arises when you use the legacy dom option to insert the Buttons into the page, but the l character in the dom string is removed (which it is in many Buttons examples). You could use the pageLength button to insert a page length button list, or add the l option back into the dom string.

This issue can also occur with the layout option when you make use of the topStart location for something other than the default pageLength. Use another layout location for the feature, pageLength, or an array to have multiple items in the topStart location.

Server-side processing

Q. It's not working... (stuck on Processing)
A. This is usually down to incorrect JSON data being passed back from the server. Please refer to this technical note on how to debug and resolve this issue.

Q. It's still not working...
A. The next most common reason for server-side processing not working is the draw variable not being returned as it was set in the request. DataTables uses draw to keep a draw count, so this is an important parameter. See server-side usage.

Q. Pagination is not enabled, or the information text shows the wrong data set count
A. This is likely to be caused by the incorrect use of recordsFiltered. recordsFiltered is the total number of records in the data set after filtering - not just the data array length (which DataTables can do itself!). So if you have no filtering recordsFiltered should be exactly the same as recordsTotal. See server-side usage.

Q. My events aren't being applied
A. What happens is that for each draw, DataTables will create the required display nodes (TR, TD etc), so old events are lost. You can either use delegated events (preferable) like in this example, or drawCallback to re-add the events on each draw. You can also use Visual Event bookmarklet to help debug event issues.

Q. How can I export the whole table when using serverSide and Buttons.
A. Buttons is a client-side process, so it can only export the data available at the client-side. When server-side processing is enabled, the full data set is not held on the client-side, so only the visible data can be exported. You can either: 1. Use a server-side process to create the files to download (recommended - the download plugin Button might be of some assistance here) or 2. Disable server-side processing.

SearchPanes

Q. SearchPanes won't configure when using it as a button
A. When configuring SearchPanes using a button the configuration for SearchPanes needs to go within the config property of the button, not in the DataTables configuration. This example shows how to do this.

Q. No Panes are being shown
A. When this happens it is probably because the data in your table is too unique. SearchPanes makes use of a searchPanes.threshold which is used to calculate whether to display a pane for a column or not. To force panes to either hide or show, it is best to make use of the columns.searchPanes.show configuration option.

Q. CascadePanes isn't working / CascadePanes is breaking things
A. searchPanes.cascadePanes is by far the most complicated part of SearchPanes. Unfortunately, with that comes a few edge cases that we are currently unable to support. If you find yourself asking this question it is likely that you are doing any/some of the following, which are not supported.

searchPanes.cascadePanes and columns.searchPanes.preSelect - This is not supported because in order for cascade to behave as expected the selections need to be made in the correct order. Currently it is not possible to indicate this with preSelect.
searchPanes.cascadePanes, serverSide and stateSave. While SearchPanes and cascade will still run with all of these enabled, the options displayed to the user on a page reload are very unlikely to be as expected. Again, SearchPanes would need to make the selections in the correct order to do this, and the initial request that is sent to the server simply returns the filtered options, leaving no way to determine what order the selections should have been made in.
searchPanes.cascadePanes and columns.searchPanes.combiner. When using these together you must make sure that the data in your table is appropriate for the selection that you make. cascade was developed with the default or logic in mind, using and logic will work in the majority of cases, but it is possible for unexpected results to occur.
When loading the SearchPanes options over ajax, but using client side processing, neither searchPanes.cascadePanes or searchPanes.viewTotal are supported. This is because the data that was initially provided by the user is likely to become inaccurate very quickly. This in turn leads to unexpected behaviour.

Licensing

Q. DataTables is great! How much is it?
A. DataTables is free, open source software that you can download and use for whatever purpose you wish, on any and as many sites you want. It is free for you to use! DataTables is available under the MIT, with which you must comply (to do this, basically keep the copyright notices in the software).

Q. Really - it's free, even for commercial sites?!
A. Yes! I'm very proud of what has been achieved with DataTables and the fantastic community that has helped it to get to where it is today, and I'm delighted to make it available as open source. Obviously if you benefit from DataTables then any reciprocation is very welcome, be it as a plug-in for DataTables (post your code in the forums), purchasing a supporter package or a blog post saying you enjoy using DataTables.

Q. We can't use MIT licensed software. What do we do?
A. In the rare case that you can't use DataTables under its available license, please get in touch to discuss alternative licensing arrangements.

Development FAQs

Q. This is great software - how can I contribute?

Write about DataTables on your blog and spread the word!
Create plug-ins for DataTables which can be show-cased on this site.
Answer support questions in the forums.
Contribute patches to any bugs you find
Test for bugs!

Q. I have created a plug-in - how can I share it with everyone else?
A. Please send it to me direct, or post it in the forum.

Q. I think I have found a bug - how do I report it?
A. Please post your bug, along with a full test case showing how to recreate the issue in the forum.