# Table

Page: /docs/components/table

{/* Figma: Meridian → Table (docs 44:1849, component set 23:10417). Spec: docs/design-system/meridian/table.md */}

Rows of records people scan, compare and open: a toolbar, an optional summary, a header, rows and pagination, in a card or flat on the page. On the site it appears in product shots and in comparison tables on product and pricing pages.

```tsx
"use client";

import { Table, TableCell, type TableColumn } from "@commenda/meridian/ui/table";
import { DEFlag, GBFlag, NLFlag, SGFlag, USFlag } from "@commenda/pathfinder/flags";
import { type ReactElement, useState } from "react";

const noop = () => {};

type Filing = {
	id: string;
	title: string;
	meta: string;
	entity: string;
	flag: ReactElement;
	person: string;
	status: { label: string; tone: "error" | "success" | "warning" | "info" | "neutral" };
	due: string;
};

const FILINGS: Filing[] = [
	{
		id: "1",
		title: "Delaware annual report",
		meta: "Annual · Delaware",
		entity: "Acme Inc.",
		flag: <USFlag size={16} />,
		person: "Priya Singh",
		status: { label: "Overdue", tone: "error" },
		due: "1 Oct 2026",
	},
	{
		id: "2",
		title: "VAT return Q3",
		meta: "Monthly · Federal Central Tax Office",
		entity: "Acme GmbH",
		flag: <DEFlag size={16} />,
		person: "Lucas Moreau",
		status: { label: "Filed", tone: "success" },
		due: "7 Nov 2026",
	},
	{
		id: "3",
		title: "Confirmation statement",
		meta: "Annual · Companies House",
		entity: "Acme UK Ltd",
		flag: <GBFlag size={16} />,
		person: "Aisha Khan",
		status: { label: "Due soon", tone: "warning" },
		due: "14 Nov 2026",
	},
	{
		id: "4",
		title: "GST return",
		meta: "Quarterly · IRAS",
		entity: "Acme Pte. Ltd.",
		flag: <SGFlag size={16} />,
		person: "Jun Tan",
		status: { label: "In review", tone: "info" },
		due: "30 Nov 2026",
	},
	{
		id: "5",
		title: "Annual accounts",
		meta: "Annual · KVK",
		entity: "Acme B.V.",
		flag: <NLFlag size={16} />,
		person: "Mira de Vries",
		status: { label: "Not started", tone: "neutral" },
		due: "31 Jan 2027",
	},
];

const COLUMNS: TableColumn<Filing>[] = [
	{
		id: "filing",
		header: "Filing",
		width: 230,
		value: (r) => r.title,
		cell: (r) => <TableCell value={r.title} description={r.meta} />,
	},
	{
		id: "entity",
		header: "Entity",
		width: 160,
		value: (r) => r.entity,
		cell: (r) => <TableCell type="entity" label={r.entity} icon={r.flag} />,
	},
	{
		id: "assignee",
		header: "Assignee",
		width: 150,
		value: (r) => r.person,
		cell: (r) => <TableCell type="person" identity={{ kind: "person", name: r.person }} />,
	},
	{
		id: "status",
		header: "Status",
		width: 110,
		value: (r) => r.status.label,
		cell: (r) => <TableCell type="badge" items={[r.status]} />,
	},
	{ id: "due", header: "Due", width: 110, value: (r) => r.due, sortable: true },
];

const ROW = { getId: (r: Filing) => r.id, getLabel: (r: Filing) => r.title };

export function TableContainers() {
	const [container, setContainer] = useState<"card" | "flat">("card");
	return (
		<div className="not-prose my-4 rounded-xl border border-fd-border bg-(--color-surface-page) p-6">
			<div className="mb-4 flex gap-2 text-[13px]">
				{(["card", "flat"] as const).map((c) => (
					<button
						key={c}
						type="button"
						onClick={() => setContainer(c)}
						className={`rounded-md px-3 py-1 ${container === c ? "bg-white shadow-sm" : "text-fd-muted-foreground"}`}
					>
						{c === "card" ? "Card" : "Flat"}
					</button>
				))}
			</div>
			<Table
				label="Filings"
				rows={FILINGS}
				columns={COLUMNS}
				rowConfig={{
					...ROW,
					menu: () => ({
						groups: [
							{
								id: "row",
								items: [{ id: "open", type: "action", label: "Open filing", onClick: noop }],
							},
						],
					}),
				}}
				container={container}
				searchConfig={{ placeholder: "Search filings" }}
			/>
		</div>
	);
}
```

