Table Structure
Rows
A row is identified, never mutated. Expansion, hierarchy, reordering, events and animation all build on getRowId and leave the data with the application.
Markdown version of this page, for assistants (Markdown for AI)
- Source
- core.ts (prepareRows, flattenRows)
- data-table.svelte
- Tests
- core.test.ts
- data-table.dom.test.ts
- table.test.ts
- table.spec.ts (browser)
- Fixture
- fixtures/table-basic
- Benchmark
- table.bench.spec.ts
On this page
Every feature on this page is keyed by row identity. expanded in the state is a list
of row ids; a tree flattens into nodes with a depth per id; a move is reported as two ids; events
carry the row itself. The renderer keeps no per-row object beyond the row model and no listener per
row: a press on a row grip and the keys on it reach one delegated listener per event type, and click
callbacks resolve the row from the event target.
// A row id is a finite number or a string and stays the same across renders.
getRowId={(row) => row.id}
// Not a position: an index changes when rows are sorted, filtered or moved.
getRowId={(row, index) => index} // wrongThe table never changes the data array. Reordering, adding and removing rows are application
decisions expressed by giving the table a new array, which is also what makes animation, undo and
server round trips possible without hidden state.
Expandable rows
Reveal one details region per record and control which rows may expand.
Amara Okafor | Engineering | Europe | $4,501 |
Jonas Lindqvist | Design | Americas | $12,420 |
Mei Tanaka | Operations | Asia | $20,339 |
Rafael Duarte | Growth | Europe | $28,258 |
Selin Aydın | Engineering | Americas | $36,177 |
Noah Brenner | Design | Asia | $44,096 |
Code
<script lang="ts">
import { DataTable } from '@svelte-lean/table';
import { memberColumns, pick } from '$lib/demo/columns';
import { money, people, type Person } from '$lib/demo/data';
const data = people(6);
const columns = pick(memberColumns(), ['name', 'team', 'region', 'revenue']);
let last = $state('');
</script>
{#snippet details(row: Person)}
<dl class="details">
<div><dt>Email</dt><dd>{row.email}</dd></div>
<div><dt>Revenue</dt><dd>{money.format(row.revenue)}</dd></div>
<div><dt>Joined</dt><dd>{row.joined}</dd></div>
</dl>
{/snippet}
<DataTable
{data}
{columns}
getRowId={(row) => row.id}
rowDetails={details}
rowExpandable={(row) => row.status !== 'Invited'}
expandRowByClick
onExpand={(open, row) => (last = `${row.name} ${open ? 'expanded' : 'collapsed'}`)}
pagination={false}
label="Members: expandable rows"
/>
<p role="status">{last}</p>onExpandreports one row;onExpandedRowsChangethe complete id list.- Details rows are not data rows: arrow-key navigation skips them.
- The snippet's second argument is
{ rowId, index, collapse }; a close button inside the details callscollapse(). expandColumnmoves the toggle into a narrow leading column of its own, after the selection column; rows that cannot expand leave it empty. Without it, the first data column reserves the toggle's width on every row so the text stays aligned.
Nested table in row details
Show the records that belong to a row as a table of their own.
| Details | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Amara Okafor | Engineering | Europe | $4,501 | |||||||||||||||||
| ||||||||||||||||||||
Jonas Lindqvist | Design | Americas | $12,420 | |||||||||||||||||
Mei Tanaka | Operations | Asia | $20,339 | |||||||||||||||||
Rafael Duarte | Growth | Europe | $28,258 | |||||||||||||||||
Selin Aydın | Engineering | Americas | $36,177 | |||||||||||||||||
Code
<script lang="ts">
import { DataTable, type Column, type RowDetailsContext } from '@svelte-lean/table';
import { memberColumns, pick } from '$lib/demo/columns';
import { money, people, type Person } from '$lib/demo/data';
type Invoice = { id: string; month: string; amount: number; paid: boolean };
const data = people(5);
const columns = pick(memberColumns(), ['name', 'team', 'region', 'revenue']);
const invoiceColumns: Column<Invoice>[] = [
{ id: 'id', header: 'Invoice', width: 120 },
{ id: 'month', header: 'Month', width: 120 },
{ id: 'amount', header: 'Amount', align: 'end', width: 120, format: (v) => money.format(Number(v)) },
{ id: 'paid', header: 'Status', width: 110, format: (v) => (v ? 'Paid' : 'Open') }
];
function invoices(member: Person): Invoice[] {
return ['2026-06', '2026-07', '2026-08'].map((month, i) => ({
id: `INV-${member.id}${i + 1}`,
month,
amount: Math.round(member.revenue / (3 + i)),
paid: i < 2 || member.id % 2 === 0
}));
}
</script>
{#snippet details(row: Person, { collapse }: RowDetailsContext)}
<div class="details">
<DataTable
data={invoices(row)}
columns={invoiceColumns}
getRowId={(invoice) => invoice.id}
density="compact"
striped
pagination={false}
label="Invoices of {row.name}"
/>
<button type="button" data-slean="button" data-variant="text" data-color="neutral" data-size="small" onclick={collapse}>
Close invoices
</button>
</div>
{/snippet}
<DataTable
{data}
{columns}
getRowId={(row) => row.id}
rowDetails={details}
expandColumn
rowLabel={(row) => row.name}
state={{ expanded: [1] }}
pagination={false}
label="Members: nested invoices"
/>- The stylesheet reaches a table's rows through child combinators from its own root, and the row
variable
--slean-table-row-bgis reset on every root, so a nested table is styled by its own props only. - Every lookup the renderer makes (a cell to focus, a row to scroll to, the row of a drag or a
key press) starts from its own
tbody, so equal row ids in the two tables do not collide.
Tree data
Render nested records through getSubRows with configurable indentation.
Amara Okafor | Engineering | Europe | $4,501 |
Engineering / Amara Okafor | Engineering | Europe | $4,501 |
Engineering / Jonas Lindqvist | Design | Americas | $12,420 |
Jonas Lindqvist | Design | Americas | $12,420 |
Mei Tanaka | Operations | Asia | $20,339 |
Rafael Duarte | Growth | Europe | $28,258 |
Selin Aydın | Engineering | Americas | $36,177 |
Code
<script lang="ts">
import { DataTable } from '@svelte-lean/table';
import { memberColumns, pick } from '$lib/demo/columns';
import { tree } from '$lib/demo/data';
// Two of the five rows carry a children array; getSubRows returns it.
const data = tree();
const columns = pick(memberColumns(), ['name', 'team', 'region', 'revenue']);
</script>
<DataTable
{data}
{columns}
getRowId={(row) => row.id}
getSubRows={(row) => row.children}
indentSize={22}
state={{ expanded: [1] }}
pagination={false}
label="Members: tree data"
/>- Tree input and
groupBy()are separate row models; combining them throws. - Row reordering is disabled while a tree model is active.
- Depth is capped at one hundred levels to catch cycles.
Row reordering
Move rows through a controlled callback without hidden data mutation.
| Drag to reorder | ||||
|---|---|---|---|---|
Amara Okafor | Engineering | Europe | $4,501 | |
Jonas Lindqvist | Design | Americas | $12,420 | |
Mei Tanaka | Operations | Asia | $20,339 | |
Rafael Duarte | Growth | Europe | $28,258 | |
Selin Aydın | Engineering | Americas | $36,177 | |
Noah Brenner | Design | Asia | $44,096 |
Code
<script lang="ts">
import { DataTable, type RowId } from '@svelte-lean/table';
import { memberColumns, pick } from '$lib/demo/columns';
import { people } from '$lib/demo/data';
let rows = $state(people(6));
const columns = pick(memberColumns(), ['name', 'team', 'region', 'revenue']);
// The table reports a move (a grip dragged, or moved with the arrow keys);
// the application owns the order.
function move(source: RowId, target: RowId) {
const from = rows.findIndex((row) => row.id === source);
const to = rows.findIndex((row) => row.id === target);
if (from < 0 || to < 0) return;
const next = [...rows];
const [moved] = next.splice(from, 1);
next.splice(to, 0, moved!);
rows = next;
}
</script>
<DataTable data={rows} {columns} getRowId={(row) => row.id} onRowMove={move} pagination={false} label="Members: row reordering" />- The leading control columns come in one order: expand, grip (
slean-table-mover), selection. The grip column sticks at the start edge like the others; its width is--slean-table-move-width(36px). - A drag starts after the pointer has moved 3px, so a click on a grip moves nothing. The lifted
row and its open details row move together, opaque and shadowed (
--slean-table-row-lifted-shadow,--slean-table-row-liftedfor its background) and below the sticky header. Escape cancels; every row slides back. - Held near the top or bottom edge of the scrolling container (the height-limited table region, or the nearest scrolling ancestor, or the page), the container scrolls, faster toward the edge; the wheel works during a drag as well.
- On release the table calls
onRowMove, waits for the new rows and lets the row glide from where it was dropped into its new place. A move the application does not make slides back. - Moves stay within the current page. While the rows are sorted, filtered or searched the grips
are hidden and the column stays, so a sort does not shift the columns; a tree (
getSubRows) or a custom row model (grouping, pivot) has no grip column. - Pointer moves write transforms on the row elements and nothing else: no state changes until
the drop, and the listeners of a drag exist only while it lasts. The grip label comes from the
moveRowmessage (Drag to reorder: followed byrowLabelor the id).
Row events
Handle click, double-click, context menu and declarative cell actions.
Actions | |||
|---|---|---|---|
Amara Okafor | Engineering | $4,501 | |
Jonas Lindqvist | Design | $12,420 | |
Mei Tanaka | Operations | $20,339 | |
Rafael Duarte | Growth | $28,258 | |
Selin Aydın | Engineering | $36,177 | |
Noah Brenner | Design | $44,096 |
Code
<script lang="ts">
import { DataTable, type Column } from '@svelte-lean/table';
import { memberColumns, pick } from '$lib/demo/columns';
import { people, type Person } from '$lib/demo/data';
const data = people(6);
const columns: Column<Person>[] = [
...pick(memberColumns(), ['name', 'team', 'revenue']),
{ id: 'actions', header: 'Actions', width: 120, sortable: false, cell: actions }
];
let notice = $state('');
</script>
<!-- Elements carrying data-action are delegated to onAction; other clicks reach onRowClick. -->
{#snippet actions()}
<button type="button" data-slean="button" data-variant="text" data-color="neutral" data-size="small" data-action="archive">
Archive
</button>
{/snippet}
<DataTable
{data}
{columns}
getRowId={(row) => row.id}
onRowClick={(row) => (notice = `Clicked ${row.name}`)}
onRowDoubleClick={(row) => (notice = `Double-clicked ${row.name}`)}
onRowContextMenu={(row, event) => {
event.preventDefault();
notice = `Context menu on ${row.name}`;
}}
onAction={(action, row) => (notice = `${action}: ${row.name}`)}
pagination={false}
label="Members: row events"
/>
<p role="status">{notice}</p>- Clicks on
button,a,input,select,textarea,label,summary, an element withcontenteditable,role="menuitem"ordata-action, and anything inside an element markeddata-no-row-click(a copy-to-clipboard span, a tooltip trigger) are not row clicks. - With
onRowClick, rows gettabindex="0", a focus ring, and answer Enter and Space when the row itself has focus. A table with cell navigation (onEdit,onCellRangeChange) keeps its single Tab stop in the cells instead. - The context-menu callback receives the native event; the table does not prevent the default.
- A right-click menu is the menu primitive's context-menu trigger:
data-slean-contextmenu="<menu id>"on a focusable element inside the cell opens the menu at the pointer (Menu).
Row animation
Animate application-owned row insertion and removal while respecting reduced motion.
Amara Okafor | Engineering | Europe | $4,501 |
Jonas Lindqvist | Design | Americas | $12,420 |
Mei Tanaka | Operations | Asia | $20,339 |
Rafael Duarte | Growth | Europe | $28,258 |
Code
<script lang="ts">
import { DataTable, type RowId } from '@svelte-lean/table';
import { memberColumns, pick } from '$lib/demo/columns';
import { people } from '$lib/demo/data';
let rows = $state(people(4));
const columns = pick(memberColumns(), ['name', 'team', 'region', 'revenue']);
let entering = $state<RowId | null>(null);
let leaving = $state<RowId | null>(null);
function add() {
const id = Math.max(0, ...rows.map((row) => row.id)) + 1;
entering = id;
rows = [{ ...people(1)[0]!, id, name: `New member ${id}` }, ...rows];
setTimeout(() => (entering = null), 350);
}
function remove() {
const first = rows[0];
if (!first) return;
leaving = first.id;
setTimeout(() => {
rows = rows.filter((row) => row.id !== first.id);
leaving = null;
}, 220);
}
</script>
<button type="button" data-slean="button" data-variant="outlined" data-color="neutral" onclick={add}>Add row</button>
<button type="button" data-slean="button" data-variant="outlined" data-color="neutral" onclick={remove}>Remove first</button>
<DataTable
data={rows}
{columns}
getRowId={(row) => row.id}
rowClass={(row) => (row.id === entering ? 'enter' : row.id === leaving ? 'leave' : '')}
pagination={false}
label="Members: row animation"
/>
<style>
/* The table adds the class; the application owns the motion and its reduced-motion rule. */
:global(tr.enter td) { animation: enter 300ms var(--ease); }
:global(tr.leave td) { animation: leave 200ms var(--ease) forwards; }
@keyframes enter { from { opacity: 0; background: var(--highlight); } }
@keyframes leave { to { opacity: 0; } }
@media (prefers-reduced-motion: reduce) {
:global(tr.enter td), :global(tr.leave td) { animation: none; }
}
</style>API
| Name | Of | Type | Default | Description |
|---|---|---|---|---|
getRowId | Data and identity | (row: T) => RowId | – | Returns a finite number or a string that stays stable across renders; selection, expansion, pinning and edits are keyed by it. Duplicates throw. |
rowDetails | Expansion | Snippet<[T, RowDetailsContext]> | undefined | Renders a full-width details row under an expanded row. The second argument carries rowId, index and collapse(). A DataTable inside it keeps its own styles and keyboard behavior. |
rowExpandable | Expansion | (row: T) => boolean | () => true | Whether a row may show details. |
expandColumn | Expansion | boolean | false | Renders the expand toggle in its own narrow leading column (after selection) instead of the first data column. |
rowLabel | Controls | (row: T) => string | the row id | Accessible name of a row in its selection, expand and move controls. |
RowDetailsContext | Row model | { rowId: RowId; index: number; collapse: () => void } | – | Second argument of the rowDetails snippet. |
expandRowByClick | Expansion | boolean | false | Toggles expansion when a non-interactive part of a cell is clicked. |
onExpand | Expansion | (expanded: boolean, row: T) => void | undefined | Runs when a data row is expanded or collapsed. |
onExpandedRowsChange | Expansion | (rows: RowId[]) => void | undefined | Runs with the complete next expanded id list, group rows included. |
getSubRows | Data and identity | (row: T) => readonly T[] | undefined | undefined | Child rows for tree tables. Not combinable with groupBy(). |
indentSize | Expansion | number | 18 | Pixels added to the first cell per tree depth. |
onRowMove | Events and composition | (source: RowId, target: RowId) => void | undefined | Adds a leading grip column. A grip is dragged live (the row follows the pointer, the others slide aside, the container scrolls near its edges, Escape cancels) or moved with ArrowUp, ArrowDown, Home and End. Moves stay within the page; the grips are hidden while sorted, filtered or searched, and there is no grip column with a tree or a custom row model. |
onRowClick | Events and composition | (row: T, event: MouseEvent | KeyboardEvent, index: number) => void | undefined | Runs for clicks outside controls (button, a, input, select, textarea, label, summary, contenteditable, menuitem, [data-action], [data-no-row-click]). Rows become Tab stops answering Enter and Space unless the table has cell navigation. |
onRowDoubleClick | Events and composition | (row: T, event: MouseEvent) => void | undefined | Runs on a row double-click. |
onRowContextMenu | Events and composition | (row: T, event: MouseEvent) => void | undefined | Runs on the contextmenu event of a row; the table does not prevent the default. |
onAction | Events and composition | (action: string, row: T, trigger: HTMLElement, index: number) => void | undefined | Delegated click on any element inside a cell that carries data-action. |
rowClass | Events and composition | (row: T, index: number) => string | undefined | Class of a row, for application state or animation. A class that sets --slean-table-row-bg tints every cell of the row, pinned cells included. |
expanded | TableState | RowId[] | [] | Expanded details, tree and group row ids. |
moveRow | TableMessages | string | 'Drag to reorder' | Hidden header text of the grip column, and prefix of each grip label (followed by the row name). |