Dog Table Docs

Vanilla tables with the practical stuff already built in.

Dog Table gives you search, sorting, pagination, remote data loading, grouping, selection, CSV export, inline editing, localization, persistence, and live refresh without bringing in a framework.

Quick start API methods Hooks

1 constructor Create a table with new DogTable(container, options) and call init().

Remote-ready fetch() requests are abortable and react to page, sort, and search state.

Progressive features Selection, export, editing, persistence, and live sync layer on only when enabled.

Installation

Use the package from npm, or load the source files directly in a browser module setup.

npm

npm install dog-table

Package entry points

dog-table - exports dist/data-table.js by default, with dog-table/min for the minified bundle
dog-table/css - exports dist/data-table.css, with dog-table/css/min for minified CSS
dog-table/locale/* - maps to dist/locale/*.js
dog-table/plugin/* - maps to dist/plugin/*.js
dog-table/utils - exports dist/utils/index.js
src/core/ contains internal support modules and is not exported as a package subpath

Quick Start

The basic flow is: load CSS, create a DogTable, pass data and columns, then call init().

Browser modules

<link rel="stylesheet" href="./src/data-table.css" />
<div id="dogs"></div>
<script type="module">
  import { DogTable } from "./src/data-table.js";

  const table = new DogTable("#dogs", {
    data: [
      { id: 1, name: "Mochi", age: 3, status: "ready" },
      { id: 2, name: "Pepper", age: 5, status: "pending" },
    ],
    columns: [
      { key: "name", label: "Name" },
      { key: "age", label: "Age" },
      { key: "status", label: "Status" },
    ],
  });

  table.init();
</script>

Bundlers

import { DogTable } from "dog-table";
import "dog-table/css";

const table = new DogTable("#dogs", {
  data,
  columns: [
    { key: "name", label: "Name" },
    { key: "breed", label: "Breed" },
    { key: "age", label: "Age" },
  ],
});

table.init();

Core Concepts

Local data

Client-side search, sort, and pagination happen automatically when you pass data and columns.

Remote data

Add a remote config to fetch server data. Page, sort, and search state are converted into query params.

Columns

Columns define labels, sort rules, formatting, search behavior, custom rendering, visibility, and editability.

Hooks

Lifecycle hooks expose init, fetch, update, sort, search, paging, row detail, selection, and loading changes.

Grouping and detail

Use groupBy, groupLabel, rowKey, and rowDetail.render() to build grouped tables with expandable rows.

Progressive enhancement

Persistence, CSV export, inline editing, locale switching, and live polling are already wired into the table instance.

Remote Example

const table = new DogTable("#dogs", {
  columns: [
    { key: "name", label: "Name" },
    { key: "age", label: "Age" },
  ],
  remote: {
    url: "/api/dogs",
    queryParams: {
      page: "page",
      pageSize: "limit",
      sort: "sort",
      order: "order",
      search: "q",
    },
    mapResponse(payload) {
      return {
        rows: payload.items,
        totalItems: payload.total,
      };
    },
  },
});

table.init();

Remote requests are abortable. If a newer fetch starts, the previous one is canceled with AbortController.

Table Options

Option	Type	Default	Purpose
`data`	`Array<object>`	`[]`	Raw local rows.
`columns`	`Array<object>`	`[]`	Column definitions used for rendering and behavior.
`pageSize`	`number`	`5`	Rows shown per page.
`paginationGuard`	`boolean \| { maxPage, minPageSize, maxPageSize }`	`false`	Optional guardrails for page/page-size bounds. Use `true` for defaults (25 / 1 / 100).
`searchable`	`boolean`	`true`	Shows or hides the built-in search control.
`searchDebounce`	`number`	`250`	Debounce delay for the search input.
`language`	`object`	built-in labels	Overrides visible UI copy such as search, paging, empty, and loading text.
`initialSort`	`{ key, direction } \| null`	`null`	Initial sort state.
`theme`	`string \| object`	`"default"`	Preset name or custom theme map.
`classNames`	`object`	`{}`	Additional class name overrides merged with the active theme.
`remote`	`object \| null`	`null`	Enables server-driven data loading through `fetch()`.
`groupBy`	`string \| function \| null`	`null`	Groups rows before rendering.
`groupLabel`	`function \| null`	`null`	Builds custom labels for group header rows.
`rowKey`	`string \| function \| null`	`null`	Stable id source for row detail and selection features.
`rowDetail`	`object \| null`	`null`	Enables expandable detail rows.
`persistence`	`"url" \| "local" \| "session" \| null`	`null`	Persists search, paging, sort, and page size state.
`persistenceKey`	`string \| null`	`null`	Custom storage or URL key prefix.
`selectable`	`boolean`	`false`	Adds row selection checkboxes.
`create`	`object \| null`	`null`	Enables built-in creation workflows with modal forms and validation.
`hooks`	`object`	`{}`	Lifecycle callbacks.

Column Definition

Field	Type	Purpose
`key`	`string`	Primary property used for value lookup, sort state, and default filtering.
`label`	`string`	Visible header label.
`accessor`	`string`	Alternate row property used for rendering and editing.
`sortable`	`boolean`	Disable built-in sorting for a column.
`searchable`	`boolean`	Exclude a column from local search matching.
`visible`	`boolean`	Hide a column while keeping it in state.
`editable`	`boolean`	Makes body cells editable through the editor plugin.
`render(value, row)`	`function`	Custom cell rendering. Can return a `Node`, string, or primitive.
`sortValue(value, row)`	`function`	Transforms values before local sorting.
`filter({ value, row, query })`	`function`	Custom local-search matching for the column.
`format` or `type`	`string`	Used by the formatter plugin for built-in display formatting.
`formatOptions`	`object`	Options passed to the formatter logic.
`locale`	`string`	Locale override for formatted output.

API Methods

Method	What it does
`init()`	Builds the table UI, binds events, initializes live mode, and renders the first state.
`loadState()` / `saveState()`	Manually interact with the persistence plugin.
`setPage(pageNumber)`	Changes the active page and updates the table.
`setSearch(query)`	Updates the search term, resets to page 1, and rerenders.
`clearSearch()`	Clears the search input and filter state.
`setPageSize(size)`	Updates page size and resets to page 1.
`setSort(key, direction)`	Applies a specific sort state.
`clearSort()`	Removes active sorting.
`setData(data)`	Replaces local row data and clears error/detail state.
`setColumns(columns)`	Replaces the current columns and rerenders.
`setTheme(theme, classNames)`	Swaps theme mapping and rebuilds the DOM shell.
`setLanguage(language)`	Merges language overrides and rebuilds visible UI text.
`toggleRowDetail(rowId)`	Expands or collapses a detail row.
`expandRowDetail(rowId)` / `collapseRowDetail(rowId)`	Explicit detail row control.
`toggleRowSelection(rowId, isSelected)`	Selects or deselects a row when selection is enabled.
`selectAll(isSelected)`	Selects or clears all rows in the current processed set.
`toggleColumnVisibility(columnKey, isVisible)`	Shows or hides a column.
`getSelectedData()`	Returns selected row objects.
`getState()`	Returns a copy of the current table state.
`setLoading(isLoading)`	Manually updates loading state and triggers `onLoadingChange`.
`exportCSV(filename)`	Exports visible columns from the current raw data to CSV.
`openCreateModal()`	Opens the record creation modal if the feature is enabled.
`reset()`	Clears search, sort, errors, and expanded detail rows.
`destroy()`	Removes event listeners, aborts fetches, stops live mode, and clears the container.

Hooks

Hook	When it fires
`onInit(state)`	After the first `init()` render completes.
`onFetchStart(state)`	Before a remote request begins.
`onFetchSuccess(payload)`	After remote data is mapped successfully.
`onFetchError(error)`	When a remote request fails.
`onDataUpdated(rows)`	After fresh remote rows are stored.
`onLoadingChange(isLoading)`	Whenever loading state changes.
`onPageChange(page)`	When the visible page changes.
`onSortChange({ sortKey, sortDirection })`	When sort state changes.
`onSearchChange(query)`	When the normalized search query changes.
`onRowToggle({ rowId, expanded })`	When a detail row is opened or closed.
`onSelectionChange(selectedRows)`	When row selection changes.
`onUpdate(snapshot)`	After a successful render/update cycle.
`onCreateSuccess(row)`	After a new record is successfully created and added.
`onCreateError(error)`	When a create request fails.

Plugins and Modules

`PersistencePlugin`

Stores search, page, sort, and page size in url, localStorage, or sessionStorage.

`SelectionPlugin`

Tracks selected row ids and exposes getSelectedData(), toggleRow(), and selectAll().

`ExportPlugin`

Exports visible columns to CSV with toCSV(filename).

`FormatterPlugin`

Formats output values before render using column formatting hints.

`EditorPlugin`

Starts inline editing for cells marked editable in column definitions.

`LivePlugin`

Handles auto-refresh timers, visibility pausing, and adaptive backoff for remote tables.

`CreatePlugin`

Manages the built-in record creation workflow, field validation, and modal state.

`DataFetcher`

Builds request URLs from table state, supports query param remapping, and aborts stale requests.

`ThemeManager`

Resolves built-in theme slots and class-name overrides used throughout the rendered UI.

`utils`

Exports escapeHtml(value) and debounce(callback, wait).

Built-in locales currently include en, es, fr, de, zh-CN, and id.

Good Defaults to Know

pageSize defaults to 5 paginationGuard is false by default paginationGuard: true uses maxPage 25 and maxPageSize 100 Search is enabled by default Search input debounce is 250ms Sort direction starts at asc Remote responses expect data and total unless mapped Grouping labels fall back to Ungrouped (count)

Demo Map

Use the demos as working reference implementations for each feature area.

Vanilla tables with the practical stuff already built in.

Installation

npm

Package entry points

Quick Start

Browser modules

Bundlers

Core Concepts

Local data

Remote data

Columns

Hooks

Grouping and detail

Progressive enhancement

Remote Example

Table Options

Column Definition

API Methods

Hooks

Plugins and Modules

PersistencePlugin

SelectionPlugin

ExportPlugin

FormatterPlugin

EditorPlugin

LivePlugin

CreatePlugin

DataFetcher

ThemeManager

utils

Good Defaults to Know

Demo Map

Basic

Custom Cells

Themes

Remote

Grouping + Detail

Localization

Advanced Features

Formatting

Inline Editing

Live Sync

Pagination Guard

Create Record

`PersistencePlugin`

`SelectionPlugin`

`ExportPlugin`

`FormatterPlugin`

`EditorPlugin`

`LivePlugin`

`CreatePlugin`

`DataFetcher`

`ThemeManager`

`utils`