DataTable

Composed table experience with toolbar, card view, filters, pagination, and selection.

Quick Preview

Track applicant status, budget, source, and ownership.

Buyer
Customer ID
Email
Status
Budget
Address
Location
Source
Assigned To
Next Action
Date Added
CUS-4823ada.okafor@giddaa.comApproved₦85mNo 5A Beta Glass Road, Off Awolowo Way, Ikoyi, LagosIkoyi, LagosWebsiteMayaSend offerMay 19, 2026
CUS-4824nnamdi.kalu@giddaa.comReview₦64mWisdom Estate, Behind BG Musa Station, Central Business District, AbujaWuse, AbujaReferralTomiSchedule tourMay 20, 2026
CUS-4825zainab.bello@giddaa.comApproved₦120mPlot 14 Aso Drive, Asokoro District, Abuja, Federal Capital TerritoryAsokoro, AbujaAgentIfeVerify docsMay 21, 2026
CUS-4826emeka.eze@giddaa.comReview₦42mNo 23 Admiralty Way, Lekki Phase 1, LagosLekki, LagosInstagramMayaFollow upMay 22, 2026
CUS-4827fatima.musa@giddaa.comApproved₦98mHouse 7, Diplomatic Zone, Maitama, AbujaMaitama, AbujaWebsiteTomiSend invoiceMay 23, 2026

Showing 1 to 5 of 10 entries

Usage

import {
  DataTable,
  DataTableBulkActions,
  DataTableCardGrid,
  DataTableFilter,
  DataTablePageSizeSelect,
  DataTablePagination,
  DataTableRoot,
  DataTableToolbar,
  useDataTable,
  type DataTableColumnDef,
} from "@giddaa-housing/ui/data-table";
import { Button } from "@giddaa-housing/ui/button";
import { TableCard } from "@giddaa-housing/ui/table-card";
import { DataTableViewSelect } from "@/components/recipes/data-table-view-select";

function ApplicantsTable({ columns, data }) {
  const table = useDataTable({
    columns,
    data,
    clientPagination: true,
    enableRowSelection: true,
  });

  return (
    <DataTableRoot table={table}>
      <DataTableToolbar>
        <DataTableFilter
          fields={filterFields}
          onApply={(serialized) => {
            setFilter(serialized);
            table.setPageIndex(0);
          }}
        />
        <DataTableViewSelect view={view} onViewChange={setView} />
        <DataTablePageSizeSelect />
      </DataTableToolbar>
      <DataTable />
      <DataTableBulkActions>
        {({ data }) => <Button>Assign {data.length}</Button>}
      </DataTableBulkActions>
      <DataTablePagination />
    </DataTableRoot>
  );
}

Examples

Default Data Table

Use the primitives to create a product-specific wrapper. The wrapper owns filters, search, routing, export buttons, and API state while the UI package keeps the table layout consistent. This example places Filter inside a toolbar popover and applies the selected status outside the table primitive.

Track applicant status, budget, source, and ownership.

Buyer
Customer ID
Email
Status
Budget
Address
Location
Source
Assigned To
Next Action
Date Added
CUS-4823ada.okafor@giddaa.comApproved₦85mNo 5A Beta Glass Road, Off Awolowo Way, Ikoyi, LagosIkoyi, LagosWebsiteMayaSend offerMay 19, 2026
CUS-4824nnamdi.kalu@giddaa.comReview₦64mWisdom Estate, Behind BG Musa Station, Central Business District, AbujaWuse, AbujaReferralTomiSchedule tourMay 20, 2026
CUS-4825zainab.bello@giddaa.comApproved₦120mPlot 14 Aso Drive, Asokoro District, Abuja, Federal Capital TerritoryAsokoro, AbujaAgentIfeVerify docsMay 21, 2026
CUS-4826emeka.eze@giddaa.comReview₦42mNo 23 Admiralty Way, Lekki Phase 1, LagosLekki, LagosInstagramMayaFollow upMay 22, 2026
CUS-4827fatima.musa@giddaa.comApproved₦98mHouse 7, Diplomatic Zone, Maitama, AbujaMaitama, AbujaWebsiteTomiSend invoiceMay 23, 2026

Showing 1 to 5 of 10 entries

This example also references copy-and-own recipes:

Toolbar Filter

Use DataTableFilter for the common toolbar popover. It composes Filter, Popover, FilterContent, FilterResetButton, and FilterApplyButton; your screen still owns what applying filters does.

<DataTableToolbar>
  <DataTableFilter
    fields={filterFields}
    onApply={(serialized, filters) => {
      setFilter(serialized);
      setStructuredFilters(filters);
      table.setPageIndex(0);
    }}
  />
  <DataTablePageSizeSelect />
</DataTableToolbar>

Props

