Documentation · itzsa

React DataTable — @itzsa/table

Composable React DataTable for Next.js & TypeScript — sorting, pagination, filters, row selection, inline editing, CSV/Excel export, tree data, and keyboard navigation. Built on shadcn-style primitives; features are opt-in via props.

@itzsa/tableReact 18 / 19Tailwind v4

Installation#

Add the package, then wire Tailwind so utility classes inside the table are generated.

pnpm add @itzsa/table

In your global CSS (Tailwind v4):

@import "tailwindcss";
@source "../node_modules/@itzsa/table";
@import "@itzsa/table/styles.css";

Peers

Peer deps: react and react-dom ^18 or ^19. Import styles once at the app root.

Getting started#

Minimal client table. Serial numbers (SN) default on — pass sn={false} to hide.

import { DataTable } from "@itzsa/table";

const data = [
  { id: "1", name: "Ada Lovelace", role: "Mathematician" },
  { id: "2", name: "Alan Turing", role: "Computer scientist" },
];

const columns = [
  { key: "name", header: "Name", sortable: true },
  { key: "role", header: "Role" },
];

export function UsersTable() {
  return (
    <DataTable
      data={data}
      columns={columns}
      pageSize={10}
      showPagination
      sn
    />
  );
}

Opt-in by default

Almost every behavioral feature is off by default except SN and pagination. Turn on what you need with props like selectable, editable, showExport.

Examples#

Live demos — Preview / Code toggle; copy from the upper right.

Full-featured grid#

Cell edit, detail panel, filters, export, keyboard nav, actions, and custom page size (type or pick).

SN		Email				Location
1	Alan Hopper	alan.hopper042@example.com	Design	Senior Engineer	Offline	New York	2017-06-14
2	Alan Lovelace	alan.lovelace002@example.com	Design	Senior Engineer	Away	New York	2017-02-02
3	Alan Torvalds	alan.torvalds082@example.com	Design	Senior Engineer	Active	New York	2017-10-26
4	Anders Hopper	anders.hopper058@example.com	Design	Senior Engineer	Active	New York	2023-10-02
5	Anders Lovelace	anders.lovelace018@example.com	Design	Senior Engineer	Offline	New York	2023-06-18
6	Anders Torvalds	anders.torvalds098@example.com	Design	Senior Engineer	Away	New York	2023-02-14
7	Dennis Johnson	dennis.johnson074@example.com	Design	Senior Engineer	Away	New York	2019-02-18
8	Dennis Turing	dennis.turing034@example.com	Design	Senior Engineer	Active	New York	2019-10-06
9	Margaret Johnson	margaret.johnson066@example.com	Design	Senior Engineer	Offline	New York	2021-06-10
10	Margaret Turing	margaret.turing026@example.com	Design	Senior Engineer	Away	New York	2021-02-26
11	Radia Hopper	radia.hopper050@example.com	Design	Senior Engineer	Away	New York	2025-02-22
12	Radia Lovelace	radia.lovelace010@example.com	Design	Senior Engineer	Active	New York	2025-10-10
13	Radia Torvalds	radia.torvalds090@example.com	Design	Senior Engineer	Offline	New York	2025-06-06
14	Ada Hopper	ada.hopper041@example.com	Engineering	Engineer	Away	San Francisco	2016-05-13
15	Ada Lovelace	ada.lovelace001@example.com	Engineering	Engineer	Active	San Francisco	2016-01-01
16	Ada Torvalds	ada.torvalds081@example.com	Engineering	Engineer	Offline	San Francisco	2016-09-25
17	Brendan Hopper	brendan.hopper057@example.com	Engineering	Engineer	Offline	San Francisco	2022-09-01
18	Brendan Lovelace	brendan.lovelace017@example.com	Engineering	Engineer	Away	San Francisco	2022-05-17

Showing 1–18 of 100

Rows

Row edit mode#

editMode="row" — double-click, edit several fields, then save or cancel.

	Email				Location