## Usage [#usage]

```tsx
import { Table, TableCell } from "@commenda/meridian/ui/table";

<Table
  label="Filings"
  rows={filings}
  rowConfig={{ getId: (r) => r.id, getLabel: (r) => r.title }}
  columns={[
    { id: "filing", header: "Filing", value: (r) => r.title },
    { id: "entity", header: "Entity", cell: (r) => <TableCell type="entity" label={r.entity} icon={r.flag} /> },
  ]}
/>;
```

## Containers [#containers]

Card by default: white, radius 12, a 0.5 hairline, holding the toolbar, header, rows and pagination. Flat sits straight on the page when the page already frames it. Switch between them below; sort by Due, search, or open a row’s menu.

```tsx
"use client";

import { Table, TableCell, type TableColumn } from "@commenda/meridian/ui/table";
import { DEFlag, GBFlag, NLFlag, SGFlag, USFlag } from "@commenda/pathfinder/flags";
import { type ReactElement, useState } from "react";

const noop = () => {};

type Filing = {
	id: string;
	title: string;
	meta: string;
	entity: string;
	flag: ReactElement;
	person: string;
	status: { label: string; tone: "error" | "success" | "warning" | "info" | "neutral" };
	due: string;
};

const FILINGS: Filing[] = [
	{
		id: "1",
		title: "Delaware annual report",
		meta: "Annual · Delaware",
		entity: "Acme Inc.",
		flag: <USFlag size={16} />,
		person: "Priya Singh",
		status: { label: "Overdue", tone: "error" },
		due: "1 Oct 2026",
	},
	{
		id: "2",
		title: "VAT return Q3",
		meta: "Monthly · Federal Central Tax Office",
		entity: "Acme GmbH",
		flag: <DEFlag size={16} />,
		person: "Lucas Moreau",
		status: { label: "Filed", tone: "success" },
		due: "7 Nov 2026",
	},
	{
		id: "3",
		title: "Confirmation statement",
		meta: "Annual · Companies House",
		entity: "Acme UK Ltd",
		flag: <GBFlag size={16} />,
		person: "Aisha Khan",
		status: { label: "Due soon", tone: "warning" },
		due: "14 Nov 2026",
	},
	{
		id: "4",
		title: "GST return",
		meta: "Quarterly · IRAS",
		entity: "Acme Pte. Ltd.",
		flag: <SGFlag size={16} />,
		person: "Jun Tan",
		status: { label: "In review", tone: "info" },
		due: "30 Nov 2026",
	},
	{
		id: "5",
		title: "Annual accounts",
		meta: "Annual · KVK",
		entity: "Acme B.V.",
		flag: <NLFlag size={16} />,
		person: "Mira de Vries",
		status: { label: "Not started", tone: "neutral" },
		due: "31 Jan 2027",
	},
];

const COLUMNS: TableColumn<Filing>[] = [
	{
		id: "filing",
		header: "Filing",
		width: 230,
		value: (r) => r.title,
		cell: (r) => <TableCell value={r.title} description={r.meta} />,
	},
	{
		id: "entity",
		header: "Entity",
		width: 160,
		value: (r) => r.entity,
		cell: (r) => <TableCell type="entity" label={r.entity} icon={r.flag} />,
	},
	{
		id: "assignee",
		header: "Assignee",
		width: 150,
		value: (r) => r.person,
		cell: (r) => <TableCell type="person" identity={{ kind: "person", name: r.person }} />,
	},
	{
		id: "status",
		header: "Status",
		width: 110,
		value: (r) => r.status.label,
		cell: (r) => <TableCell type="badge" items={[r.status]} />,
	},
	{ id: "due", header: "Due", width: 110, value: (r) => r.due, sortable: true },
];

const ROW = { getId: (r: Filing) => r.id, getLabel: (r: Filing) => r.title };

export function TableContainers() {
	const [container, setContainer] = useState<"card" | "flat">("card");
	return (
		<div className="not-prose my-4 rounded-xl border border-fd-border bg-(--color-surface-page) p-6">
			<div className="mb-4 flex gap-2 text-[13px]">
				{(["card", "flat"] as const).map((c) => (
					<button
						key={c}
						type="button"
						onClick={() => setContainer(c)}
						className={`rounded-md px-3 py-1 ${container === c ? "bg-white shadow-sm" : "text-fd-muted-foreground"}`}
					>
						{c === "card" ? "Card" : "Flat"}
					</button>
				))}
			</div>
			<Table
				label="Filings"
				rows={FILINGS}
				columns={COLUMNS}
				rowConfig={{
					...ROW,
					menu: () => ({
						groups: [
							{
								id: "row",
								items: [{ id: "open", type: "action", label: "Open filing", onClick: noop }],
							},
						],
					}),
				}}
				container={container}
				searchConfig={{ placeholder: "Search filings" }}
			/>
		</div>
	);
}
```

