Component

Table

The default table for AG. A fully-featured table powered by TanStack Table v8 with sorting, search, pagination, row selection, column visibility, and type-aware per-column filters, all styled with AG tokens.

Installation

Install from the live registry into any shadcn-initialized app (another project). Prefer installing ag-globals first so AG tokens and fonts are present.

npx shadcn@latest add https://design.ag.org/r/table

Usage

Use Table for any tabular data. Enable only the interactions you need (sort, filter, paginate, select) and turn the rest off for simple, read-only tables.

Composition

input button checkbox pagination dropdown-menu calendar select

Playground

Preview


INV-001	Acme Corp	Paid	$250.00	1/12/2024
INV-002	Globex	Pending	$1200.00	3/4/2024
INV-003	Initech	Paid	$820.00	5/21/2024
INV-004	Umbrella	Overdue	$430.00	7/9/2024

6 rows

Configure

Column filters

Yes

Demo the per-column filters (text, select, range, date-range).

Searchable

Show a search input in the toolbar.

Pagination

Yes

Show pagination controls below the table.

Selectable

Prepend a checkbox column for row selection.

Column visibility

Show a dropdown to toggle column visibility.

Code

import { DataTable, type ColumnDef } from "@/components/ui/data-table"

// Declare a per-column filter by setting meta.filterVariant on the column def.
type Invoice = {
  invoice: string
  customer: string
  status: string
  amount: number
  joined: Date
}

const columns: ColumnDef<Invoice>[] = [
  { accessorKey: "invoice", header: "Invoice" },
  { accessorKey: "customer", header: "Customer", meta: { filterVariant: "text" } },
  { accessorKey: "status", header: "Status", meta: { filterVariant: "select" } },
  {
    accessorKey: "amount",
    header: "Amount",
    cell: (info) => `$${(info.getValue() as number).toFixed(2)}`,
    meta: { filterVariant: "range" },
  },
  {
    accessorKey: "joined",
    header: "Joined",
    cell: (info) => (info.getValue() as Date).toLocaleDateString(),
    meta: { filterVariant: "date-range" },
  },
]

const data: Invoice[] = [
  { invoice: "INV-001", customer: "Acme Corp", status: "Paid", amount: 250, joined: new Date("2024-01-12") },
  { invoice: "INV-002", customer: "Globex", status: "Pending", amount: 1200, joined: new Date("2024-03-04") },
  { invoice: "INV-003", customer: "Initech", status: "Paid", amount: 820, joined: new Date("2024-05-21") },
]

<DataTable columns={columns} data={data} pagination />

Variants & States

Supported variants, sizes, and interaction states for this component.

Configurations

With title
With footer

Props

Prop	Type	Default value	Description
columns	ColumnDef<TData>[]	,	Column definitions. Use createColumnHelper<TData>() for full type inference.
data	TData[]	,	Array of row objects to render.
searchable	boolean \| string	false	true enables a global filter; a column id filters that single column.
pagination	boolean	false	Show pagination controls.
pageSize	number	10	Rows per page when pagination is enabled.
selectable	boolean	false	Prepend a per-row selection checkbox column.
onSelectionChange	(selected: TData[]) => void	,	Fires with the selected row objects whenever selection changes.
columnVisibility	boolean	false	Show a column visibility toggle dropdown.
column.meta.filterVariant	"text" \| "select" \| "multi-select" \| "range" \| "date-range"	,	Set on a column def to render a type-appropriate filter control in the toolbar. Omit for no per-column filter.
column.meta.filterLabel	string	,	Optional human label for a column's filter control (defaults to the column header/id).

Do

Define columns with createColumnHelper for full type safety
Declare meta.filterVariant per column to give each filter the right control
Enable pagination for large datasets rather than rendering every row
Provide a meaningful title so the table has an accessible caption

Don't

Don't enable heavy features (filters, pagination) for a handful of static rows
Don't hide the search input when there are many rows
Don't use a range filter on non-numeric columns, use select instead
Don't put unrelated data in a single table, split into multiple tables