API reference

Exports

The root entry ships the renderer, the engine, the pure helpers it is built from, and the two message sets. The ./core entry contains the pure functions only and imports nothing from Svelte.

Root entry

import { … } from '@svelte-lean/table'

Core entry

import { … } from '@svelte-lean/table/core' — pure functions over the same types; runs under plain Node.

DataTable props

Every capability of the renderer is a prop. The three required props establish the row contract; everything else defaults to off or to the plain table.

Data and identity

The rows, the schema and a stable identity per row.

Controlled state

Bind one serializable object or listen without binding.

Controls

Each control is independent; none is rendered by default.

Expansion

Details rows and tree rows share the expanded id list in the state.

Presentation

Structure and naming stay explicit props; colors and spacing are CSS custom properties.

States

Network ownership stays with the application; the table announces what it is told.

Events and composition

Side effects leave through callbacks; content enters through snippets.

Methods

Exported from the component instance (bind:this).

Column

A column reads a field, a dot path or a computed value, and declares how it sorts, filters, renders and edits. Columns are plain objects; only snippets tie them to a Svelte file.

Data and content

Identity, the value it reads and how the value is rendered.

Layout

Widths and pinning use logical insets, so they work in both directions.

Sort, filter and aggregate

Defaults cover numbers, dates and text; each can be replaced per column.

Editing

The renderer parses and validates; the application commits.

Table state

TableState is one plain, serializable object. Every change passes through setState() and onStateChange; bind:state on the renderer is the same path.

TableState

Fields and their defaultState() values.

Types

Event payloads and model types, all exported from the root entry.

Events and positions

Small typed values suited to stores, query layers and command handlers.

Row model

What createRowModel() and a custom getRowModel exchange.

Messages

Every visible or accessible string of the renderer comes from TableMessages. Pass a partial object to override some of them; en and tr are complete sets. Defaults shown are the en values.

TableMessages

Keys, where each one is used, and the English default.

Engine

createTable() is the engine the renderer is built on. Options are read lazily, so a getter keeps the engine reactive to the caller state; a state getter makes it controlled.

Use the engine when the renderer's markup is not the markup you need: a different table structure, a list, a chart legend, or a test that asserts the model. It is the escape hatch under DataTable and the same code path, so the behavior matches.

<script lang="ts">
	import { createTable, type Column } from '@svelte-lean/table';

	type Member = { id: number; name: string; revenue: number };
	let rows = $state<Member[]>(load());
	const columns: Column<Member>[] = [
		{ id: 'name', header: 'Member' },
		{ id: 'revenue', header: 'Revenue', align: 'end' }
	];

	// Options are read lazily: a getter keeps the engine reactive to $state in the caller.
	// A plain object as state makes the table own it; a state getter makes it controlled.
	const table = createTable({
		data: () => rows,
		columns,
		getRowId: (row) => row.id,
		state: { pageSize: 10 },
		onStateChange: (next) => console.log(next.sorting)
	});
</script>

<!-- A renderer of your own: derived values are getters and update with the state. -->
<table>
	<thead>
		<tr>
			{#each table.visibleColumns as column (column.id)}
				<th aria-sort={table.sortOf(column.id)?.desc ? 'descending' : table.sortOf(column.id) ? 'ascending' : undefined}>
					<button type="button" onclick={() => table.toggleSort(column.id)}>{column.header}</button>
				</th>
			{/each}
		</tr>
	</thead>
	<tbody>
		{#each table.model.rows as node (node.id)}
			<tr>
				{#each table.visibleColumns as column (column.id)}
					<td>{String(valueOf(node.data!, column) ?? '')}</td>
				{/each}
			</tr>
		{/each}
	</tbody>
</table>
<p>Page {table.model.pageIndex + 1} of {table.model.pageCount}</p>

// Controlled: the engine reads the caller's state and stores nothing itself.
let view = $state<Partial<TableState>>({});
const table = createTable({
	data: () => rows,
	columns,
	getRowId: (row) => row.id,
	state: () => view,
	onStateChange: (next) => (view = next)
});

table.setSearch('rhye');       // reports { …view, search: 'rhye', pageIndex: 0 } through onStateChange
table.toggleSelection(1);      // selection helpers respect the selection mode and scope options
table.model.total;             // filtered count, recomputed from the getters

// No Svelte at all: the pure model under plain Node, for tests or a server-side export.
import { createRowModel, defaultState } from '@svelte-lean/table/core';

const model = createRowModel({
	data: rows,
	columns,
	state: defaultState({ sorting: [{ id: 'revenue', desc: true }], pageSize: 0 }),
	getRowId: (row) => row.id
});
model.rows.map((node) => node.data);

TableOptions

A MaybeGetter<V> is a value or a function returning it.

Table

Derived values are getters (reactive under runes); transitions call setState() and report through onStateChange.

Modules

Separate entry points, one subpath each. They are pure functions over the same types, never import the renderer and stay out of a build until imported (proved by the table-basic fixture).

Entry points

Import path, exports and purpose. Sizes are on the overview page and in the size file.

Module sizes

Each entry bundled on its own with esbuild, Svelte's runtime excluded; shared code is counted per entry here and de-duplicated by a consumer's bundler. Read from packages/table/artifacts/size.json.