## Density [#density]

Compact 40 is the default; relaxed 52 gives dense data room. A row with a second line grows to 52 (64 relaxed) and its other cells stretch to match. Header 36 at both.

```tsx
import { Table, TableCell, type TableColumn } from "@commenda/meridian/ui/table";
import { DEFlag, GBFlag, NLFlag, SGFlag, USFlag } from "@commenda/pathfinder/flags";
import { type ReactElement } from "react";

const noop = () => {};

type Filing = {
	id: string;
	title: string;
	meta: string;
	entity: string;
	flag: ReactElement;
	person: string;
	status: { label: string; tone: "error" | "success" | "warning" | "info" | "neutral" };
	due: string;
};

const FILINGS: Filing[] = [
	{
		id: "1",
		title: "Delaware annual report",
		meta: "Annual · Delaware",
		entity: "Acme Inc.",
		flag: <USFlag size={16} />,
		person: "Priya Singh",
		status: { label: "Overdue", tone: "error" },
		due: "1 Oct 2026",
	},
	{
		id: "2",
		title: "VAT return Q3",
		meta: "Monthly · Federal Central Tax Office",
		entity: "Acme GmbH",
		flag: <DEFlag size={16} />,
		person: "Lucas Moreau",
		status: { label: "Filed", tone: "success" },
		due: "7 Nov 2026",
	},
	{
		id: "3",
		title: "Confirmation statement",
		meta: "Annual · Companies House",
		entity: "Acme UK Ltd",
		flag: <GBFlag size={16} />,
		person: "Aisha Khan",
		status: { label: "Due soon", tone: "warning" },
		due: "14 Nov 2026",
	},
	{
		id: "4",
		title: "GST return",
		meta: "Quarterly · IRAS",
		entity: "Acme Pte. Ltd.",
		flag: <SGFlag size={16} />,
		person: "Jun Tan",
		status: { label: "In review", tone: "info" },
		due: "30 Nov 2026",
	},
	{
		id: "5",
		title: "Annual accounts",
		meta: "Annual · KVK",
		entity: "Acme B.V.",
		flag: <NLFlag size={16} />,
		person: "Mira de Vries",
		status: { label: "Not started", tone: "neutral" },
		due: "31 Jan 2027",
	},
];

const COLUMNS: TableColumn<Filing>[] = [
	{
		id: "filing",
		header: "Filing",
		width: 230,
		value: (r) => r.title,
		cell: (r) => <TableCell value={r.title} description={r.meta} />,
	},
	{
		id: "entity",
		header: "Entity",
		width: 160,
		value: (r) => r.entity,
		cell: (r) => <TableCell type="entity" label={r.entity} icon={r.flag} />,
	},
	{
		id: "assignee",
		header: "Assignee",
		width: 150,
		value: (r) => r.person,
		cell: (r) => <TableCell type="person" identity={{ kind: "person", name: r.person }} />,
	},
	{
		id: "status",
		header: "Status",
		width: 110,
		value: (r) => r.status.label,
		cell: (r) => <TableCell type="badge" items={[r.status]} />,
	},
	{ id: "due", header: "Due", width: 110, value: (r) => r.due, sortable: true },
];

const ROW = { getId: (r: Filing) => r.id, getLabel: (r: Filing) => r.title };

export function TableDensity() {
	const rows = FILINGS.slice(0, 3);
	// No fixed widths here, so three columns fit a half-width card.
	const cols = [COLUMNS[0], COLUMNS[3], COLUMNS[4]]
		.filter((c): c is TableColumn<Filing> => Boolean(c))
		.map(({ width: _width, ...c }) => c);
	return (
		<div className="not-prose my-4 grid gap-6 md:grid-cols-2">
			{(["compact", "relaxed"] as const).map((density) => (
				<div key={density}>
					<p className="mb-2 text-[12px] text-fd-muted-foreground">
						{density === "compact" ? "Compact · 40" : "Relaxed · 52"}
					</p>
					<Table
						label={`Filings, ${density}`}
						rows={rows}
						columns={cols}
						rowConfig={ROW}
						controlsConfig={{ toolbar: false, pagination: false }}
						viewConfig={{ density: { value: density, onValueChange: noop } }}
					/>
				</div>
			))}
		</div>
	);
}
```