Ada Lovelace	ada.lovelace001@example.com	Engineering	Engineer	Active	San Francisco	2016-01-01
Alan Lovelace	alan.lovelace002@example.com	Design	Senior Engineer	Away	New York	2017-02-02
Grace Lovelace	grace.lovelace003@example.com	Product	Designer	Offline	London	2018-03-03
Margaret Lovelace	margaret.lovelace006@example.com	Support	Lead	Offline	Toronto	2021-06-06
Guido Lovelace	guido.lovelace011@example.com	Product	Designer	Away	London	2016-11-11
James Lovelace	james.lovelace016@example.com	People	Specialist	Active	Remote	2021-04-16
Ada Turing	ada.turing021@example.com	Sales	Analyst	Offline	Tokyo	2016-09-21
Margaret Turing	margaret.turing026@example.com	Design	Senior Engineer	Away	New York	2021-02-26

Tree data#

Path-based hierarchy via getTreeDataPath. Expand groups on the first column.

	Name	Role	Email	Location	Status
	Engineering
	Design
	Product
	Operations

Locale override#

Partial localeText map for toolbar and control labels.

	Email
Ada Lovelace	ada.lovelace001@example.com	Engineering	Engineer
Alan Lovelace	alan.lovelace002@example.com	Design	Senior Engineer
Grace Lovelace	grace.lovelace003@example.com	Product	Designer
Katherine Lovelace	katherine.lovelace004@example.com	Marketing	Product Manager
Linus Lovelace	linus.lovelace005@example.com	Sales	Analyst

Props API#

Full surface area — DataTable, columns, pagination, actions, classNames, styles, and localeText. Use these tables when wiring the package in another app.

DataTable#

Core props. Features stay opt-in unless noted.

DataTableProps

