DataTable

Installation

The DataTable is a standalone module — it carries no chart dependencies and can be used on its own. Import the class and point it at a container element and a data array.

import { DataTable } from 'katucharts.js/datatable';

const table = new DataTable('#grid', { data: rows });

Quick start

Pass your rows as data and describe each column. With no columns supplied, the grid infers them from the first row.

const rows = [
  { id: 'm5gr84i9', amount: 316, status: 'success',    email: '[email protected]' },
  { id: '3u1reuv4', amount: 242, status: 'success',    email: '[email protected]' },
  { id: 'derv1ws0', amount: 837, status: 'processing', email: '[email protected]' },
];

new DataTable('#grid', {
  data: rows,
  columns: [
    { accessorKey: 'status', header: 'Status' },
    { accessorKey: 'email',  header: 'Email' },
    { accessorKey: 'amount', header: 'Amount', type: 'number' },
  ],
  pagination: { pageSize: 10 },
  filtering: { enabled: true },
});

Columns

Each column is an object. Use accessorKey, header, cell, enableSorting and related properties — or KatuCharts' own field, title and formatter names, which are accepted as equivalents.

Cell & header rendering

Show anything you like in a cell or header. A column's cell function renders its content — return text, an HTML string or a DOM node — and a header function builds custom header markup, like a sortable button.

const usd = (n) => new Intl.NumberFormat('en-US',
  { style: 'currency', currency: 'USD' }).format(n);

columns: [
  // function header with a sort button
  {
    accessorKey: 'email',
    header: ({ column }) => {
      const b = document.createElement('button');
      b.textContent = 'Email';
      b.onclick = () => column.toggleSorting();
      return b;
    },
  },
  // cell returning markup
  {
    accessorKey: 'amount',
    header: () => '<div style="text-align:right">Amount</div>',
    cell: ({ row }) =>
      `<div style="text-align:right">${usd(row.getValue('amount'))}</div>`,
  },
  // an action / checkbox column has no accessorKey — give it an id
  { id: 'actions', cell: ({ row }) => renderMenu(row.original) },
]

Each callback receives row, column and table values you can use to read data and drive the grid:

Sorting

Sorting is on by default; click a header to cycle ascending → descending → unsorted. Disable it globally, enable multi-column sort, or set an initial sort.

new DataTable('#grid', {
  data: rows,
  sorting: {
    enabled: true,
    multiSort: true,
    defaultSort: [{ column: 'amount', direction: 'desc' }],
  },
});

// or set an initial state
new DataTable('#grid', {
  data: rows,
  initialState: { sorting: [{ id: 'amount', desc: true }] },
});

Filtering

The grid offers a global search box plus a per-column filter row. Both can be switched on or off independently, and every column picks (or infers) one of several filter types.

Turn the whole filter row off with filtering.enabled = false, or hide a single column's filter with filterable: false (enableColumnFilter: false). A Reset filters button appears automatically while any filter is active.

Enable the global search box in the toolbar; it matches across all visible columns (or a chosen subset).

new DataTable('#grid', {
  data: rows,
  search: { enabled: true, placeholder: 'Search…' },
  filtering: { enabled: true },          // per-column filter row
  columns: [
    { accessorKey: 'email', header: 'Email' },                        // text filter
    { accessorKey: 'status', header: 'Status', filterType: 'faceted' },
    { accessorKey: 'amount', header: 'Amount', type: 'number',
      filterType: 'numberrange' },
    { accessorKey: 'id', header: 'ID', filterable: false },           // no filter
  ],
});

Pagination

Pagination is on by default. Configure the page size, the offered sizes, and which controls render.

Row selection

Enable single or multi-row selection, with optional checkboxes and a header select-all.

const table = new DataTable('#grid', {
  data: rows,
  selection: { mode: 'multi', checkbox: true },
});

table.on('selection:change', ({ selected }) => {
  // do something with the selected rows
});

Column management

Beyond rendering, columns can be hidden, pinned, resized and reordered. Resizing is on by default; the others are opt-in.

• A Columns toolbar menu toggles each column on or off (respects enableHiding). Hide the button with columnVisibility.enabled = false.
• Pin columns left or right with pinned on the column, or columnPinning.enabled = true plus the pinColumn() method.
• Drag the right edge of a header to resize. Disable with columnResizing.enabled = false.
• Enable drag-to-reorder with columnReordering.enabled = true.

Theming & CSS

The whole visual layer is driven by --kdt-* CSS custom properties on a single class, so you can re-theme by setting one variable — no !important needed. Every part also carries a stable class name you can target directly.

Set any of these on .katucharts-datatable (or a wrapper) to retheme. The grid ships sensible light defaults and a built-in dark palette.

/* Re-theme by setting variables on a wrapper — no !important */
.my-grid .katucharts-datatable {
  --kdt-primary: #b43417;
  --kdt-radius: ;
  --kdt-accent: #fbeae5;
}

Theming & CSS · classNames

Prefer attaching your own classes? Pass a classNames object to hook any part — root, toolbar, table, header, row, cell, footer and pagination.

new DataTable('#grid', {
  data: rows,
  classNames: { root: 'my-grid', row: 'my-row', cell: 'my-cell' },
  style: { theme: 'dark', density: 'compact', radius: 12 },
});

density: 'compact' | 'normal' | 'comfortable' adjusts row height and padding. A 'Density' toolbar item lets users switch it live.

Flip the whole grid to dark with style.theme = 'dark' (or set data-theme="dark" on the root).

Events

Subscribe through the events option (or the .on(name, handler) method) to react to user interaction.

Localization

Built-in UI strings — search and filter placeholders, pagination, the export and density menus, column controls — ship in several languages. You can pick a language explicitly, let the grid follow the browser, or override individual strings.

By default the grid auto-detects the language from the browser and falls back to English when there's no match. Set locale to pin a language; once set it never changes on its own.

// Auto-detect from the browser language (default)
new DataTable('#grid', { data: rows });

// Pin a locale — stays fixed regardless of the browser
new DataTable('#grid', { data: rows, locale: 'pt-BR' });

Locales included out of the box:

Overriding individual strings

Pass lang to override any string for the active locale. Per-key overrides always win over the locale pack, so you can pin a locale and still customize a label or two.

new DataTable('#grid', {
  data: rows,
  locale: 'pt-BR',
  lang: { search: 'Procurar produtos…' },   // wins over the locale pack
});

Switch language at runtime with setLocale — the grid re-renders and keeps any lang overrides.

const table = new DataTable('#grid', { data: rows });
table.setLocale('es');   // switch language and redraw

Add your own language with registerLocale before creating the grid; omitted strings fall back to English.

import { DataTable, registerLocale } from 'katucharts.js/datatable';

registerLocale('fr', { search: 'Rechercher…', noData: 'Aucune donnée' });
new DataTable('#grid', { data: rows, locale: 'fr' });

Options reference

Top-level options passed to new DataTable(container, options). Feature blocks are objects so you can enable and configure each in one place.

Programmatic API

The instance exposes methods to drive the grid from your own code.