@preline/datatable

Datatables

Datatables solutions for massive datasets.

Contents

• Overview
• Installation
• Basic usage
• CSS
• Configuration Options
• JavaScript API
• Events
• Common Patterns
• License

Overview

The Datatables component provides a powerful data table interface with sorting, searching, pagination, and row selection capabilities. It integrates with DataTables.net for advanced table functionality.

Key Features:

• Column sorting
• Search functionality
• Pagination
• Row selection (single and multiple)
• Customizable paging controls
• Integration with DataTables.net
• Programmatic control via JavaScript API
• Event system for table interactions

Installation

To get started, install DataTable plugin via npm, else you can skip this step if you are already using Preline UI as a package.

npm i jquery datatables.net-dt @preline/datatable

CSS

Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

@import "tailwindcss";

/* @preline/datatable */
@source "../node_modules/@preline/datatable/*.js";
@import "./node_modules/@preline/datatable/variants.css";
@import "./node_modules/@preline/datatable/theme.css";

.dt-layout-row:has(.dt-search),
.dt-layout-row:has(.dt-length),
.dt-layout-row:has(.dt-paging) {
  display: none !important;
}

JavaScript

Include the JavaScript that powers the interactive elements near the end of your </body> tag:

<script src="./node_modules/jquery/dist/jquery.min.js"></script>
<script src="./node_modules/datatables.net-dt/js/dataTables.dataTables.min.js"></script>
<script src="./node_modules/@preline/datatable/index.js"></script>

Manual Initialization

Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

<script src="./node_modules/jquery/dist/jquery.min.js"></script>
<script src="./node_modules/datatables.net-dt/js/dataTables.dataTables.min.js"></script>
<script type="module">
  import HSDataTable from "@preline/datatable/non-auto.mjs";

  new HSDataTable(document.querySelector("#datatable"));
</script>

Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module. jQuery and DataTable are referenced as globals, so expose them on window before importing the plugin.

@preline/datatable is the auto-init entry: it scans the DOM and initializes matching elements automatically.

import jQuery from "jquery";
window.jQuery = jQuery;
window.$ = jQuery;
import DataTable from "datatables.net";
window.DataTable = DataTable;

import "@preline/datatable";

@preline/datatable/non-auto is the manual entry: use it when you want explicit control over when initialization happens, either via autoInit() or by creating a specific instance yourself.

import jQuery from "jquery";
window.jQuery = jQuery;
window.$ = jQuery;
import DataTable from "datatables.net";
window.DataTable = DataTable;

import HSDataTable from "@preline/datatable/non-auto";

HSDataTable.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#datatable");
if (el) new HSDataTable(el);

TypeScript

This package ships with TypeScript type definitions. No additional @types/ package is needed.

Basic usage

The following example demonstrates the minimal HTML structure required for a datatable component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The table supports sorting, searching, and pagination.

<div data-hs-datatable>
  <table>
    <thead>
      <tr>
        <th scope="col">
          Name
          <svg class="hidden hs-datatable-ordering-desc:block" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>
          <svg class="hidden hs-datatable-ordering-asc:block" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m18 15-6-6-6 6"/></svg>
        </th>
        <th scope="col">
          Age
          <svg class="hidden hs-datatable-ordering-desc:block" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>
          <svg class="hidden hs-datatable-ordering-asc:block" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m18 15-6-6-6 6"/></svg>
        </th>
        <th scope="col" class="--exclude-from-ordering">
          Action
        </th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>John Brown</td>
        <td>45</td>
        <td>
          <button type="button">Delete</button>
        </td>
      </tr>
    </tbody>
  </table>

  <div style="display: none;" data-hs-datatable-paging>
    <button type="button" data-hs-datatable-paging-prev>
      <span aria-hidden="true">«</span>
      <span class="sr-only">Previous</span>
    </button>
    <div data-hs-datatable-paging-pages></div>
    <button type="button" data-hs-datatable-paging-next>
      <span class="sr-only">Next</span>
      <span aria-hidden="true">»</span>
    </button>
  </div>
</div>

Structure Requirements:

• data-hs-datatable: Required on the container element
• Standard HTML <table> structure with <thead> and <tbody>
• Optional paging controls with data-hs-datatable-paging
• Optional search input with data-hs-datatable-search
• Optional row selection checkboxes

