Ballmac UI home

Data TablePRO

A complete data grid on TanStack Table: sortable headers, search, column visibility, row selection, pagination, a loading state and live result counts.

Status
INV-2045

Lumen Health

ops@lumen.example

Paid
$3,120.00
INV-2043

Harbor & Co

finance@harbor.example

Paid
$2,310.00
INV-2048

Quartz Media

billing@quartz.example

Overdue
$1,980.00
INV-2041

Northwind Studio

billing@northwind.example

Paid
$1,250.00
INV-2050

Sable Design

studio@sable.example

Pending
$1,105.00

1–5 of 10

Page 1 of 2

Installation

  1. Get a Pro licence key.

    The source is part of Ballmac UI Pro.

    Log in with your licence key to read and copy it here, or install it through the shadcn CLI or the MCP server. You own the code once it is in your project.

    $49 once regular price $99for this and every other Pro item. Tax included.Money back if it does not work.

  2. Once per project: add the Pro registry and your licence key.

    components.json
    {
      "registries": {
        "@ballmac": "https://ui.ballmac.com/r/{name}.json",
        "@ballmac-pro": {
          "url": "https://ui.ballmac.com/r/pro/{name}.json",
          "headers": { "Authorization": "Bearer ${BALLMAC_LICENSE_KEY}" }
        }
      }
    }
    .env.local
    BALLMAC_LICENSE_KEY=your-licence-key
  3. Add it.

    $ pnpm dlx shadcn@latest add @ballmac-pro/data-table

Usage

import { DataTable, DataTableColumnHeader } from "@/components/ballmac/data-table"

The full example is in the Code tab above.

Examples

Loading and empty

NameRole

Loading…

Page 1 of 1
NameRole
No members yet. Invite your first teammate to get started.

0 results

Page 1 of 1

API reference

<DataTable>

PropTypeDefault
columns*

Column definitions from TanStack Table. Use `DataTableColumnHeader` in `header` for sortable columns, and `meta: { label: "Name" }` to name a column in the Columns menu.

ColumnDef<TData, TValue>[]—
data*

Rows to display.

TData[]—
label*

Accessible name of the table. Also names the scroll region.

string—
selectable

Add a leading checkbox column for selecting rows.

booleanfalse
onSelectionChange

Called with the selected row objects whenever the selection changes.

(rows: TData[]) => void—
searchable

Show a search field that filters across every column.

booleantrue
searchPlaceholder

Placeholder of the search field.

string—
columnToggle

Show a menu for hiding and showing columns.

booleantrue
pageSize

Rows per page. Set to 0 to disable pagination.

number8
loading

Show placeholder rows while data loads.

booleanfalse
emptyMessage

Message when there are no rows or no matches.

React.ReactNode—
initialSorting

Initial sort, for example `[{ id: "amount", desc: true }]`.

SortingState[]
toolbar

Extra content on the right of the toolbar, such as an export button.

React.ReactNode—
getRowId

Give every row a stable id. Defaults to the row index.

(row: TData, index: number) => string—
stickyHeader

Keep the header visible while the body scrolls. Combine with `maxHeightClassName`.

booleanfalse
maxHeightClassName

Height limit for the scroll area, for example `max-h-96`.

string—

<DataTableColumnHeader>

PropTypeDefault
column*

The column from the header context: `header: ({ column }) => <DataTableColumnHeader column={column} title="Amount" />`.

Column<TData, TValue>—
title*

Visible column title.

string—
numeric

Right-align the title for numeric columns.

boolean—

Also accepts the standard attributes of its root element.

Accessibility

KeyAction
Tab / EnterSort buttons, checkboxes, pagination and the column menu are real controls
Screen readersaria-sort on headers; the result count is a polite live region

Quality scorecard

7/7

Every applicable check passes

Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.0, across 2 examples.

How we measure
  • Passed: Accessibility scan

    No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).

  • Passed: Small screens

    No sideways scrolling at 360, 390 or 1280 px wide.

  • Passed: Reduced motion

    Every endless animation stops when the visitor asks for less motion.

  • Passed: Right to left

    Mirrors correctly in Arabic, Hebrew, Persian and Urdu layouts (0% of elements off the mirror, limit 15%).

  • Passed: Clean console

    No console errors or React hydration errors while loading.

  • Passed: Keyboard

    15 tab stops, each showing a visible change when it takes focus. 2 documented keys.

  • Not applicable: Loading, empty and error

    Does not show data or take submissions.

  • Passed: Automated tests

    Covered by data-table.test.tsx.

  • For information: Footprint

    4.6 KB of source (gzip) in 1 file. Installs @tanstack/react-table, lucide-react.

Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.

Use with AI

Pass columns (TanStack ColumnDef) and data. Use DataTableColumnHeader for sortable headers. selectable adds checkboxes; pageSize sets rows per page. With the shadcn MCP server set up (guide), ask your agent:

Add the Ballmac UI Data Table (@ballmac-pro/data-table) to this project with the shadcn MCP, then use it where it fits.

Use it for

  • Lists of records people search, sort and select
  • Admin and billing screens

Not for

  • A small static table; use table
  • Server-side paging for huge datasets without adapting the parts

Registry JSON (needs your licence key): https://ui.ballmac.com/r/pro/data-table.json

Credits

Based on shadcn/ui Data Table, adapted by Ballmac. Covered by the Ballmac UI Pro license.