<DataTable />

<DataTable <T> />TailwindCSS ModulesProduction Stable

Enterprise-grade data table for operational dashboards: unified client and server query protocols, toolbar search and thirteen filter types, multi-column sort, pagination, row selection, column visibility, expandable rows, and dual list/grid layouts — all driven by a single DataTableQuery object.

InstallationColoxo CLI

npx coloxo add data-table --style coloxo-css

ES Module ImportPlayground / npm package

import { DataTable, type DataTableColumn, type DataTableQuery } from '@coloxo/ui';

Design Tokens:

--cx-datatable-row-height--cx-datatable-header-height--cx-datatable-border--cx-datatable-active-bg

01 / Architecture & pipeline

1. Client vs Server Query Engine

Two execution models share identical toolbar UX and query shape; only the data plane differs.

In-Memory Engine (client)DEFAULT

Runs applyClientPipeline locally: search → filter → sort → paginate over the in-memory data array.

Ideal for admin consoles under ~5k rows, Storybook demos, and offline-first tooling.

mode="client" (default)
onQueryChange updates UI state only

Controlled Query Protocol (server)

Parent owns fetching; pass total, loading, and current page slice via data.

Query mutations mirror REST/GraphQL list endpoints and URL-serialized filter state.

mode="server"
query={query}
onQueryChange={setQuery}
total={remoteTotal}

Client pipeline stages

STAGE 01
Search
Global + per-field text match
STAGE 02
Filter
Column operators (eq, in, between…)
STAGE 03
Sort
Single or multi field ordering
STAGE 04
Paginate
page × pageSize window
STAGE 05
Render
List table or grid cards

Page reset contract: DEFAULT_RESET_PAGE_ON resets to page 1 when search, filter, pageSize, or sort changes unless overridden via resetPageOn.

02 / Column configuration

2. Column Schema & Render Patterns

Declarative column definitions map query fields to cells, filters, and sticky layout.

Name	Type	Default	Description
key	string	—	Stable column id for sort/filter field mapping and visibility toggles.
title	ReactNode \| fn	—	Header label or render function receiving the column definition.
dataIndex	keyof T \| string \| string[]	—	Field accessor; supports nested paths like network.ingress.ip.
width / minWidth	number \| string	—	Fixed or minimum column width for table-layout: fixed.
sortable	boolean \| { multi?, compare? }	—	Enables sort control; optional compare(a,b) overrides default value ordering.
filter	DataTableColumnFilter	—	Toolbar filter popover config (type, options, applyMode, custom render).
render	(value, record, index) => ReactNode	—	Cell renderer when raw dataIndex value is not enough.
align	"left" \| "center" \| "right"	—	Cell and header text alignment.
fixed	"left" \| "right"	—	Sticky column pinning for wide datasets.
hidden	boolean	—	Exclude column from initial render (visibility API can still toggle).

Numeric right align

Financial amounts use tabular nums and right alignment for scanability.

128,450.22 USD

align="right"
sortable={{ compare: (a,b) => a.amount - b.amount }}

Fixed right actions

Pin trailing controls while horizontally scrolling wide datasets.

fixed="right"
rowActions={(record) => <RowActions />}

Status badges

Map enum values to semantic Badge colors inside render().

Active

render={(value) => (
  <Badge color={mapStatus(value)} dot />
)}

03 / Filtering & query helpers

3. Filters, Sorting & Query Utilities

Thirteen first-class filter types plus immutable query merge helpers and URL serialization.

textselectmulti-selectcheckboxradiodatedate-rangenumbernumber-rangebooleansearch-selecttree-selectcustom

mergeQuery(base, patch)

Shallow-merge a partial query patch without resetting pagination unless intended.

withPageReset(prev, patch, resetOn?)

Applies patch and forces page: 1 when search, filter, pageSize, or sort changes per resetOn / DEFAULT_RESET_PAGE_ON.

applyClientPipeline(data, columns, query)

Runs the full in-memory pipeline; returns { rows, total } for client mode previews.

import {
  applyClientPipeline,
  mergeQuery,
  withPageReset,
  DEFAULT_RESET_PAGE_ON,
  parseDataTableQuery,
  serializeDataTableQuery,
  serializeDataTableQueryToURLSearchParams,
} from '@coloxo/ui';

const next = withPageReset(query, { search: 'acme' }, DEFAULT_RESET_PAGE_ON);
const { rows, total } = applyClientPipeline(data, columns, next);
const params = serializeDataTableQueryToURLSearchParams(next);
const restored = parseDataTableQuery(params);

04 / Live sandbox

4. Interactive Live Sandbox & Inspector

Tune density, view mode, and toolbar features; copy generated JSX for your app shell.

Props inspector

viewMode

rowDensity

pagination

rowSelection

stickyHeader

Visual Render CanvasLIST · STANDARD

Team directory sandbox
	Department		Email	Status
Member 1 MBR-0001	Engineering	Manager	member1@coloxo.app	Active	2024-01-01
Member 2 MBR-0002	Design	Individual contributor	member2@coloxo.app	Pending	2024-02-02
Member 3 MBR-0003	HR	Individual contributor	member3@coloxo.app	Inactive	2024-03-03
Member 4 MBR-0004	Finance	Manager	member4@coloxo.app	Active	2024-04-04
Member 5 MBR-0005	Engineering	Individual contributor	member5@coloxo.app	Pending	2024-05-05
Member 6 MBR-0006	Design	Individual contributor	member6@coloxo.app	Inactive	2024-06-06
Member 7 MBR-0007	HR	Manager	member7@coloxo.app	Active	2024-07-07
Member 8 MBR-0008	Finance	Individual contributor	member8@coloxo.app	Pending	2024-08-08

tsx

