DataTables jQuery UI Integration

2.3.7 · active · verified Wed Apr 22

The `datatables.net-jqui` package provides an integration layer to style DataTables instances using the jQuery UI theming framework. It extends the core DataTables library, allowing developers to leverage existing jQuery UI themes for a consistent look and feel across their applications. The current stable version is 2.3.7, though a 3.0.0-beta.1 release indicates upcoming major changes. This package focuses solely on presentation and requires both the core `datatables.net` library and `jquery-ui` to function correctly. Its release cadence is generally tied to major DataTables and relevant jQuery UI updates. It differentiates itself by offering a specific, highly customizable theming option for DataTables users who are already invested in the jQuery UI ecosystem, ensuring visual harmony with other jQuery UI widgets.

Common errors

```
$(...).DataTable is not a function
```
cause jQuery, DataTables core, or `datatables.net-jqui` is not loaded, or loaded in the wrong order, preventing the `DataTable` method from being attached to the jQuery object.

fix Verify that jQuery, `datatables.net`, and `datatables.net-jqui` scripts are included in the correct order in your HTML or module imports. Ensure jQuery is available globally or correctly imported as `$`.
```
Table appears unstyled or default DataTables styling is present.
```
cause Missing or incorrectly linked CSS files for either the jQuery UI theme or the `datatables.net-jqui` specific styling.

fix Ensure both `jquery-ui.min.css` (or your chosen theme CSS) and `dataTables.jqueryui.min.css` are linked in your HTML `<head>` section, before your JavaScript.
```
Uncaught TypeError: $(...).button is not a function
```
cause A specific jQuery UI widget's JavaScript file (e.g., `button`, `datepicker`) is required but has not been loaded. `datatables.net-jqui` styles DataTables using jQuery UI, but does not bundle all jQuery UI widgets.

fix Include the necessary individual jQuery UI widget scripts if you are using specific jQuery UI features beyond basic theming, e.g., `import 'jquery-ui/ui/widgets/button';`.
```
Uncaught ReferenceError: jQuery is not defined
```
cause The jQuery library has not been loaded or is not accessible in the scope where DataTables is being initialized.

fix Ensure `jquery` is loaded before any other scripts that depend on it. In a module environment, `import $ from 'jquery';` should be at the top of your relevant script file.

Warnings

breaking DataTables v3.0.0-beta.1 has been released, signifying a major overhaul to the core DataTables library. This new version removes jQuery as a direct dependency and shifts to a TypeScript-based, dependency-free architecture. While DataTables v3 can still operate with jQuery, extensions like `datatables.net-jqui` may have their own major version bumps and specific compatibility requirements with DataTables v3 and jQuery UI.
Fix: Refer to the DataTables 3 upgrade notes and `datatables.net-jqui` v3 documentation for specific changes, import paths, and initialization patterns. Be prepared for potential refactoring if migrating from DataTables v2.x.
gotcha Proper styling requires the correct CSS files to be included: a jQuery UI theme CSS (e.g., `jquery-ui.min.css`), and the DataTables jQuery UI integration CSS (`dataTables.jqueryui.min.css`). Without these, the table will appear unstyled or with default DataTables styling.
Fix: Ensure both a jQuery UI theme stylesheet and the `dataTables.jqueryui.min.css` are linked in your HTML, preferably before your main application scripts. Example: `<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/themes/base/jquery-ui.min.css"> <link rel="stylesheet" type="text/css" href="https://cdn.datatables.net/2.0.7/css/dataTables.jqueryui.min.css">`
gotcha The load order of scripts is critical for jQuery plugins. jQuery must be loaded first, followed by jQuery UI's JavaScript (if using specific widgets or core components), then DataTables core, and finally `datatables.net-jqui`. Incorrect order can lead to `$(...).DataTable is not a function` or styling issues.
Fix: Always load scripts in this sequence: jQuery, jQuery UI (if needed), `datatables.net`, `datatables.net-jqui`. For example: `<script src="jquery.js"></script> <script src="jquery-ui.js"></script> <script src="dataTables.js"></script> <script src="dataTables.jqueryui.js"></script>`
gotcha This package has peer dependencies (`jquery`, `datatables.net`, `jquery-ui`) that must be installed and properly configured alongside it. Failing to install them, or installing incompatible versions, will cause runtime errors.
Fix: Ensure `jquery`, `datatables.net`, and `jquery-ui` are explicitly installed and match compatible versions. Check DataTables and jQuery UI documentation for their respective compatibility matrices. For npm: `npm install jquery datatables.net jquery-ui`.

Install

npm install datatables.net-jqui npm
yarn add datatables.net-jqui yarn
pnpm add datatables.net-jqui pnpm

Imports

$
wrong:
```
const $ = require('jquery');
```
correct:
```
import $ from 'jquery';
```
While CommonJS `require` works, ESM `import` is preferred for modern projects. Ensures jQuery is available for DataTables to attach to.
DataTables jQuery UI Plugin
wrong:
```
import { DataTable } from 'datatables.net-jqui';
```
correct:
```
import 'datatables.net-jqui';
```
This package is a jQuery plugin that extends `$.fn.DataTable`. It does not export named symbols for its primary functionality. Importing it triggers the side effect of attaching its logic to jQuery.
DataTable Initialization
wrong:
```
import DataTable from 'datatables.net-jqui'; new DataTable('#myTable');
```
correct:
```
import $ from 'jquery';
import 'datatables.net';
import 'datatables.net-jqui';

$(document).ready(() => {
  $('#myTable').DataTable({
    // DataTables options specific to jQuery UI
    renderer: 'jqueryui'
  });
});
```
Even though `datatables.net-jqui`'s README shows `import DataTable from 'datatables.net-jqui'; new DataTable(...)`, this is generally for DataTables v1.11+ which supports non-jQuery initialization. For jQuery UI integration, the plugin extends the jQuery object, making the `$(...).DataTable()` pattern the most common and robust for JQUI styling. Ensure core `datatables.net` is also imported.

Quickstart

This quickstart demonstrates how to initialize a DataTables instance with jQuery UI styling, including necessary CSS and JavaScript imports via CDN, and a basic HTML table structure.

<!-- Include jQuery, jQuery UI, DataTables core, and DataTables JQUI CSS -->
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/themes/base/jquery-ui.min.css">
<link rel="stylesheet" type="text/css" href="https://cdn.datatables.net/2.0.7/css/dataTables.jqueryui.min.css">

<!-- Your HTML table -->
<table id="myDataTable" class="display" style="width:100%">
  <thead>
    <tr>
      <th>Name</th>
      <th>Position</th>
      <th>Office</th>
      <th>Age</th>
      <th>Start date</th>
      <th>Salary</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Tiger Nixon</td>
      <td>System Architect</td>
      <td>Edinburgh</td>
      <td>61</td>
      <td>2011/04/25</td>
      <td>$320,800</td>
    </tr>
    <tr>
      <td>Garrett Winters</td>
      <td>Accountant</td>
      <td>Tokyo</td>
      <td>63</td>
      <td>2011/07/25</td>
      <td>$170,750</td>
    </tr>
  </tbody>
</table>

<script type="module">
  import $ from 'jquery';
  import 'jquery-ui/ui/widgets/button'; // Example for a common JQUI widget
  import 'datatables.net';
  import 'datatables.net-jqui';

  $(document).ready(function() {
    $('#myDataTable').DataTable({
      // JQUI-specific options can be added here if needed
      // For example, to explicitly enable JQUI renderer (often default if plugin loaded)
      // renderer: 'jqueryui'
    });
  });
</script>

view raw JSON →