Prop/APITypeDefaultDescription
useDataTable(options: UseDataTableOptions, selector?)-Creates the TanStack Table v9 instance with the DataTable feature set, Giddaa defaults, and the optional row-selection column. Pass clientPagination to let the table page data itself.
createDataTableColumnHelper<TData>() => ColumnHelper-Column helper bound to the DataTable features, so accessor columns infer their cell value type.
DataTableColumnDefDataTableColumnDef<TData, TValue?>-Column definition type. Use this instead of importing ColumnDef from TanStack.
DataTableRoot{ table, isLoading?, onRowClick? }-Provider/root that shares the TanStack table instance with child components.
DataTableToolbardiv props-Layout shell for search, filters, page-size select, export buttons, or app actions.
DataTableFilterFilter props plus popover/trigger/button overrides-Convenience toolbar popover for filter rows. Calls onApply; does not mutate table rows, fetch data, or write URL params for you.
DataTable{ table?, isLoading?, emptyState? }-Styled table renderer using the shared TanStack instance.
DataTableCardGrid{ renderCard?, titleColumnId?, detailColumnIds? }-Card-grid renderer using the shared TanStack instance. Use renderCard for product-specific card layouts.
DataTableBulkActionsrender prop or node-Sticky bulk-action bar shown when rows are selected.
DataTablePagination{ table?, page?, pageSize?, pageCount?, totalEntries?, onPageChange?, showControls?, controlAppearance?, showJumpToPage? }-Pagination footer with entry summary, page controls, and jump-to-page. Reads TanStack pagination state by default, or drive it from API state.
DataTablePageSizeSelect{ table?, pageSizeOptions?, pageSize?, onPageSizeChange?, label? }-Page-size select. Reads TanStack state by default, or drive it from API state with pageSize + onPageSizeChange.

Pagination

Pagination and page size can be driven two ways. Both use the same DataTablePagination and DataTablePageSizeSelect components — pick per screen based on where the source of truth lives.

Client-side (TanStack owns pagination)

When the table has all the rows, set clientPagination and TanStack slices, counts, and navigates for you. The controls bind to the table instance automatically (via prop or DataTableRoot context):

const table = useDataTable({
  columns,
  data, // full dataset
  clientPagination: true,
});

<DataTablePageSizeSelect /> // reads/writes table.setPageSize
<DataTablePagination />     // reads/writes table.setPageIndex

Without clientPagination the table renders every row in data, which is what you want when data is already one page from the API.

Server-side (API owns pagination)

Real screens usually fetch one page at a time and get page, pageSize, and a total count back from the API. There are two supported approaches:

A — Controlled TanStack. Keep using the table instance but let your API be the source of truth. TanStack won't slice data; it just tracks state and reports getPageCount() from rowCount:

const table = useDataTable({
  columns,
  data: pageRows, // only the current page from the API
  rowCount: totalCount, // total across all pages, from the API
  state: { pagination: { pageIndex: page - 1, pageSize } },
  onPaginationChange: (updater) => {
    const next =
      typeof updater === "function"
        ? updater({ pageIndex: page - 1, pageSize })
        : updater;
    setPage(next.pageIndex + 1);
    setPageSize(next.pageSize);
  },
});

<DataTablePageSizeSelect />
<DataTablePagination />

B — Fully controlled (no table wiring). If pagination lives entirely in your API/query state and you don't want to thread it through TanStack, pass the values directly. In this mode neither control touches the table instance:

<DataTablePageSizeSelect
  pageSize={pageSize}
  onPageSizeChange={(size) => {
    setPageSize(size);
    setPage(1); // reset to first page on size change
  }}
/>
<DataTablePagination
  page={page}           // 1-based current page
  pageSize={pageSize}
  totalEntries={totalCount}
  onPageChange={setPage} // called with the next 1-based page
/>

Notes:

  • page is 1-based; TanStack's internal pageIndex is 0-based. The controlled props and onPageChange all speak 1-based pages so they map directly to typical API params.
  • Pass totalEntries + pageSize to render the "Showing 11 to 20 of 132 entries" summary and derive page count. If your API already returns a page count, pass pageCount too.
  • Use showControls, showPreviousNext, showJumpToPage, and showSummary to hide footer sections per screen.
  • Use controlAppearance="icon" for compact previous/next buttons or controlAppearance="control" for labelled Previous/Next buttons.
  • DataTablePagination renders nothing when pageCount <= 1, in either mode.
  • Reset to page 1 when the page size, search, or filters change so you don't request an out-of-range page.

Columns

Type column lists with DataTableColumnDef. Column options are TanStack's own (size, enableSorting, enablePinning, enableResizing, enableHiding), plus the DataTable meta keys.