## Cell types [#cell-types]

Read-only cell types in five families. Text left, numbers right. Each comes in compact and relaxed, and default, hover and selected.

```tsx
import { TableCell, TableNumberCell } from "@commenda/meridian/ui/table";
import { DEFlag } from "@commenda/pathfinder/flags";
import { type ReactElement } from "react";

const noop = () => {};

export function TableCellTypes() {
	const groups: [string, [string, ReactElement][]][] = [
		[
			"Text",
			[
				["Text", <TableCell key="a" value="Delaware annual report" />],
				[
					"Description",
					<TableCell key="b" value="Delaware annual report" description="Due 1 Mar 2027" />,
				],
				[
					"Text + badge",
					<TableCell
						key="c"
						value="Payment from NASA"
						badge={{ label: "Failed", tone: "error" }}
					/>,
				],
				["Copy", <TableCell key="d" type="copy" value="EIN 84-1234567" onCopy={noop} />],
			],
		],
		[
			"People and places",
			[
				[
					"Entity",
					<TableCell key="a" type="entity" label="Acme GmbH" icon={<DEFlag size={16} />} />,
				],
				[
					"Person",
					<TableCell key="b" type="person" identity={{ kind: "person", name: "Priya Singh" }} />,
				],
				[
					"Person + email",
					<TableCell
						key="c"
						type="person"
						identity={{ kind: "person", name: "Priya Singh" }}
						description="priya@acme.com"
					/>,
				],
			],
		],
		[
			"Status",
			[
				[
					"Badge",
					<TableCell key="a" type="badge" items={[{ label: "In review", tone: "info" }]} />,
				],
				["Tag", <TableCell key="b" type="tag" items={[{ label: "Read only" }]} />],
				["Yes", <TableCell key="c" type="boolean" value />],
				["No", <TableCell key="d" type="boolean" value={false} />],
			],
		],
		[
			"Numbers",
			[
				[
					"Number",
					<TableNumberCell key="a" value={12480} format={{ style: "currency", currency: "USD" }} />,
				],
				[
					"Positive",
					<TableNumberCell
						key="b"
						value={4812.4}
						tone="positive"
						format={{ style: "currency", currency: "USD", signDisplay: "always" }}
					/>,
				],
				[
					"Failed",
					<TableNumberCell
						key="c"
						value={419}
						struck
						format={{ style: "currency", currency: "USD" }}
					/>,
				],
				[
					"Trend · positive",
					<TableNumberCell
						key="d"
						value="+12.0%"
						trend={{ direction: "up", intent: "positive" }}
					/>,
				],
				[
					"Trend · critical",
					<TableNumberCell
						key="e"
						value="−4.2%"
						trend={{ direction: "down", intent: "critical" }}
					/>,
				],
			],
		],
	];
	return (
		<div className="not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-6 md:grid-cols-2">
			{groups.map(([group, cells]) => (
				<div key={group}>
					<p className="mb-2 font-medium text-[13px]">{group}</p>
					<div className="flex flex-col divide-y divide-fd-border rounded-lg border border-fd-border">
						{cells.map(([name, cell]) => (
							<div
								key={name}
								className="grid min-h-10 grid-cols-[1fr_120px] items-center gap-3 px-3"
							>
								<div className="min-w-0">{cell}</div>
								<span className="text-[11px] text-fd-muted-foreground">{name}</span>
							</div>
						))}
					</div>
				</div>
			))}
		</div>
	);
}
```

