React DataTable: examples and API

Preview

Live preview

Changes apply to this preview only.

Project portfolio

	Atlas	Maya
	Orbit	Noah

0 projects selected.

Loading the interactive example?

Width adapts to the available space

"use client";

import { useState } from "react";
import { DataTable } from "@pimolu/react";

export function DataTableExample() {
  const [selected, setSelected] = useState<string[]>([]);
  const rows = [
    { id: "atlas", name: "Atlas", owner: "Maya" },
    {
      id: "orbit",
      name: "Orbit",
      owner: "Noah"
    },
    {
      id: "forma",
      name: "Forma",
      owner: "Alice"
    }
  ];
  return (
    <div className="space-y-4">
      <DataTable
        data={rows}
        columns={[
          { id: "name", header: "Project", sortable: true },
          {
            id: "owner",
            header: "Owner",
            sortable: true
          }
        ]}
        getRowId={(row) => row.id}
        getRowLabel={(row) => `Select ${row.name}`}
        caption="Project portfolio"
        pageSize={2}
        selectable
        selectedRowIds={selected}
        onSelectionChange={setSelected}
      />
      <p role="status">{selected.length} project{selected.length === 1 ? "" : "s"} selected.</p>
    </div>
  );
}

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Team directory

Filter across every column, sort by any sortable header, select a page of rows and paginate. The header checkbox reflects the visible page and becomes indeterminate when only some rows are selected.

Open preview

Controlled selection

selectedRowIds and onSelectionChange keep the selection in the page so a bulk action can react to it. The table still owns the select-all checkbox and the indeterminate state.

Open preview

Recent orders

The same API drives a denser order table: currency and date cells are formatted with custom accessors while sortValue keeps the raw numeric and ISO values.

Open preview

Usage

Provide stable column ids, data and getRowId. A cell renderer can return React content; use searchValue and sortValue when its visual output does not expose the raw value.

Choose DataTable for a simpler client-side table. Use DataGrid when you need server ownership, grouping, column visibility or resizing. Pages start at 1.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluDataTableSort

Type source

PimoluDataTableSort public API
Name	Type	Default	Description
`columnId`Required	`string`	—	Id of the sorted column.
`direction`Required	`PimoluDataTableSortDirection`	—	Active direction.

columnIdRequired: string
No default extracted.
Id of the sorted column.
directionRequired: PimoluDataTableSortDirection
No default extracted.
Active direction.

PimoluDataTableColumn

Type source

PimoluDataTableColumn public API
Name	Type	Default	Description
`id`Required	`string`	—	Stable column id, also used as the fallback row property key.
`header`Required	`ReactNode`	—	Visible header content.
`accessor`	`((row: T) => ReactNode) \| undefined`	—	Renders the cell content.
`cell`	`((row: T) => ReactNode) \| undefined`	—	Renders the cell content; takes precedence over `accessor`.
`sortable`	`boolean \| undefined`	—	Enables the sort button on this column.
`align`	`PimoluDataTableAlign \| undefined`	`"start"`	Cell and header alignment. Defaults to "start".
`width`	`Property.Width<string \| number> \| undefined`	—	Optional fixed width (number of pixels or any CSS width).
`searchValue`	`((row: T) => string \| number \| null \| undefined) \| undefined`	—	Raw value used by the global filter.
`sortValue`	`((row: T) => string \| number \| null \| undefined) \| undefined`	—	Raw value used for sorting.

idRequired: string
No default extracted.
Stable column id, also used as the fallback row property key.
headerRequired: ReactNode
No default extracted.
Visible header content.
accessor: ((row: T) => ReactNode) | undefined
No default extracted.
Renders the cell content.
cell: ((row: T) => ReactNode) | undefined
No default extracted.
Renders the cell content; takes precedence over `accessor`.
sortable: boolean | undefined
No default extracted.
Enables the sort button on this column.
align: PimoluDataTableAlign | undefined
Default: "start"
Cell and header alignment. Defaults to "start".
width: Property.Width<string | number> | undefined
No default extracted.
Optional fixed width (number of pixels or any CSS width).
searchValue: ((row: T) => string | number | null | undefined) | undefined
No default extracted.
Raw value used by the global filter.
sortValue: ((row: T) => string | number | null | undefined) | undefined
No default extracted.
Raw value used for sorting.

