KKiotaPay UI
Browse documentation

Data Table

A client-side table over data you already hold. Sorting, paging, column visibility and search all run in the browser.

Installation

pnpm dlx shadcn@latest add https://kiotapay-ui-staging.staging.kiotapay.com/r/data-table.json

Installs data-table.tsx and data-table-pagination.tsx, plus the shadcn table, button, select and dropdown-menu primitives. Adds @tanstack/react-table.

Usage

'use client'

import type { ColumnDef } from '@tanstack/react-table'

import { DataTable } from '@/components/custom/data-table'

const columns: ColumnDef<Payout>[] = [
  { accessorKey: 'reference', header: 'Reference' },
  { accessorKey: 'beneficiaryName', header: 'Beneficiary' },
]

export function PayoutTable({ payouts, isLoading }) {
  return (
    <DataTable
      columns={columns}
      data={payouts}
      searchKeys={['reference', 'beneficiaryName']}
      sortField="reference"
      isLoading={isLoading}
    />
  )
}

Props

PropTypeDefaultDescription
columnsColumnDef<TData, TValue>[]—Required. Standard TanStack column defs.
dataTData[]—Required. null and undefined are treated as empty.
searchKeysstring[]—Column ids the search box looks through. Supports dotted paths.
toolbarReactNode—Replaces the built-in search box.
isLoadingbooleanfalseShows a progress bar without hiding current rows.
sortFieldstring—Column id to sort by on first render.
sortDescbooleanfalseDirection for sortField.
tableClassNamestring—Applied to the <Table>; override the 1200px minimum here.

Right for a few hundred rows arriving in one response. Past that, the whole set has to be shipped and held in memory to render one page of it — use Paginated Data Table instead.

Behaviour notes

A # column is prepended automatically, numbered by position in the rendered rows, so the sequence reads 1..N down the page regardless of how the user has sorted.

Search runs over searchKeys, not columns. That is what lets a key name a nested path — 'branch.name' — which no single column owns. It is a case-insensitive substring match.

Sortable headers are buttons, so they are reachable by keyboard and announced as activatable rather than being click-only divs.

Grid view is the same rows, restacked as cards for narrow screens, with column ids humanised into labels.