## Row actions [#row-actions]

At most three per row: the main action as a bordered IconButton, one secondary action, then more for everything else. Each icon has a tooltip. Never a text or link button down every row. Use `TableRowActions` in a cell, or `rowConfig.menu` for the more menu.

## Toolbar, summary and preset filters [#toolbar-summary-and-preset-filters]

Filters on the left, one dropdown each; an applied filter shows its value, with Clear after. Search is an icon that opens in place. The summary strip sits inside the container, read-only.

```tsx
import { TableSummary } from "@commenda/meridian/ui/table";

export function TableSummaryExample() {
	return (
		<div className="not-prose my-4 rounded-xl border border-fd-border bg-white p-6">
			<TableSummary
				label="This quarter"
				items={[
					{ id: "due", label: "Total due this quarter", value: "$48,210.00" },
					{ id: "filed", label: "Filed", value: "$31,640.00" },
					{ id: "overdue", label: "Overdue", value: "$4,250.00" },
					{ id: "upcoming", label: "Upcoming", value: "$12,320.00" },
				]}
			/>
		</div>
	);
}
```

## Pagination [#pagination]

Pagination closes every table: the range, Rows per page (25 by default) and pages. Cursor lists show Previous and Next. The bulk-action bar is not in Meridian; product shots do not need it.

## States [#states]

Loading shows skeleton rows at the current density; the toolbar and header stay so the page does not jump. Empty uses the Empty state: no results with Clear filters, or first use. Errors offer Try again.

```tsx
import { Table, TableCell, type TableColumn } from "@commenda/meridian/ui/table";
import { type ReactElement } from "react";

const noop = () => {};

type Filing = {
	id: string;
	title: string;
	meta: string;
	entity: string;
	flag: ReactElement;
	person: string;
	status: { label: string; tone: "error" | "success" | "warning" | "info" | "neutral" };
	due: string;
};

const COLUMNS: TableColumn<Filing>[] = [
	{
		id: "filing",
		header: "Filing",
		width: 230,
		value: (r) => r.title,
		cell: (r) => <TableCell value={r.title} description={r.meta} />,
	},
	{
		id: "entity",
		header: "Entity",
		width: 160,
		value: (r) => r.entity,
		cell: (r) => <TableCell type="entity" label={r.entity} icon={r.flag} />,
	},
	{
		id: "assignee",
		header: "Assignee",
		width: 150,
		value: (r) => r.person,
		cell: (r) => <TableCell type="person" identity={{ kind: "person", name: r.person }} />,
	},
	{
		id: "status",
		header: "Status",
		width: 110,
		value: (r) => r.status.label,
		cell: (r) => <TableCell type="badge" items={[r.status]} />,
	},
	{ id: "due", header: "Due", width: 110, value: (r) => r.due, sortable: true },
];

const ROW = { getId: (r: Filing) => r.id, getLabel: (r: Filing) => r.title };

export function TableStates() {
	return (
		<div className="not-prose my-4 grid gap-6">
			<div>
				<p className="mb-2 text-[12px] text-fd-muted-foreground">Loading</p>
				<Table
					label="Filings"
					rows={[]}
					columns={COLUMNS}
					rowConfig={ROW}
					stateConfig={{ isLoading: true }}
				/>
			</div>
			<div>
				<p className="mb-2 text-[12px] text-fd-muted-foreground">Empty</p>
				<Table
					label="Filings"
					rows={[]}
					columns={COLUMNS}
					rowConfig={ROW}
					stateConfig={{
						empty: {
							title: "No results for “Delaware 2027”",
							description: "Try a different search, or clear the filters.",
							action: { id: "clear", label: "Clear filters", onAction: noop },
						},
					}}
				/>
			</div>
			<div>
				<p className="mb-2 text-[12px] text-fd-muted-foreground">Error</p>
				<Table
					label="Filings"
					rows={[]}
					columns={COLUMNS}
					rowConfig={ROW}
					stateConfig={{ error: { message: "Couldn’t load filings", onRetry: noop } }}
				/>
			</div>
		</div>
	);
}
```

