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 | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ada Okaforada.okafor@giddaa.com | CUS-4823 | ada.okafor@giddaa.com | Approved | ₦85m | No 5A Beta Glass Road, Off Awolowo Way, Ikoyi, Lagos | Ikoyi, Lagos | Website | Maya | Send offer | May 19, 2026 | ||
Nnamdi Kalunnamdi.kalu@giddaa.com | CUS-4824 | nnamdi.kalu@giddaa.com | Review | ₦64m | Wisdom Estate, Behind BG Musa Station, Central Business District, Abuja | Wuse, Abuja | Referral | Tomi | Schedule tour | May 20, 2026 | ||
Zainab Bellozainab.bello@giddaa.com | CUS-4825 | zainab.bello@giddaa.com | Approved | ₦120m | Plot 14 Aso Drive, Asokoro District, Abuja, Federal Capital Territory | Asokoro, Abuja | Agent | Ife | Verify docs | May 21, 2026 | ||
Emeka Ezeemeka.eze@giddaa.com | CUS-4826 | emeka.eze@giddaa.com | Review | ₦42m | No 23 Admiralty Way, Lekki Phase 1, Lagos | Lekki, Lagos | Maya | Follow up | May 22, 2026 | |||
Fatima Musafatima.musa@giddaa.com | CUS-4827 | fatima.musa@giddaa.com | Approved | ₦98m | House 7, Diplomatic Zone, Maitama, Abuja | Maitama, Abuja | Website | Tomi | Send invoice | May 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 | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ada Okaforada.okafor@giddaa.com | CUS-4823 | ada.okafor@giddaa.com | Approved | ₦85m | No 5A Beta Glass Road, Off Awolowo Way, Ikoyi, Lagos | Ikoyi, Lagos | Website | Maya | Send offer | May 19, 2026 | ||
Nnamdi Kalunnamdi.kalu@giddaa.com | CUS-4824 | nnamdi.kalu@giddaa.com | Review | ₦64m | Wisdom Estate, Behind BG Musa Station, Central Business District, Abuja | Wuse, Abuja | Referral | Tomi | Schedule tour | May 20, 2026 | ||
Zainab Bellozainab.bello@giddaa.com | CUS-4825 | zainab.bello@giddaa.com | Approved | ₦120m | Plot 14 Aso Drive, Asokoro District, Abuja, Federal Capital Territory | Asokoro, Abuja | Agent | Ife | Verify docs | May 21, 2026 | ||
Emeka Ezeemeka.eze@giddaa.com | CUS-4826 | emeka.eze@giddaa.com | Review | ₦42m | No 23 Admiralty Way, Lekki Phase 1, Lagos | Lekki, Lagos | Maya | Follow up | May 22, 2026 | |||
Fatima Musafatima.musa@giddaa.com | CUS-4827 | fatima.musa@giddaa.com | Approved | ₦98m | House 7, Diplomatic Zone, Maitama, Abuja | Maitama, Abuja | Website | Tomi | Send invoice | May 23, 2026 |
Showing 1 to 5 of 10 entries
This example also references copy-and-own recipes:
- DataTableViewSelect for the toolbar list/card view switcher.
- ActionsMenu for row and card actions.
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/API | Type | Default | Description |
|---|---|---|---|
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. |
DataTableColumnDef | DataTableColumnDef<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. |
DataTableToolbar | div props | - | Layout shell for search, filters, page-size select, export buttons, or app actions. |
DataTableFilter | Filter 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. |
DataTableBulkActions | render 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.setPageIndexWithout 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:
pageis 1-based; TanStack's internalpageIndexis 0-based. The controlled props andonPageChangeall speak 1-based pages so they map directly to typical API params.- Pass
totalEntries+pageSizeto render the "Showing 11 to 20 of 132 entries" summary and derive page count. If your API already returns a page count, passpageCounttoo. - Use
showControls,showPreviousNext,showJumpToPage, andshowSummaryto hide footer sections per screen. - Use
controlAppearance="icon"for compact previous/next buttons orcontrolAppearance="control"for labelled Previous/Next buttons. DataTablePaginationrenders nothing whenpageCount <= 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.
| Before | After |
|---|---|
import type { ColumnDef } from "@tanstack/react-table" and ColumnDef<TData> | DataTableColumnDef<TData> from @giddaa-housing/ui/data-table |
Row<TData>, Table<TData> from TanStack | DataTableRow<TData>, DataTableInstance<TData> |
PaginationState, SortingState, RowSelectionState, Updater from TanStack | DataTablePaginationState, DataTableSortingState, DataTableRowSelectionState, DataTableUpdater |
getPaginationRowModel: getPaginationRowModel() | clientPagination: true |
getSortedRowModel, getCoreRowModel options | Remove them; both are built in |
manualPagination: true | Optional; it is the default unless clientPagination is set |
columnResizeMode: "onChange" | Optional; it is the default |
table.getState().pagination in render | useDataTable(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 column | sortFn |
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.