PimoluDataTableLabels

Type source

PimoluDataTableLabels public API
Name	Type	Default	Description
`filter`Required	`string`	—	Accessible label of the filter input.
`filterPlaceholder`Required	`string`	—	Placeholder of the filter input.
`selectAll`Required	`string`	—	Accessible label of the header select-all checkbox.
`selectRow`Required	`(rowId: string) => string`	—	Accessible label of a row checkbox.
`empty`Required	`string`	—	Shown when there is no row to display.
`loading`Required	`string`	`false`	Announced while loading.
`clearSelection`Required	`string`	—	Label of the clear-selection button.

filterRequired: string
No default extracted.
Accessible label of the filter input.
filterPlaceholderRequired: string
No default extracted.
Placeholder of the filter input.
selectAllRequired: string
No default extracted.
Accessible label of the header select-all checkbox.
selectRowRequired: (rowId: string) => string
No default extracted.
Accessible label of a row checkbox.
emptyRequired: string
No default extracted.
Shown when there is no row to display.
loadingRequired: string
Default: false
Announced while loading.
clearSelectionRequired: string
No default extracted.
Label of the clear-selection button.

PimoluDataTableProps

Type source

PimoluDataTableProps public API
Name	Type	Default	Description
`data`Required	`readonly T[]`	—	Rows to display. Never mutated.
`columns`Required	`readonly PimoluDataTableColumn<T>[]`	—	Column definitions.
`getRowId`Required	`(row: T) => string`	—	Stable identity for a row, used by selection.
`getRowLabel`	`((row: T) => string) \| undefined`	`the localised "Select row <id>" label`	Full accessible label of a row checkbox. Defaults to the localised "Select row <id>" label.
`caption`	`ReactNode`	—	Visible table caption, also used as the accessible name.
`ariaLabel`	`string \| undefined`	—	Accessible name when no caption is rendered.
`filterable`	`boolean \| undefined`	`true`	Shows the global filter input. Defaults to true. Matching is case-insensitive across `searchValue`, the rendered cell text and the primitive `row[column.id]` value.
`filter`	`string \| undefined`	—	Controlled filter value.
`defaultFilter`	`string \| undefined`	`""`	Initial filter value when uncontrolled.
`onFilterChange`	`((value: string) => void) \| undefined`	—	Called with the next filter value.
`sort`	`PimoluDataTableSort \| null \| undefined`	—	Controlled sort. Pass `null` to clear.
`defaultSort`	`PimoluDataTableSort \| null \| undefined`	`null`	Initial sort when uncontrolled.
`onSortChange`	`((sort: PimoluDataTableSort \| null) => void) \| undefined`	—	Called with the next sort; `null` when the sort is cleared.
`selectable`	`boolean \| undefined`	`false`	Adds the selection column and the selection bar. The header checkbox selects the visible page only.
`selectedRowIds`	`readonly string[] \| undefined`	—	Controlled selected row ids.
`defaultSelectedRowIds`	`readonly string[] \| undefined`	—	Initial selection when uncontrolled.
`onSelectionChange`	`((selectedRowIds: string[]) => void) \| undefined`	—	Called with the next selection, ordered like `data`. Selection persists across pages and filtering.
`pageSize`	`number \| undefined`	`10`	Rows per page. Defaults to 10.
`page`	`number \| undefined`	—	Controlled page, starting at 1. Filtering and sorting reset the internal page but never call `onPageChange` on your behalf.
`defaultPage`	`number \| undefined`	`1`	Initial page when uncontrolled. Defaults to 1.
`onPageChange`	`((page: number) => void) \| undefined`	—	Called with the next page.
`pagination`	`boolean \| undefined`	`true`	Shows the footer and the pagination. Defaults to true.
`stickyHeader`	`boolean \| undefined`	`false`	Keeps the header visible while the table body scrolls.
`loading`	`boolean \| undefined`	`false`	Dims the table and announces a busy state.
`labels`	`Partial<PimoluDataTableLabels> \| undefined`	—	Overrides individual chrome labels.
`emptyState`	`ReactNode`	—	Replaces the default empty message.
`className`	`string \| undefined`	—	Additional class names on the root.
`rowClassName`	`((row: T, index: number) => string \| undefined) \| undefined`	—	Additional class names per row.