## Anatomy [#anatomy]

One row cell: compact 40 high, 12 side padding, text 13 in soft-pearl 1000. Entities lead with a 16 flag, 8 before the name. Rows are split by a 0.5 soft-pearl 300 line; hover and selected fill soft-pearl 200. Header 36.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `rows` (required) | `readonly TRow[]` |  |
| `columns` (required) | `readonly TableColumn<TRow>[]` |  |
| `rowConfig` (required) | `{ getId: (row: TRow) => string; getLabel: (row: TRow) => string; onActivate?: ((row: TRow) => void) \| undefined; menu?: ((row: TRow) => DropdownMenu) \| undefined; }` |  |
| `viewConfig` | `{ density?: SelectionProps<"compact" \| "relaxed">; hiddenColumns?: SelectionProps<readonly string[]>; columnWidths?: SelectionProps<Readonly<Partial<Record<string, number>>>>; columnPinning?: SelectionProps<Readonly<Partial<Record<string, "start" \| "end" \| null>>>>; }` |  |
| `groupingConfig` | `{ getId: (row: TRow) => string; getLabel: (id: string) => string; leading?: (id: string) => ReactNode; summary?: ((id: string, pageRows: readonly TRow[]) => ReactNode) \| undefined; collapsedGroups?: SelectionProps<readonly string[]>; }` |  |
| `container` | `"card" \| "flat"` |  |
| `controlsConfig` | `{ toolbar?: boolean; pagination?: boolean; }` | Hide record-list chrome when embedding a read-only table. Disabling pagination renders every local row. |
| `sortingConfig` | `SelectionProps<TableSort \| null>` |  |
| `searchConfig` | `SelectionProps<string> & { getText?: ((row: TRow) => string) \| undefined; placeholder?: string; }` |  |
| `filterConfig` | `{ filters: readonly TableFilter<TRow>[]; operators?: SelectionProps<Readonly<Record<string, TableFilterOperator>>>; value: Readonly<Record<string, readonly string[]>>; onValueChange: (value: Record<string, readonly string[]>) => void; }` |  |
| `selectionConfig` | `SelectionProps<TableSelection> & { canSelect?: ((row: TRow) => boolean) \| undefined; allMatching?: { queryKey: string; total: number; }; actions?: readonly TableAction[]; moreMenu?: DropdownMenu; }` |  |
| `toolbarConfig` | `TableToolbarConfig` |  |
| `stateConfig` | `TabularStateConfig` |  |
| `summary` | `ReactNode` |  |
| `footerConfig` | `{ total?: { label: string; cells: Readonly<Record<string, ReactNode>>; }; addAction?: TableAction; }` |  |
| `className` | `string` |  |
| `dataMode` (conditional) | `"local" \| "remote"` |  |
| `paginationConfig` (conditional) | `{ mode?: "pages"; totalRows?: number; pageSizes?: readonly number[]; } & SelectionProps<TablePage> \| { mode: "cursor"; hasNext: boolean; hasPrevious: boolean; onNext: () => void; onPrevious: () => void; summary?: string; pageSize: number; onPageSizeChange?: (size: number) => void; } \| (({ mode?: "pages"; totalRows?: number; pageSizes?: readonly number[]; } & SelectionProps<TablePage>) & { totalRows: number; })` |  |

**`rowConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `getId` (required) | `(row: TRow) => string` |  |
| `getLabel` (required) | `(row: TRow) => string` |  |
| `onActivate` | `(row: TRow) => void` |  |
| `menu` | `(row: TRow) => DropdownMenu` |  |

**`viewConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `density` | `SelectionProps<"compact" \| "relaxed">` |  |
| `hiddenColumns` | `SelectionProps<readonly string[]>` |  |
| `columnWidths` | `SelectionProps<Readonly<Partial<Record<string, number>>>>` |  |
| `columnPinning` | `SelectionProps<Readonly<Partial<Record<string, "start" \| "end" \| null>>>>` |  |

**`viewConfig.density` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `value` (required) | `"compact" \| "relaxed"` |  |
| `onValueChange` (required) | `(value: "compact" \| "relaxed") => void` |  |

