# @marmooo/table
A dependency-free HTML `` library. Sorting, per-column filtering,
pagination, column visibility, column resizing, and cell editing are all opt-in
plugins/components that you can combine as needed.
> **Note**: the built-in UI (search inputs, pagination, column selector) uses
> Bootstrap class names (`form-control`, `is-invalid`, `pagination`,
> `page-item`, `page-link`, etc). Everything still works without Bootstrap's CSS
> loaded, but borders and spacing won't look right. If you want a fully custom
> look, override it with the `render` options described below.
## Installation
```
npm install @marmooo/table
```
## Basic usage
```ts
import { Table } from "@marmooo/table";
const table = new Table({
data: [
{ id: 1, name: "Alice", age: 30 },
{ id: 2, name: "Bob", age: 25 },
],
columns: [
{ id: "id", name: "ID" },
{ id: "name", name: "Name" },
{ id: "age", name: "Age" },
],
});
const container = document.querySelector("table")!;
table.render(container);
```
`columns[].id` maps to a key on each row object in `data`. By default, values
are rendered as plain text.
## Plugins
Sorting, resizing, and cell editing are each independent plugins passed via
`plugins`. If you don't pass one, that feature is simply off (e.g. without
`Sortable`, clicking a header does nothing).
```ts
import { Editable, Resizable, Sortable, Table } from "@marmooo/table";
const table = new Table({ data, columns });
const resizable = new Resizable(table);
table.options.plugins = [
new Sortable(table, { resizable }), // pass `resizable` when using both, so a column-border drag isn't mistaken for a sort click
resizable,
new Editable(table),
];
table.render(container);
```
### Sortable
- Sorting is triggered by clicking a header, or by pressing Enter / Space
(headers automatically get `tabindex="0"`).
- The current sort column/order is exposed both via `aria-sort` (`ascending` /
`descending` / `none`) and an arrow icon in the header.
- Sorting itself is non-destructive and lives in `Table`; it never mutates
`options.data` directly.
Per-column control:
```ts
{
id: "actions",
name: "",
sortable: false, // exclude this column from sorting (default: true)
render: (row, td) => { /* buttons, etc. */ },
}
```
```ts
{
id: "createdAt",
name: "Created",
// Ascending-order comparator (same convention as Array.prototype.sort:
// negative if a comes first). Reversal for descending order is handled
// automatically.
compare: (a, b) => (a.createdAt as Date).getTime() - (b.createdAt as Date).getTime(),
}
```
If `compare` isn't provided, columns compare numerically when both values are
`number`, and otherwise fall back to `String()` + `localeCompare`. For values
that don't sort correctly once stringified (`Date`, booleans, etc.), providing
`compare` is recommended.
### Resizable
Drag a column border to resize it. When a column's visibility is toggled via
`toggleColumn()`, widths are automatically reset via `reset()`.
### Editable
Clicking a `tbody` cell makes it `contentEditable`; it exits edit mode on blur.
It doesn't persist the value back into `data` — read it back yourself (e.g. on
`blur`) if you need to.
## Components (`options.components`)
### `pagination`
```ts
new Table({
data,
columns,
components: {
pagination: {
pageSize: 20,
container: document.querySelector("#pagination"),
maxPageButtons: 5, // omit to show every page number
// pass `render` to fully replace the markup (default is a Bootstrap-style nav/ul/li)
},
},
});
```
- Use `table.pagination.goToPage(n)` to change pages and
`table.pagination.getTotalPages()` to get the page count.
### `columnSearch` (per-column filtering)
```ts
components: {
columnSearch: {
placeholder: "Search…",
debounce: 200, // delay (ms) between the input event and applying the filter; default 200
datalist: false, // attach a