dataRequired: readonly T[]
No default extracted.
Rows to display. Never mutated.
columnsRequired: readonly PimoluDataTableColumn<T>[]
No default extracted.
Column definitions.
getRowIdRequired: (row: T) => string
No default extracted.
Stable identity for a row, used by selection.
getRowLabel: ((row: T) => string) | undefined
Default: the localised "Select row <id>" label
Full accessible label of a row checkbox. Defaults to the localised "Select row <id>" label.
caption: ReactNode
No default extracted.
Visible table caption, also used as the accessible name.
ariaLabel: string | undefined
No default extracted.
Accessible name when no caption is rendered.
filterable: boolean | undefined
Default: true
Shows the global filter input. Defaults to true. Matching is case-insensitive across `searchValue`, the rendered cell text and the primitive `row[column.id]` value.
filter: string | undefined
No default extracted.
Controlled filter value.
defaultFilter: string | undefined
Default: ""
Initial filter value when uncontrolled.
onFilterChange: ((value: string) => void) | undefined
No default extracted.
Called with the next filter value.
sort: PimoluDataTableSort | null | undefined
No default extracted.
Controlled sort. Pass `null` to clear.
defaultSort: PimoluDataTableSort | null | undefined
Default: null
Initial sort when uncontrolled.
onSortChange: ((sort: PimoluDataTableSort | null) => void) | undefined
No default extracted.
Called with the next sort; `null` when the sort is cleared.
selectable: boolean | undefined
Default: false
Adds the selection column and the selection bar. The header checkbox selects the visible page only.
selectedRowIds: readonly string[] | undefined
No default extracted.
Controlled selected row ids.
defaultSelectedRowIds: readonly string[] | undefined
No default extracted.
Initial selection when uncontrolled.
onSelectionChange: ((selectedRowIds: string[]) => void) | undefined
No default extracted.
Called with the next selection, ordered like `data`. Selection persists across pages and filtering.
pageSize: number | undefined
Default: 10
Rows per page. Defaults to 10.
page: number | undefined
No default extracted.
Controlled page, starting at 1. Filtering and sorting reset the internal page but never call `onPageChange` on your behalf.
defaultPage: number | undefined
Default: 1
Initial page when uncontrolled. Defaults to 1.
onPageChange: ((page: number) => void) | undefined
No default extracted.
Called with the next page.
pagination: boolean | undefined
Default: true
Shows the footer and the pagination. Defaults to true.
stickyHeader: boolean | undefined
Default: false
Keeps the header visible while the table body scrolls.
loading: boolean | undefined
Default: false
Dims the table and announces a busy state.
labels: Partial<PimoluDataTableLabels> | undefined
No default extracted.
Overrides individual chrome labels.
emptyState: ReactNode
No default extracted.
Replaces the default empty message.
className: string | undefined
No default extracted.
Additional class names on the root.
rowClassName: ((row: T, index: number) => string | undefined) | undefined
No default extracted.
Additional class names per row.

Accessibility

Provide caption or ariaLabel and useful row labels when selection is enabled.
Selection persists across filtering and pages; the header checkbox selects the visible page. Test this behavior in your workflow.

Read the accessibility guide →

Preview

More examples

Team directory

Controlled selection

Recent orders

Usage

API reference

PimoluDataTableSort

PimoluDataTableColumn

PimoluDataTableLabels

PimoluDataTableProps

Accessibility

Related components