Upgrading to DataTables 2 from 1.10+
DataTables 2 is a major release with a lot of changes, enhancements and improvements over the 1.x series. There have also been some items which have been removed or updated and they are highlighted in this document.
It is part of a number of related documents detailing the release of DataTables 2:
Backwards compatibility for a library such as DataTables is very important, so a lot of work has been invested in making sure that as few as possible breaking changes have been made for v2, but there have been some, as detailed below.
Please note that this is not an exhaustive list of all minor changes. For a complete list, please refer to the release notes.
Updated
File name
If you are loading DataTables directly through a script tag, please note that the core DataTables file has changed its name from jquery.dataTables.js to dataTables.js. The DataTables default CSS file has also been updated to be consistent in its naming with the styling integration files and is now called dataTables.dataTables.css:
If you are using the download builder to create a combined file, a download package or using NPM / Yarn, you don't need to worry about this. It will all be handled automatically. Only if you were referencing jquery.dataTables.js would your include need to be updated.
dom property
This property was used in DataTables 1.x to place control and information elements around the table. It was flexible, but also very difficult to use, particularly when used with styling libraries such as Bootstrap, often leading to very long strings that were difficult to manipulate.
DataTables 2 introduces the new layout option to make layout positioning much easier to work with, in a styling independent manner. This new property effectively renders dom redundant as the two cannot be used together. However, dom is one of the most widely used parameters in DataTables, so I didn't want to drop it completely.
dom is still available in DataTables 2 (likely it will be dropped in v3 whenever that happens!), but the default CSS for DataTables has been updated for layout and does not include styling for dom. If you need to continue using dom, you will likely need to add some CSS to position the elements as you need. However, you are strongly encouraged to update to using layout.
Class names
The class names that DataTables uses for the elements it adds to the table have been updated to be more consistent, and to be sane (unlike previous versions!). DataTables 1.x had class names which had accumulated over time, and were a bit of a hodge-podge. They are now a lot more consistent in how they are named. They will start with dt- to indicate they are DataTables specific.
If you have been using custom styling with the old DataTables class names, you will need to update your CSS for the new names.
In addition to the class names being updated, the object structure that DataTables uses to store that class names has been updated to be a lot more manageable. This object structure is used by the various styling integrations for DataTables, and is now also considered to be part of the public API, letting you easily change the class names if needed.
You can find the default class names that DataTables uses here. To customise, access via DataTables.ext.classes.
Deferred rendering
DataTables has long since had the ability to delay the creation of DOM elements for the table body until they are needed for display through its deferRender option. This has significant performance implications, particularly when using Ajax loaded data, since it means DataTables doesn't need to create DOM nodes until they are used for the currently displayed page. For this reason, deferRender's default value has been changed to be enabled (true) in DataTables 2.
This has implications on code that assumes that the table's body nodes have been created. If you perform DOM operations on the table through the API, you may have to update your code to account for this. The v1 behaviour can be restored by adding deferRender: false to your initialisation options for the DataTable.
Ajax loading with an empty string
The ajax option (or ajax.url if used as an object) has been updated to not make a request if supplied as an empty string. Previously it would make the call to the document's URL. If you need that behaviour, use ajax: window.location.pathname.
Explicit label / input
The search and page length menus will now use an explicit label / input|select pair if possible now (i.e. the input is at the start or end of the string). This is done to help improve accessibility, particularly for screen readers which do not always support the previously used implicit pair.
language.search and language.lengthMenu are the strings that control this behaviour. If the input element for either is at the start or end of the string an explicit link will be used. If it is in the middle of the string an implicit link will be used.
As a result, language.lengthMenu's default value has been updated from Show _MENU_ entries to be _MENU_ _ENTRIES_ per page.
Stable ordering
Ordering in DataTables is now 100% deterministic. Previously the order of the rows could depend upon the ordering that had previously been applied to the table (only noticeable if rows had the matching ordering data). The data order is now reset to the originally loaded order before each order operation is applied to address this issue.
Order sequence
When ordering columns by clicking on their header element, in v1 it would simply toggle between ascending and descending ordering for the columns (controllable with the columns.orderSequence option). DataTables 2 introduces a new option to this parameter, an empty string value which represents no ordering. The default has been updated to make use of this and the ordering sequence that is applied when clicking the header cell is now:
- Ascending
- Descending
- No order
It will repeat that sequence indefinitely as the column header is clicked. As before, it can be controlled using the columns.orderSequence option, and if you wish to restore the default DataTables 1.x behaviour you can do so by setting the default:
DataTable.defaults.column.orderSequence = ['asc', 'desc'];
Examples
The examples on this site have all been updated to have the ability to be themed by any of our supported styling libraries. This is made possible through the new layout option, which allows features such as Buttons and SearchPanes to be added without a style specific dom string.
All examples also have the ability to show and run initialisation with or without jQuery (default without), and for themes which support it, enable dark or light mode.
Finally, the examples have all been formatted by Prettier (actually, specifically Prettier More) to provide consistent code styling.
Documentation
The code snippets in the reference documentation have been updated to focus on non-jQuery initialisation. Specifically DataTables is now accessed using the global DataTable object - e.g. previously an example might have been:
$('#myTable').DataTable({
scrollX: true
});
It will now be:
new DataTable('#myTable', {
scrollX: true
});
Both forms will still work! The change is primarily due to the increasing use of ES Modules where the DataTable object is imported without the need to also import jQuery.
Removed
Legacy API
DataTables used to extend the jQuery object that it returned from $().dataTable() with DataTables specific methods such as fnDraw, fnGetData and so on (all of them had the fn prefix). That API became legacy and deprecated when DataTables 1.10 introduced an entirely new chainable API. DataTables 2 removes the legacy API completely. If you were using any of the legacy fn* methods, you will need to update them.
deferLoading option
This option was available in DataTables 1.x to stop DataTables from replacing the content of the HTML table on its initial start up. It was initially added into DataTables to allow search engines to crawl the table's data without needing to execute Javascript. That has long since stopped being an issue since all search engines can execute Javascript to load Ajax data. Since it added significant complexity and indirection to DataTables' code paths, it has been removed.
pagingTag option
This existed in later 1.x releases to help improve accessibility. Initially DataTables used a tags to display the paging buttons, but button is preferred for accessibility. pagingTag was available in 1.x to allow buttons to be used, without changing the default. DataTables 2 takes the opportunity to update the paging buttons to button elements, so this option is no longer relevant.
stripeClasses option
DataTables 1.x would add odd and even classes to every row in the table to allow row stripe styling of the table. This has long since been redundant due to the :nth-child selector of CSS supporting the same ability. This option has been removed and row striping of a table is now done solely by CSS.
escapeRegex option in search options
This property hasn't been documented since 1.10, but did exist for legacy reasons. Use the regex option of the DataTables.SearchOptions object to control if a string should be treated as a regex string or not.
concat() method
This was quite simply broken and wasn't behaving as documented. As a result, I took the decision to remove it since it is unlikely to be getting any use and would have added additional code to DataTables to fix.
error event
The old error event unfortunately triggered the window.onerror DOM0 catch all error action, purely due to its naming. This was undesirable and as such the property has been renamed to dt-error. It is still identical in behaviour, and if you do want window.onerror to be triggered, set DataTable.ext.errMode = 'throw';.