Prop	Type	Default	Description
data	T[]	-	Row data (full set in client mode, or current page in server mode).
columns	DataTableColumn<T>[]	-	Column definitions.
getRowId	(row, index) => string	row.id	Stable row id for selection, edit, and expand state.
showPagination	boolean	true	Show footer pagination.
pageSize	number	10	Rows per page. Any positive number (e.g. 18).
paginationOptions	DataTablePaginationOptions	-	Page-size combobox, totals, numbered pages, min/max.
paginationMode	'client' \| 'server'	'client'	Who owns paging. Wins over mode when both set.
mode	'client' \| 'server'	'client'	Legacy alias for data sourcing (prefer paginationMode).
totalRows	number	-	Server-mode total row count.
loading	boolean	false	Loading overlay over the scroll area.
onStateChange	(state) => void	-	Fires when page, sort, filters, density, etc. change.
selectable	boolean	false	Checkbox selection column.
selectedIds	string[]	-	Controlled selection.
defaultSelectedIds	string[]	-	Uncontrolled initial selection.
onSelectionChange	(ids) => void	-	Selection callback.
sn	boolean	true	Auto serial-number column (not in row data).
snHeader	string	"SN"	SN column header label.
stickyHeader	boolean	false	Pin header while scrolling body.
stickyHeading	boolean	false	Deprecated alias for stickyHeader.
stickyFirstColumn	boolean	false	Pin first data column horizontally.
minTableWidth	string	-	Min table width before horizontal scroll.
maxHeight	string	-	Scroll container max-height (defaults to 28rem with sticky/virtualization).
emptyMessage	string	locale	Empty state text (falls back to localeText.emptyMessage).
enableMultiSort	boolean	true	Allow multiple sort columns.
sort	DataTableSort[]	-	Controlled sort.
defaultSort	DataTableSort[]	[]	Uncontrolled initial sort.
onSortChange	(sort) => void	-	Sort change callback.
enableFiltering	boolean	false	Per-column filter bar.
filters	DataTableFilters	-	Controlled filter bar values.
defaultFilters	DataTableFilters	-	Uncontrolled initial filters.
onFiltersChange	(filters) => void	-	Filter bar callback.
showFilterBuilder	boolean	false	Advanced multi-condition filter popover.
advancedFilters	FilterCondition[]	-	Controlled advanced filters.
onFilterBuilderApply	(payload) => void	-	Called when builder Apply is pressed.
enableQuickFilter	boolean	false	Global toolbar search.
quickFilter	string	-	Controlled quick filter.
onQuickFilterChange	(value) => void	-	Quick filter callback.
quickFilterPlaceholder	string	-	Overrides locale quick-filter placeholder.
showColumnSelector	boolean	false	Columns show/hide menu.
columnVisibility	Record<string, boolean>	-	Visibility map (false = hidden).
onColumnVisibilityChange	(v) => void	-	Visibility callback.
reorderable	boolean	false	Drag headers to reorder.
columnOrder	string[]	-	Controlled column order.
onColumnOrderChange	(order) => void	-	Order callback.
showColumnMenu	boolean	false	Per-header ⋮ menu (sort / pin / hide).
pinnedColumns	{ left?, right? }	-	Pinned column keys.
onPinnedColumnsChange	(pinned) => void	-	Pin change callback.
resizable	boolean	false	Drag column edges to resize.
columnWidths	Record<string, number>	-	Controlled widths.
onColumnWidthsChange	(widths) => void	-	Width callback.
density	'compact'\|'comfortable'\|'spacious'	'compact'	Row density.
showDensityControl	boolean	false	Toolbar density menu.
activeRowId	string \| null	-	Highlighted row id.
onRowClick	(row, index) => void	-	Row click handler.
rowClassName	string \| (row, index) => string	-	Per-row class helper.
actions	DataTableRowAction[] \| (row) => …	-	Declarative row actions.
actionsDisplay	'menu' \| 'icons'	'menu'	Shorthand for actionsOptions.display.
actionsOptions	DataTableActionsOptions	-	Permissions, sticky, display mode.
renderRowActions	(row) => ReactNode	-	Custom actions content (ignored if actions is set).
popoverOffset	number	8	floating-ui offset for menus.
popoverPlacement	Placement	bottom-start	floating-ui placement.
editable	boolean	false	Enable inline editing.
editMode	'cell' \| 'row'	'cell'	Single cell vs whole-row draft.
editAllColumns	boolean	false	All columns editable unless column.editable === false.
processRowUpdate	(newRow, oldRow) => T \| Promise<T>	-	Commit edited row.
onProcessRowUpdateError	(error) => void	-	Edit commit error handler.
onCellEditStart	(params) => void	-	Fired when edit begins.
onCellEditStop	(params) => void	-	Fired when edit ends.
isCellEditable	(params) => boolean	-	Per-cell edit gate.
enableVirtualization	boolean	false	Row virtualization (off with tree/detail).
virtualRowHeight	number	-	Estimated row height; defaults from density.
virtualOverscan	number	8	Extra rows outside viewport.
showExport	boolean	false	CSV export toolbar.
exportFilename	string	table-export.csv	Download filename.
exportScope	'filtered' \| 'page' \| 'selected'	'filtered'	Which rows are exported.
onExported	(format) => void	-	After export completes (csv \| clipboard).
enableKeyboardNavigation	boolean	false	Arrow-key focus; Enter starts edit.
getDetailPanelContent	(params) => ReactNode	-	Master-detail panel under a row.
detailPanelExpandedRowIds	string[]	-	Controlled detail expand state.
onDetailPanelExpandedRowIdsChange	(ids) => void	-	Detail expand callback.
treeData	boolean	false	Enable path-based tree hierarchy.
getTreeDataPath	(row) => string[]	-	Path segments for each row.
expandedTreeIds	string[]	-	Controlled tree expand ids.
defaultGroupingExpansionDepth	number	-	Initial expand depth (-1 = all).
groupingColDef	{ headerName?, width?, … }	-	Grouping column chrome.
localeText	Partial<DataTableLocaleText>	-	Override UI strings (see localeText table).
radius	'none'\|'xs'\|'sm'\|'md'	'xs'	Corner radius token.
showRowBorders	boolean	true	Horizontal borders between rows.
showColumnBorders	boolean	false	Vertical borders between columns.
className	string	-	Root element class.
style	CSSProperties	-	Root element inline style.
classNames	DataTableClassNames	-	Per-slot Tailwind classes (see classNames slots).
styles	DataTableStyles	-	Per-slot inline CSS (see styles slots).
toolbar	ReactNode	-	Extra toolbar content beside built-ins.

DataTableColumn#

Per-column configuration passed in columns[].

DataTableColumn<T>