Do not supply: `defaultValue`.

**`viewConfig.density` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `"compact" \| "relaxed"` |  |
| `onValueChange` | `(value: "compact" \| "relaxed") => void` |  |

Do not supply: `value`.

**`viewConfig.hiddenColumns` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `value` (required) | `readonly string[]` |  |
| `onValueChange` (required) | `(value: readonly string[]) => void` |  |

Do not supply: `defaultValue`.

**`viewConfig.hiddenColumns` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `readonly string[]` |  |
| `onValueChange` | `(value: readonly string[]) => void` |  |

Do not supply: `value`.

**`viewConfig.columnWidths` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `value` (required) | `Readonly<Partial<Record<string, number>>>` |  |
| `onValueChange` (required) | `(value: Readonly<Partial<Record<string, number>>>) => void` |  |

Do not supply: `defaultValue`.

**`viewConfig.columnWidths` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `Readonly<Partial<Record<string, number>>>` |  |
| `onValueChange` | `(value: Readonly<Partial<Record<string, number>>>) => void` |  |

Do not supply: `value`.

**`viewConfig.columnPinning` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `value` (required) | `Readonly<Partial<Record<string, "start" \| "end" \| null>>>` |  |
| `onValueChange` (required) | `(value: Readonly<Partial<Record<string, "start" \| "end" \| null>>>) => void` |  |

Do not supply: `defaultValue`.

**`viewConfig.columnPinning` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `Readonly<Partial<Record<string, "start" \| "end" \| null>>>` |  |
| `onValueChange` | `(value: Readonly<Partial<Record<string, "start" \| "end" \| null>>>) => void` |  |

Do not supply: `value`.

**`groupingConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `getId` (required) | `(row: TRow) => string` |  |
| `getLabel` (required) | `(id: string) => string` |  |
| `leading` | `(id: string) => ReactNode` |  |
| `summary` | `(id: string, pageRows: readonly TRow[]) => ReactNode` |  |
| `collapsedGroups` | `SelectionProps<readonly string[]>` |  |

**`groupingConfig.collapsedGroups` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `value` (required) | `readonly string[]` |  |
| `onValueChange` (required) | `(value: readonly string[]) => void` |  |

Do not supply: `defaultValue`.

**`groupingConfig.collapsedGroups` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `readonly string[]` |  |
| `onValueChange` | `(value: readonly string[]) => void` |  |

Do not supply: `value`.

**`controlsConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `toolbar` | `boolean` |  |
| `pagination` | `boolean` |  |

**`sortingConfig` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `value` (required) | `TableSort` |  |
| `onValueChange` (required) | `(value: TableSort \| null) => void` |  |

Do not supply: `defaultValue`.

**`sortingConfig.value` fields**

| Field | Type | Description |
| --- | --- | --- |
| `columnId` (required) | `string` |  |
| `direction` (required) | `"desc" \| "asc"` |  |

**`sortingConfig` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `TableSort` |  |
| `onValueChange` | `(value: TableSort \| null) => void` |  |

Do not supply: `value`.

**`sortingConfig.defaultValue` fields**

| Field | Type | Description |
| --- | --- | --- |
| `columnId` (required) | `string` |  |
| `direction` (required) | `"desc" \| "asc"` |  |

**`filterConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `filters` (required) | `readonly TableFilter<TRow>[]` |  |
| `operators` | `SelectionProps<Readonly<Record<string, TableFilterOperator>>>` |  |
| `value` (required) | `Readonly<Record<string, readonly string[]>>` |  |
| `onValueChange` (required) | `(value: Record<string, readonly string[]>) => void` |  |

**`filterConfig.operators` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `value` (required) | `Readonly<Record<string, TableFilterOperator>>` |  |
| `onValueChange` (required) | `(value: Readonly<Record<string, TableFilterOperator>>) => void` |  |

Do not supply: `defaultValue`.

**`filterConfig.operators` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `defaultValue` | `Readonly<Record<string, TableFilterOperator>>` |  |
| `onValueChange` | `(value: Readonly<Record<string, TableFilterOperator>>) => void` |  |

Do not supply: `value`.

**`toolbarConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `actions` | `readonly TableAction[]` | Prefer named actions. Legacy actions use first=primary, second=secondary, remainder=overflow. |
| `primaryAction` | `TableAction & { menu?: DropdownMenu; icon?: ReactNode; }` |  |
| `secondaryAction` | `TableAction` |  |
| `onExport` | `() => void` |  |
| `moreMenu` | `DropdownMenu` |  |

