Skip to content
Porcelana

DataTable

Sortable, searchable, selectable, paginated table that turns into cards on phones.

Data & display

Example

Alarm devices
Bedside dialBedroomOnline86%
Kitchen puckKitchenOnline54%
Hall panelHallwayOnline100%
Kids lampKids roomOffline12%
Example.tsx
import { Badge, DataTable, type ColumnDef } from "@porcelana/ui";

interface Device {
  id: string;
  name: string;
  room: string;
  battery: number;
  status: "Online" | "Offline";
}

const devices: Device[] = [
  { id: "d1", name: "Bedside dial", room: "Bedroom", battery: 86, status: "Online" },
  { id: "d2", name: "Kitchen puck", room: "Kitchen", battery: 54, status: "Online" },
  { id: "d3", name: "Hall panel", room: "Hallway", battery: 100, status: "Online" },
  { id: "d4", name: "Kids lamp", room: "Kids room", battery: 12, status: "Offline" },
  { id: "d5", name: "Desk pebble", room: "Office", battery: 71, status: "Online" },
  { id: "d6", name: "Garden chime", room: "Terrace", battery: 39, status: "Offline" }
];

const columns: ColumnDef<Device, unknown>[] = [
  { accessorKey: "name", header: "Device" },
  { accessorKey: "room", header: "Room" },
  {
    accessorKey: "status",
    header: "Status",
    cell: (c) => (
      <Badge tone={c.getValue() === "Online" ? "success" : "danger"} dot>
        {c.getValue<string>()}
      </Badge>
    )
  },
  { accessorKey: "battery", header: "Battery", cell: (c) => `${c.getValue<number>()}%` }
];

export default function Example() {
  return (
    <DataTable
      data={devices}
      columns={columns}
      caption="Alarm devices"
      selectable
      searchable
      searchLabel="Search devices"
      pageSize={4}
      getRowId={(d) => d.id}
      getRowLabel={(d) => d.name}
    />
  );
}

Import

Import
import { DataTable } from "@porcelana/ui";
import "@porcelana/ui/styles.css"; // once, at your app root

Props

Generated from the TypeScript types. Standard HTML attributes are passed through and not listed.

DataTable

Sortable, filterable, selectable, paginated table on TanStack Table. Under 640px it renders a card list with sort chips; selection becomes tap-to-select.

PropTypeDefaultDescription
captionrequiredstring–Describes the table for screen readers. Visible unless `hideCaption`.
columnsrequiredColumnDef<TData, unknown>[]–TanStack Table column definitions. A string header becomes the sort label.
datarequiredTData[]–Rows to display.
classNamestring–Class on the outer wrapper.
emptyTextReactNodeNo resultsShown when no rows match.
getRowId((row: TData, index: number) => string)–Stable id per row; keys selection state. Defaults to the row index.
getRowLabel((row: TData) => string)–Name of a row, used in "Select <name>" labels and mobile card titles.
hideCaptionboolean–Keep the caption for screen readers but hide it visually.
initialSortingSortingState[]Sorting on first render, e.g. [{ id: "name", desc: false }].
layout"table" | "auto" | "cards"autoForce a layout instead of following the 640px breakpoint.
onRowSelectionChange((selection: RowSelectionState) => void)–Called with the selection map ({ [rowId]: true }).
pageSizenumber10Rows per page.
renderCard((row: Row<TData>) => ReactNode)–Custom mobile card body. Defaults to "Column: value" lines.
rowSelectionRowSelectionState–Controlled selection map.
searchableboolean–Shows a search field filtering every column.
searchLabelstringSearchAccessible name and placeholder of the search field.
selectableboolean–Adds a checkbox column (and tap-to-select cards on mobile).
toolbar((table: Table<TData>) => ReactNode)–Content for the toolbar, e.g. bulk actions. Receives the table instance.

Accessibility

  • A captioned table; sortable headers are buttons and the header cells carry aria-sort.
  • Row checkboxes are named after the row (getRowLabel); select-all is page-scoped and tri-state.
  • Result counts are announced live after searching or paging.
  • The scroll area is a focusable, labelled region so keyboard users can scroll wide tables.

Mobile

  • Under 640px rows become tap-to-select cards, and sort options become a row of chips.
  • Force a layout with layout="table" or layout="cards".