Prop	Type	Default	Description
key	string	-	Field key on the row object.
header	string	-	Header label.
sortable	boolean	-	Include in sort cycling.
hideBelow	'sm' \| 'md' \| 'lg'	-	Hide column below breakpoint.
wrap	boolean	-	Soft-wrap cell text (disables truncate).
truncate	boolean	true*	Ellipsis overflow (*default when wrap is unset).
sticky	boolean	-	Legacy sticky left; prefer pinned.
pinned	'left' \| 'right'	-	Pin while scrolling horizontally.
resizable	boolean	true	Allow resize when table resizable is on.
width	number	-	Preferred width in px.
minWidth	number	-	Minimum width in px.
maxWidth	number	-	Maximum width in px.
filterable	boolean	-	Appear in filter bar / builder.
filterType	string \| enum \| number \| …	-	Filter input type.
filterOptions	string[]	-	Enum / select options for filter.
filterMin	number	-	Numeric filter min.
filterMax	number	-	Numeric filter max.
filterStep	number	-	Numeric filter step.
editable	boolean	-	Editable when table editable is on.
editType	'text'\|'number'\|'select'\|'boolean'\|'textarea'	'text'	Built-in editor.
editOptions	string[]	-	Select options for editType select.
renderEditCell	(helpers) => ReactNode	-	Custom editor.
cell	(row, index) => ReactNode	-	Custom display renderer.
className	string	-	Body cell classes.
headerClassName	string	-	Header cell classes.

paginationOptions#

Footer rows-per-page combobox (type + dropdown) and pager chrome.

DataTablePaginationOptions

Prop	Type	Default	Description
showPageSizeOptions	boolean	true	Show rows-per-page combobox.
pageSizeOptions	number[]	[5,10,20,50]	Preset sizes; current pageSize always merged in.
allowCustomPageSize	boolean	true	Type a custom limit in the same control.
minPageSize	number	1	Clamp typed values (min).
maxPageSize	number	500	Clamp typed values (max).
showPageNumbers	boolean	true	Numbered page buttons.
maxVisiblePages	number	3	Sliding window of page numbers.
showTotal	boolean	true	Showing X–Y of Z.
rowsLabel	string	"Rows"	Label beside page-size control.
showPrevNext	boolean	true	Previous / next buttons.

actions & actionsOptions#

Declarative row actions — menu or icons, never both.

DataTableRowAction

Prop	Type	Default	Description
id	string	-	Optional action id.
label	string	-	Menu / tooltip label.
onClick	(row) => void	-	Click handler.
icon	ReactNode	-	Icon for menu or icons mode.
variant	'default' \| 'destructive'	-	Destructive styling for delete-like actions.
show	boolean \| (row) => boolean	-	Conditional visibility (prefer over hidden).
hidden	boolean \| (row) => boolean	-	Hide when true.
disabled	boolean \| (row) => boolean	-	Disable per row.
permission	string \| (row) => boolean	-	Checked via actionsOptions.permissions / canAccess.

DataTableActionsOptions

Prop	Type	Default	Description
display	'menu' \| 'icons'	'menu'	⋯ popover or icon buttons only (never both).
permissions	string[] \| Record<string, boolean>	-	Allowed permission keys.
canAccess	(permission, row) => boolean	-	Custom permission check (wins).
sticky	boolean	true	Sticky actions column.
menuAriaLabel	string	-	Aria label for ⋯ trigger.

classNames slots#

Pass Tailwind (or any) class strings per slot. Merged last via tailwind-merge — same idea as MUI DataGrid classes.

DataTableClassNames

Prop	Type	Default	Description
root	string	-	Outer DataTable wrapper.
toolbar	string	-	Top toolbar row.
quickFilter	string	-	Quick filter control.
columnSelector	string	-	Columns visibility menu.
densityControl	string	-	Density menu.
export	string	-	Export menu.
filterBuilder	string	-	Advanced filter builder trigger/popover.
filterBar	string	-	Per-column filter bar.
scroll	string	-	Scroll container around the table.
table	string	-	<table> element.
header	string	-	<thead> region.
headerRow	string	-	Header <tr>.
headerCell	string	-	Header <th> cells.
body	string	-	<tbody>.
row	string	-	Body <tr>.
cell	string	-	Body <td> cells.
pagination	string	-	Footer pagination.
loading	string	-	Loading overlay.
empty	string	-	Empty-state cell.
detailPanel	string	-	Expanded detail panel cell.
expandCell	string	-	Expand/collapse control cell.
checkboxCell	string	-	Selection checkbox cell.
snCell	string	-	Serial-number cell.
actionsCell	string	-	Row actions cell.
actionsHeader	string	-	Actions column header.

classNames={{
  root: "shadow-sm",
  headerCell: "text-xs uppercase tracking-wide",
  row: "hover:bg-muted/40",
  pagination: "border-t",
}}

styles slots#

Per-slot React.CSSProperties. Prefer classNames for theme tokens; use styles for one-off layout.

DataTableStyles