Initial State:

• Table displays all data
• Sorting is enabled on columns (unless excluded)
• Pagination controls are hidden if not needed

CSS

Please add the following CSS to the head. This is necessary because Datatables.net does not allow to add custom markup with options disabled, such as paging: false or searching: false.

<style>
  .dt-layout-row:has(.dt-search),
  .dt-layout-row:has(.dt-length),
  .dt-layout-row:has(.dt-paging) {
    display: none !important;
  }
</style>

Configuration Options

Data Options

Note: Please note that this component requires the use of the Datatables.net plugin. Most options available in the plugin are available in our wrapper.

Data options are specified in the data-hs-datatable attribute as a JSON object.

Example:

<div data-hs-datatable='{
  "pageBtnClasses": "px-3 py-1 border rounded",
  "rowSelectingOptions": {
    "selectAllSelector": "#hs-select-all",
    "individualSelector": ".hs-row-checkbox"
  }
}'>
  <!-- Table structure -->
</div>

Class Options

CSS class modifiers use -- prefix to control datatable behavior.

Required CSS Classes / Data Attributes

These data attributes define the structure and must be present for specific features to function.

Tailwind Modifiers

JavaScript API

The HSDataTable object is available in the global window object after the plugin is loaded.

Instance Methods

These methods are called on a datatable instance.

Static Methods

These methods are called directly on the HSDataTable class.

Usage Examples

Example 1: Accessing DataTables.net instance

// Get the datatable instance
const instance = HSDataTable.getInstance('#hs-datatable', true);

if (instance) {
  const { element } = instance;
  // Access underlying DataTables.net instance
  const { dataTable } = element;

  if (dataTable) {
    // Use DataTables.net methods
    dataTable.search('query').draw();
  }
}

Example 2: Destroying datatable instance

const instance = HSDataTable.getInstance('#hs-datatable', true);

if (instance) {
  const { element } = instance;
  const destroyBtn = document.querySelector('#hs-destroy-btn');

  destroyBtn.addEventListener('click', () => {
    element.destroy();
  });
}

Example 3: Destroying datatable instance

const instance = HSDataTable.getInstance('#hs-datatable', true);

if (instance) {
  const { element } = instance;
  const removeBtn = document.querySelector('#hs-remove-btn');

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('#hs-datatable').remove();
  });
}

Events

Note: Please note that this component requires the use of the Datatables.net plugin. Most events available in the plugin are available in our wrapper.

Datatable instances emit events through the underlying DataTables.net instance. Access the DataTables.net instance via element.dataTable to listen to events.

Common DataTables.net Events:

• draw - When table is redrawn
• order - When column ordering changes
• search - When search is performed
• page - When page changes
• select - When row is selected
• deselect - When row is deselected

Event Usage Example

// Get datatable instance
const instance = HSDataTable.getInstance('#hs-datatable', true);

if (instance) {
  const { element } = instance;
  const { dataTable } = element;

  if (dataTable) {
    // Listen to draw event
    dataTable.on('draw.dt', () => {
      console.log('Table redrawn!');
      // Perform actions after table redraws
      // e.g., update UI, reinitialize plugins
    });

    // Listen to order event
    dataTable.on('order.dt', () => {
      console.log('Column ordering changed!');
    });

    // Listen to search event
    dataTable.on('search.dt', () => {
      console.log('Search performed!');
    });
  }
}

Common Patterns

Pattern 1: With Search

Add search functionality to the datatable.

<input type="text" data-hs-datatable-search placeholder="Search...">

<div data-hs-datatable>
  <!-- Table structure -->
</div>

Pattern 2: With Row Selection

Enable row selection with checkboxes.

<div data-hs-datatable>
  <table>
    <thead>
      <tr>
        <th>
          <input type="checkbox" data-hs-datatable-row-selecting-all>
        </th>
        <!-- Other columns -->
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>
          <input type="checkbox" data-hs-datatable-row-selecting-individual>
        </td>
        <!-- Other cells -->
      </tr>
    </tbody>
  </table>
</div>

Pattern 3: Exclude Column from Ordering

Disable sorting on specific columns.

<th scope="col" class="--exclude-from-ordering">
  Actions
</th>

License

Copyright (c) 2024 Htmlstream.

Licensed under the MIT License.