table

A responsive table component.

Philosophy

HTML tables are semantically powerful but visually bland. Our Table components add consistent styling while preserving the native table structure - <table>, <thead>, <tbody>, <tr>, <th>, <td> - because screen readers depend on these elements for data navigation. For interactive features like sorting and filtering, see Data Table.

How It's Built

Loading diagram...

Installation

npx @gentleduck/cli add table

npx @gentleduck/cli add table

Usage

import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"

<Table>
  <TableCaption>A list of your recent invoices.</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead className="w-[100px]">Invoice</TableHead>
      <TableHead>Status</TableHead>
      <TableHead>Method</TableHead>
      <TableHead className="text-right">Amount</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell className="font-medium">INV001</TableCell>
      <TableCell>Paid</TableCell>
      <TableCell>Credit Card</TableCell>
      <TableCell className="text-right">$250.00</TableCell>
    </TableRow>
  </TableBody>
</Table>

Examples

Data Table

You can use the <Table /> component to build more complex data tables. Combine it with TanStack Table to add sorting, filtering, and pagination.

See the Data Table documentation for a full guide.

You can also see data-table examples in the Blocks Library.

Component Composition

Loading diagram...

RTL Support

Set the direction once with DirectionProvider (or <html dir="rtl">) and the table follows it: cells align to the start side. No dir prop or rtl: classes needed.

Motion

Alpha: Motion Compositions

Motion components work standalone, but some compositions may behave unexpectedly: this is still under active development. If you find a broken composition, please file an issue.

Use MotionTable and MotionTableRow for staggered entrance animations powered by motion. The table uses a scaleIn entrance (fade, scale, and blur) with a bouncy spring transition, and each row staggers by 50ms via the index prop.

Requires the motion package. Use MotionTable instead of Table and MotionTableRow instead of TableRow. All other sub-components stay the same. The regular components are perfectly fine - this is an optional enhancement.

API Reference

Table

Prop	Type	Default	Description
`dir`	`'ltr' \| 'rtl'`	-	Text direction override. Resolved via `useDirection` (`dir` prop -> `DirectionProvider` -> `<html dir>`).
`className`	`string`	-	Additional CSS class names
`children`	`React.ReactNode`	-	Table content (`TableHeader`, `TableBody`, `TableFooter`, `TableCaption`)
`...props`	`React.HTMLProps<HTMLTableElement>`	-	Additional props to spread to the table element

TableHeader

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS class names
`children`	`React.ReactNode`	-	Header rows
`...props`	`React.HTMLProps<HTMLTableSectionElement>`	-	Additional props to spread to the thead element

TableBody

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS class names
`children`	`React.ReactNode`	-	Body rows
`...props`	`React.HTMLProps<HTMLTableSectionElement>`	-	Additional props to spread to the tbody element

TableFooter

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS class names
`children`	`React.ReactNode`	-	Footer rows
`...props`	`React.HTMLProps<HTMLTableSectionElement>`	-	Additional props to spread to the tfoot element

TableRow

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS class names
`children`	`React.ReactNode`	-	Row cells (`TableHead` or `TableCell`)
`...props`	`React.HTMLProps<HTMLTableRowElement>`	-	Additional props to spread to the tr element

TableHead

Prop	Type	Default	Description
`scope`	`string`	`'col'`	HTML `scope` attribute for accessibility
`className`	`string`	-	Additional CSS class names
`children`	`React.ReactNode`	-	Header cell content
`...props`	`React.ThHTMLAttributes<HTMLTableCellElement>`	-	Additional props to spread to the th element

TableCell

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS class names
`children`	`React.ReactNode`	-	Cell content
`...props`	`React.TdHTMLAttributes<HTMLTableCellElement>`	-	Additional props to spread to the td element

TableCaption

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS class names
`children`	`React.ReactNode`	-	Caption text
`...props`	`React.HTMLProps<HTMLTableCaptionElement>`	-	Additional props to spread to the caption element

MotionTable

scaleIn entrance (fade, scale, and blur) with springBouncy transition on mount. Requires the motion package.

Prop	Type	Default	Description
`...props`	`TableProps`	-	All props from `Table` are supported

MotionTableRow

Staggered scaleIn entrance (fade, scale, and blur) with springBouncy transition. Requires the motion package.

Prop	Type	Default	Description
`index`	`number`	`0`	Stagger delay index (50ms per index) for entrance animation
`...props`	`TableRowProps`	-	All props from `TableRow` are supported