Prop	Type	Default	Description
root	CSSProperties	-	Outer wrapper.
toolbar	CSSProperties	-	Toolbar.
filterBar	CSSProperties	-	Filter bar.
scroll	CSSProperties	-	Scroll container.
table	CSSProperties	-	<table>.
header	CSSProperties	-	Header region.
headerRow	CSSProperties	-	Header row.
headerCell	CSSProperties	-	Header cells.
body	CSSProperties	-	Body.
row	CSSProperties	-	Body rows.
cell	CSSProperties	-	Body cells (merged after size/pin styles).
pagination	CSSProperties	-	Footer.
loading	CSSProperties	-	Loading overlay.
empty	CSSProperties	-	Empty state.
detailPanel	CSSProperties	-	Detail panel.

styles={{
  root: { borderRadius: 10 },
  scroll: { maxHeight: "22rem" },
  headerCell: { letterSpacing: "0.02em" },
}}

localeText#

Partial map over DataTableLocaleText. Unset keys keep English defaults from DEFAULT_LOCALE_TEXT.

Partial<DataTableLocaleText>

Prop	Type	Default	Description
emptyMessage	string	"No results."	Empty table copy.
loading	string	"Loading…"	Loading overlay text.
snHeader	string	"SN"	SN column header.
actionsHeader	string	"Actions"	Actions column header.
quickFilterPlaceholder	string	"Search…"	Quick filter placeholder.
quickFilterAriaLabel	string	-	Quick filter aria-label.
quickFilterClear	string	-	Clear search button label.
densityLabel	string	-	Density control label.
densityCompact / Comfortable / Spacious	string	-	Density option labels.
columnsLabel	string	-	Columns menu trigger.
columnsSearchPlaceholder	string	-	Columns search field.
columnsShowAll / columnsHideAll	string	-	Bulk visibility actions.
columnsCount	(n) => string	-	Visible column count text.
exportLabel	string	-	Export menu trigger.
exportDownloadCsv / exportCopyCsv / exportCopied	string	-	Export menu items + toast.
paginationShowing / paginationOf	string	-	“Showing X–Y of Z” parts.
paginationRowsLabel	string	-	Rows label (also overridable via paginationOptions).
paginationPrevious / paginationNext	string	-	Pager buttons.
paginationPageAria	(n) => string	-	Page button aria.
filterBuilderLabel	string	-	Filter builder trigger.
filterBarAll / filterBarClear	string	-	Filter bar chrome.
filterBarPlaceholder / filterBarAria	(header) => string	-	Per-column filter labels.
columnMenuSortAsc / SortDesc / ClearSort	string	-	Header menu sort items.
columnMenuPinLeft / PinRight / Unpin / Hide	string	-	Header menu pin/hide.
selectAllAria / selectRowAria	string \| fn	-	Selection aria.
expandRowAria / collapseRowAria	string	-	Detail expand aria.
expandGroupAria / collapseGroupAria	string	-	Tree group aria.
detailPanelAria	string	-	Detail panel region aria.

CSS & theming#

Import package CSS once, then override via classNames / styles. Consumer classes win.

<DataTable
  classNames={{
    root: "border-border",
    header: "bg-muted/40",
    row: "hover:bg-muted/30",
    pagination: "bg-card",
  }}
  styles={{
    root: { borderRadius: 12 },
    headerCell: { fontWeight: 600 },
  }}
  data={rows}
  columns={columns}
/>

Merge order

Internal classes → classNames.* (via tailwind-merge) → styles.* inline. Column className / headerClassName apply on that column’s cells.

Feature map#

Capability → prop. Everything here is opt-in except SN and pagination.

Quick reference

Prop	Type	Default	Description
Auto SN	sn	true	Computed serial column
Selection	selectable	false	Checkbox column
Quick filter	enableQuickFilter	false	Toolbar search
Filter bar	enableFiltering	false	Per-column filters
Filter builder	showFilterBuilder	false	Advanced filters
Export CSV	showExport	false	Download / copy
Editing	editable	false	Cell or row mode
Detail panel	getDetailPanelContent	—	Expandable rows
Tree data	treeData + getTreeDataPath	false	Hierarchy
Virtualization	enableVirtualization	false	Large pages
Keyboard	enableKeyboardNavigation	false	Arrow focus
i18n	localeText	—	UI string map
Custom CSS	classNames / styles	—	Per-slot styling