const columns: DataTableColumnDef<Applicant>[] = [
  {
    accessorKey: "name",
    header: "Buyer",
    meta: { isPinned: true, pinPosition: "start", useAsCardTitle: true },
  },
  { accessorKey: "budget", header: "Budget" },
];

pinPosition takes "start" or "end", which follow the reading direction, so a pinned column lands on the correct side in right-to-left layouts. "left" and "right" are accepted as aliases for them.

When a cell needs its value typed, build the list with the column helper instead:

const column = createDataTableColumnHelper<Applicant>();

const columns = column.columns([
  column.accessor("budget", {
    header: "Budget",
    cell: ({ getValue }) => formatCurrency(getValue()), // getValue() is a number
  }),
]);

Column resizing is live by default (columnResizeMode: "onChange"). Shift-click a row checkbox to select the range back to the last row you toggled.

Reading table state

The component that calls useDataTable does not re-render when table state changes. Each DataTable component subscribes to the state it shows, so selecting a row, sorting, paging, or dragging a column wider leaves your toolbar, filters, and the rest of the screen alone.

Event handlers can read and write the table at any time:

<DataTableFilter onApply={() => table.setPageIndex(0)} />

To use table state while rendering your own UI, select it in the second argument and read it from table.state. The component then re-renders only when that selection changes:

const table = useDataTable(options, (state) => ({
  rowSelection: state.rowSelection,
}));

const selectedCount = Object.keys(table.state.rowSelection).length;

Or subscribe a small part of the tree with table.Subscribe:

<table.Subscribe selector={(state) => state.sorting}>
  {(sorting) => <SortSummary sorting={sorting} />}
</table.Subscribe>

Calling table.getSelectedRowModel() or reading table.atoms.pagination.get() directly in render gives the current value but will not re-render when it changes.

Migrating from TanStack Table v8

@giddaa-housing/ui now ships TanStack Table v9 as its own dependency. Remove @tanstack/react-table from your app's package.json and import the DataTable types from @giddaa-housing/ui/data-table instead. An app that still builds its own tables on TanStack v8 can keep that version installed; the two do not conflict.

BeforeAfter
import type { ColumnDef } from "@tanstack/react-table" and ColumnDef<TData>DataTableColumnDef<TData> from @giddaa-housing/ui/data-table
Row<TData>, Table<TData> from TanStackDataTableRow<TData>, DataTableInstance<TData>
PaginationState, SortingState, RowSelectionState, Updater from TanStackDataTablePaginationState, DataTableSortingState, DataTableRowSelectionState, DataTableUpdater
getPaginationRowModel: getPaginationRowModel()clientPagination: true
getSortedRowModel, getCoreRowModel optionsRemove them; both are built in
manualPagination: trueOptional; it is the default unless clientPagination is set
columnResizeMode: "onChange"Optional; it is the default
table.getState().pagination in renderuseDataTable(options, (state) => ({ pagination: state.pagination })), then table.state.pagination
initialState.columnPinning: { left, right }{ start, end }
column.pin("left"), getIsPinned() === "left""start" / "end"
sortingFn on a columnsortFn
declare module "@tanstack/react-table" { interface ColumnMeta … }Remove it for DataTable columns; meta is typed by DataTableColumnMeta

Filtering, grouping, expanding, and faceting are not part of the DataTable feature set. Keep filtering in your API or in the data you pass in.

Views

Keep view switching in your application wrapper. The root provides the TanStack table once, then each view can render the same row model differently.

Use the DataTableViewSelect recipe when you want the standard toolbar select for list/card switching.

<DataTableRoot table={table}>
  <DataTableToolbar>{/* view toggle, filters, search */}</DataTableToolbar>
  {view === "list" ? <DataTable /> : null}
  {view === "card" ? (
    <DataTableCardGrid
      renderCard={(row, { action, selection }) => (
        <TableCard
          action={action}
          selection={selection}
          title={row.original.name}
          subtitle={row.original.email}
          details={[
            { label: "Budget", value: row.original.budget },
            { label: "Location", value: row.original.location },
          ]}
        />
      )}
    />
  ) : null}
  {view === "kanban" ? <ApplicantKanban table={table} /> : null}
  <DataTablePagination />
</DataTableRoot>

For simple card views, you can map columns directly:

<DataTableCardGrid
  titleColumnId="name"
  subtitleColumnId="email"
  badgeColumnId="status"
  detailColumnIds={["budget", "location", "assignedTo"]}
/>

For richer screens, prefer renderCard. This avoids forcing your table columns to match the card layout, especially when title and subtitle are composed inside the same table cell. Kanban should stay app-owned until the interaction model stabilizes; it can consume useDataTableContext() or the same table instance.

Accessibility

  • Provide accessible column headers and row action labels.
  • Keep router search params, API fetching, and product filters in the application wrapper.
  • Keep row click behavior separate from interactive controls inside cells.

On this page