**`toolbarConfig.secondaryAction` fields**

| Field | Type | Description |
| --- | --- | --- |
| `icon` | `ReactNode` |  |
| `id` (required) | `string` |  |
| `label` (required) | `string` |  |
| `onAction` (required) | `() => void` |  |
| `disabled` | `boolean` |  |

**`toolbarConfig.moreMenu` fields**

| Field | Type | Description |
| --- | --- | --- |
| `groups` (required) | `DropdownGroup[]` |  |
| `searchConfig` | `{ label: string; value?: string; onValueChange?: (query: string) => void; filter?: "local" \| "manual"; }` |  |
| `loadingConfig` | `{ isLoading: boolean; label?: string; }` |  |
| `emptyContent` | `ReactNode` |  |
| `footerContent` | `ReactNode` |  |
| `footerConfig` | `{ label: string; onAction: () => void; disabled?: boolean; }` |  |

**`toolbarConfig.moreMenu.searchConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `value` | `string` |  |
| `onValueChange` | `(query: string) => void` |  |
| `filter` | `"manual" \| "local"` |  |

**`toolbarConfig.moreMenu.loadingConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isLoading` (required) | `boolean` |  |
| `label` | `string` |  |

**`toolbarConfig.moreMenu.footerConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `onAction` (required) | `() => void` |  |
| `disabled` | `boolean` |  |

**`stateConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isLoading` | `boolean` |  |
| `error` | `{ message: string; onRetry: () => void; }` |  |
| `empty` | `{ title: string; description?: string; action?: TableAction; }` |  |

**`stateConfig.error` fields**

| Field | Type | Description |
| --- | --- | --- |
| `message` (required) | `string` |  |
| `onRetry` (required) | `() => void` |  |

**`stateConfig.empty` fields**

| Field | Type | Description |
| --- | --- | --- |
| `title` (required) | `string` |  |
| `description` | `string` |  |
| `action` | `TableAction` |  |

**`stateConfig.empty.action` fields**

| Field | Type | Description |
| --- | --- | --- |
| `icon` | `ReactNode` |  |
| `id` (required) | `string` |  |
| `label` (required) | `string` |  |
| `onAction` (required) | `() => void` |  |
| `disabled` | `boolean` |  |

**`footerConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `total` | `{ label: string; cells: Readonly<Record<string, ReactNode>>; }` |  |
| `addAction` | `TableAction` |  |

**`footerConfig.total` fields**

| Field | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `cells` (required) | `Readonly<Record<string, ReactNode>>` |  |

**`footerConfig.addAction` fields**

| Field | Type | Description |
| --- | --- | --- |
| `icon` | `ReactNode` |  |
| `id` (required) | `string` |  |
| `label` (required) | `string` |  |
| `onAction` (required) | `() => void` |  |
| `disabled` | `boolean` |  |

**`paginationConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `mode` (required) | `"cursor"` |  |
| `hasNext` (required) | `boolean` |  |
| `hasPrevious` (required) | `boolean` |  |
| `onNext` (required) | `() => void` |  |
| `onPrevious` (required) | `() => void` |  |
| `summary` | `string` |  |
| `pageSize` (required) | `number` |  |
| `onPageSizeChange` | `(size: number) => void` |  |

## Best practices [#best-practices]

- Text left; numbers right with fixed decimals; a badge column shares its header’s alignment.
- Entities and countries lead with their flag. Long names wrap to two lines instead of truncating.
- Show a tertiary "–" in an empty cell, never a blank.
- One more menu or the icon actions per row; never a link or text button repeated down the rows.
- In a product shot, keep the toolbar and pagination so it reads as the real product. In a comparison table on a marketing page, drop them.
- Hover and selected share soft-pearl 200; the checked box tells them apart.
- Source: Pathfinder Table. Meridian keeps it as is; editable cells, the bulk-action bar and the prototype are not carried over.
