Keenthemes Ktui Ktui

KTDataTable — AI Agent Reference

Full reference for the DataTable component in KtUI. Package: @keenthemes/ktui. Class: KTDataTable. Root attribute: data-kt-datatable.

Always prefer ktui.io/docs/datatable docs and examples over guessing markup or options.

1. Basic Usage

<div data-kt-datatable="true">
  <table>
    <thead>
      <tr>
        <th data-kt-datatable-column="name">Name</th>
        <th data-kt-datatable-column="email">Email</th>
      </tr>
    </thead>
    <tbody></tbody>
  </table>
</div>

import { KTDataTable } from '@keenthemes/ktui';

const dt = KTDataTable.getInstance(tableEl);

2. Config Options

3. Programmatic API

const dt = KTDataTable.getInstance(tableEl);

dt.sort('name');
dt.sort('name', 'desc');           // explicit sort order
dt.goPage(2);
dt.setPageSize(25);
dt.search('query');
dt.setFilter({ column: 'status', type: 'text', value: 'active' });
dt.reload();        // re-fetch from API
dt.redraw();        // re-render current data
dt.getState();      // { page, sortField, sortOrder, pageSize, ... }
dt.check(value);    // check a row by value
dt.uncheck(value);  // uncheck a row by value
dt.getChecked();    // get array of checked row values
dt.dispose();

Instance management

4. Column Config

columns: {
  name: {
    title: 'Full Name',
    render: (item, data, ctx) => `<strong>${item}</strong>`,
    sortType: 'string', // or 'numeric'
    sortValue: (cellValue, rowData) => rowData.firstName + ' ' + rowData.lastName,
    createdCell: (cell, cellData, rowData, row) => {
      cell.classList.add('text-primary');
    },
  },
  actions: {
    checkbox: true,
  },
}

5. Remote Data Provider

Response shape

interface KTDataTableResponseDataInterface {
  data: KTDataTableDataInterface[];
  totalCount: number;
}

Config

{
  apiEndpoint: 'https://api.example.com/users',
  requestMethod: 'POST',
  requestHeaders: { 'Authorization': 'Bearer ...' },
  mapResponse: (response) => ({ data: response.items, totalCount: response.total }),
  mapRequest: (params) => ({ ...params, page: params.page + 1 }),
}

6. Fixed Column Widths

Use tableLayout: 'fixed' with <colgroup> for consistent column widths across pages:

<table data-kt-datatable-table="true" style="table-layout: fixed; width: 100%;">
  <colgroup>
    <col style="width: 40px">    <!-- checkbox -->
    <col style="width: 70px">    <!-- ID -->
    <col>                         <!-- Name (auto-fill) -->
    <col style="width: 120px">   <!-- Status -->
  </colgroup>
</table>

7. Column Filters

Client-side filtering with setFilter():

dt.setFilter({ column: 'status', type: 'text', value: 'active' });
dt.setFilter({ column: 'price', type: 'numeric', value: { min: 10, max: 100 } });

Filter pipeline runs between search and sort.

8. Empty State

Default: When data.length === 0, renders a single row with infoEmpty text (default: "No records found"). Supports HTML.

Custom via data attribute:

<div data-kt-datatable="true"
     data-kt-datatable-info-empty='<div class="py-10 text-center">No records found</div>'>

Pitfall — never hardcode empty state HTML in <tbody>: The DataTable reads tbody rows as "data" on init. Hardcoded content gets treated as 1 row and disappears on re-render. Always use data-kt-datatable-info-empty or the JS infoEmpty config.

9. Event System

All events dispatch through dual channel:

1. Internal callbacks (.on()) — bare name
2. DOM CustomEvents (addEventListener) — namespaced as kt.datatable.<event>

// Internal callback
dt.on('sort', (payload) => { console.log(payload.field); });

// DOM CustomEvent
el.addEventListener('kt.datatable.sort', (e) => {
  console.log(e.detail.payload.field);
});

10. Architecture

Source: src/components/datatable/

Lifecycle (Critical)

Every data update follows this sequence:

_updateData()
  ├── fetchSync() or fetch()     ← reads from DOM or API
  ├── _draw()
  │     ├── _cleanupForRedraw()  ← cleans listeners + DOM artifacts (NOT registry)
  │     ├── _updateTable()       ← re-renders tbody rows
  │     ├── _updatePagination()  ← re-renders pagination buttons
  │     ├── afterDraw layoutPlugin hook
  │     └── _saveState()         ← persists to localStorage
  ├── _finalize()
  │     ├── _checkbox.init()     ← re-queries DOM, calls reapplyCheckedStates()
  │     ├── _sortHandler.initSort()
  │     ├── searchHandler.attach()
  │     ├── KTComponents.init()
  │     ├── spinner.hide()
  │     └── update _contentChecksum  ← MUST be last (after DOM modifications)
  └── emit 'update'

ORDER MATTERS. _finalize() modifies the DOM. Any checksum saved before _finalize() will be stale.

11. Pitfalls

12. Build & Testing

cd ~/Sites/keenthemes/ktui/ktui
npx vitest run src/components/datatable    # all pass
npx tsc --noEmit                           # typecheck
npm run build:webpack                      # full bundle
npm run build:lib                          # ESM + CJS library builds

Do NOT edit lib/esm/ or lib/cjs/ directly — they're generated from npm run build:lib.

13. Documentation

• DataTable docs: ktui.io/docs/datatable
• Changelog: ktui.io/docs/changelog

Source: keenthemes/ktui — distributed by TomeVault.