1<DataTable2  columns={columns}3  data={rows}4  search={{ placeholder: 'Search members…', debounceMs: 300 }}5  pagination={{ pageSize: 8, showSizeChanger: true }}6  rowSelection={{}}7  stickyHeader8/>

05 / Dual view modes

5. List vs Grid Layout

Same query state powers native table semantics or card grid density.

List view

	Department		Email	Status
Member 1 MBR-0001	Engineering	Manager	member1@coloxo.app	Active	2024-01-01
Member 2 MBR-0002	Design	Individual contributor	member2@coloxo.app	Pending	2024-02-02
Member 3 MBR-0003	HR	Individual contributor	member3@coloxo.app	Inactive	2024-03-03
Member 4 MBR-0004	Finance	Manager	member4@coloxo.app	Active	2024-04-04
Member 5 MBR-0005	Engineering	Individual contributor	member5@coloxo.app	Pending	2024-05-05
Member 6 MBR-0006	Design	Individual contributor	member6@coloxo.app	Inactive	2024-06-06

Grid view

Active

Member 1

MBR-0001

Manager · Engineering

Pending

Member 2

MBR-0002

Individual contributor · Design

Inactive

Member 3

MBR-0003

Individual contributor · HR

Active

Member 4

MBR-0004

Manager · Finance

Pending

Member 5

MBR-0005

Individual contributor · Engineering

Inactive

Member 6

MBR-0006

Individual contributor · Design

06 / Enterprise dark theme

6. Dark Theme Matrix

Token-driven borders and active row fills on deep enterprise surfaces.

Incident audit trail · compact density

Row height 32px · header 44px · --cx-datatable-border on #0B1120

Security operations log

Recent audit events
Severity	Incident	Service	Actor	Timestamp
CRITICAL	INC-9021	auth-gateway	svc-bot-iam	2026-09-22 14:02 UTC
HIGH	INC-9020	payments-api	jordan.vance	2026-09-22 13:48 UTC
MEDIUM	INC-9019	search-index	deploy-hook	2026-09-22 13:12 UTC
HIGH	INC-9018	ledger-writer	batch-recon	2026-09-22 12:55 UTC

07 / Enterprise compositions

7. High-Density Application Patterns

Selection-aware ledgers and expandable infrastructure rows in production layouts.

Composition A: Financial ledger

Treasury

Row selection with live selected count for batch approval workflows.

0 rows selected

	Counterparty		Status
SWIFT-88421	Acme Treasury Ltd.	128,450.22 USD	posted
ACH-44102	Northwind Payroll	-42,800.00 USD	posted
WIRE-99201	Helios Capital	510,000.00 EUR	pending
ACH-44188	Vertex Cloud	-9,240.15 USD	failed
SWIFT-88425	Orbital FX Desk	76,320.50 GBP	posted

Composition B: Kubernetes pods

Platform

Expandable rows surface container metrics without leaving the list context.

		Namespace	Node	Phase	Restarts
	api-gateway-7f9c8	prod-edge	gke-node-12	Running	0
	billing-worker-2a1	prod-billing	gke-node-04	Running	1
CPU 180m Memory 768Mi Node gke-node-04
	search-index-0	prod-search	gke-node-09	Pending	0
	metrics-scraper-fail	observability	gke-node-02	Failed	5

08 / Accessibility contract

8. Keyboard & Assistive Technology

Native table semantics, sort affordances, and stable layout under hydration.

Keyboard navigation

Tab through toolbar controls; sort buttons activate with Enter/Space; row selection checkboxes participate in the tab order with visible focus rings.

aria-sort & live regions

Sortable headers expose aria-sort (ascending/descending/none). Pagination and selection summaries use polite live regions where counts change.

table-layout: fixed & CLS

Explicit column widths and --cx-datatable-row-height via data-density keep cumulative layout shift at zero during SSR hydration and density toggles.

Props

Name	Type	Default	Description
columns	DataTableColumn<T>[]	—	Column definitions (key, title, dataIndex, sortable, filter, render, align, fixed).
data	T[]	—	Row records for the current view or server page slice.
mode	"client" \| "server"	client	Client pipeline vs parent-owned server fetching.
query / defaultQuery	DataTableQuery / Partial<DataTableQuery>	—	Controlled or initial paging, search, sort, and filters.
onQueryChange	(query: DataTableQuery) => void	—	Fired when toolbar interactions mutate query state.
total	number	—	Remote row count (server mode).
loading	boolean	—	Shows loading affordance over the table body.
error	boolean \| Error \| ReactNode	—	Error state surface.
search	boolean \| DataTableSearchConfig	—	Global search field (placeholder, debounceMs, fields).
pagination	boolean \| DataTablePaginationConfig	—	Footer paging controls and page size changer.
resetPageOn	DataTableResetPageOn	—	When to reset to page 1 (defaults to DEFAULT_RESET_PAGE_ON).
rowSelection	DataTableRowSelection<T>	—	Checkbox selection with optional controlled selectedRowKeys.
columnVisibility	boolean \| DataTableColumnVisibility	—	Column show/hide toggles in the toolbar.
expandable	DataTableExpandable<T>	—	Expandable rows with renderExpandedRow.
viewMode / defaultViewMode	"list" \| "grid"	—	Layout; grid requires renderGridItem.
renderGridItem	(record, index) => ReactNode	—	Card renderer for grid view.
stickyHeader	boolean	—	Sticky header row while scrolling.
rowDensity	"compact" \| "standard" \| "comfortable"	standard	Row rhythm via data-density and --cx-datatable-row-height (32 / 40 / 48).
rowActions	(record, index) => ReactNode	—	Trailing actions column (often fixed right).
caption	string	—	Accessible table caption.
getRowId	(record, index) => string	—	Stable row key resolver.