Data Table

Usage#

import { DataTable, type DataTableColumn } from "neelam-ui";
 
interface Person {
  id: number;
  name: string;
  role: string;
  score: number;
}
 
const columns: DataTableColumn<Person>[] = [
  { key: "name", header: "Name", sortable: true },
  { key: "role", header: "Role", sortable: true },
  { key: "score", header: "Score", sortable: true, align: "right" },
];
 
<DataTable columns={columns} data={people} getRowId={(row) => row.id} />

Order of operations#

Filtering runs before sorting and pagination. That ordering is what makes the page count and sort order describe the rows actually on screen, rather than the unfiltered set — a common off-by-a-page bug when the three are composed in the wrong order.

Columns#

key must be a key of your row type, so a typo is a type error rather than a column of undefined.

Custom cells#

cell takes over rendering for a column:

{
  key: "role",
  header: "Role",
  sortable: true,
  cell: (row) => <Badge variant="secondary">{row.role}</Badge>,
  filterValue: (row) => row.role,
}

Sorting a formatted value#

{
  key: "createdAt",
  header: "Created",
  sortable: true,
  cell: (row) => formatDate(row.createdAt),
  sortValue: (row) => row.createdAt.getTime(),
}

Without sortValue, "1 April" sorts before "1 March" — alphabetically correct and chronologically wrong.

Filtering#

filterable adds a search box above the table that matches across every column. Match counts are announced through a live region, so a screen reader user learns that the result set changed without having to go looking.

<DataTable
  columns={columns}
  data={people}
  filterable
  filterLabel="Filter people"
  noMatchesMessage="No people match that search."
/>

Pagination#

Set pageSize to paginate; omit it to render every row. To place the pagination controls somewhere else — outside a card the table sits inside, say — combine hidePagination with onPaginationChange and render your own, while DataTable keeps owning the sort, filter, and page maths:

const [pagination, setPagination] = useState(null);
 
<DataTable
  columns={columns}
  data={people}
  pageSize={10}
  hidePagination
  onPaginationChange={setPagination}
/>;
 
{pagination && (
  <Pagination
    page={pagination.page}
    totalPages={pagination.totalPages}
    onPageChange={pagination.setPage}
  />
)}

hidePagination has no effect without pageSize.

Keyboard#

Accessibility#

• Renders a real <table> with <th scope="col"> headers, so table navigation commands work in screen readers.
• Sortable headers are <button>s carrying aria-sort, which is updated as the sort cycles — the current sort is announced, not merely drawn as an arrow.
• Filter match counts are announced through a live region.
• The empty state distinguishes "no data at all" (emptyMessage) from "your filter excluded everything" (noMatchesMessage), which are very different situations for the user.

Deliberate omissions#

Row selection, column resizing, column reordering, virtualisation, and server-side data are not included. Each would push the component from a presentation concern into a state-management one, and the reasoning is recorded in DECISIONS.md in the repository. For those cases, compose Table with your own logic.

API reference#

DataTable#

DataTableColumn#