Table

A data table with automatic column detection, horizontal-only separators, and a compound sub-component API for full layout control.

Table


 Recent invoices
  Invoice   Status    Qty      Amount
 ─────────────────────────────────────
  INV001    Paid      2       $500.00
 ─────────────────────────────────────
  INV002    Pending   1       $150.00
 ─────────────────────────────────────
  INV003    Overdue   3       $750.00
 ─────────────────────────────────────
  Total                     $1,400.00

Run demo

Terminal

bunx @gridland/demo table

Terminal

bunx @gridland/demo table

Terminal

curl -fsSL https://raw.githubusercontent.com/thoughtfulllc/gridland/main/scripts/run-demo.sh | bash -s table

Terminal

curl -fsSL https://raw.githubusercontent.com/thoughtfulllc/gridland/main/scripts/run-demo.sh | bash -s table

Installation

Terminal

bunx create-gridland add table

Usage

import { Table } from "@/components/ui/table"

<Table
  data={[
    { name: "Alice", role: "Engineer", status: "Active" },
    { name: "Bob", role: "Designer", status: "Active" },
    { name: "Charlie", role: "PM", status: "Away" },
  ]}
/>

Examples

Custom Columns

Select and order which columns to display.

Custom columns

<Table
  data={[
    { name: "Alice", age: 30, role: "Engineer" },
    { name: "Bob", age: 25, role: "Designer" },
  ]}
  columns={["name", "role"]}
/>

Custom Colors

Override the default header and separator colors.

Custom colors

<Table
  data={[
    { name: "Alice", role: "Engineer" },
    { name: "Bob", role: "Designer" },
  ]}
  headerColor="cyan"
  borderColor="#5e81ac"
/>

Compound API

For full layout control, use TableRoot with sub-components.

Compound table

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

<TableRoot>
  <TableCaption>A list of your recent invoices.</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead>Invoice</TableHead>
      <TableHead>Status</TableHead>
      <TableHead>Amount</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>INV001</TableCell>
      <TableCell>Paid</TableCell>
      <TableCell>$250.00</TableCell>
    </TableRow>
  </TableBody>
  <TableFooter>
    <TableRow>
      <TableCell>Total</TableCell>
      <TableCell></TableCell>
      <TableCell>$250.00</TableCell>
    </TableRow>
  </TableFooter>
</TableRoot>

Cell Alignment

Right-align or center-align individual cells using the align prop.

Right-aligned prices

<TableRoot>
  <TableHeader>
    <TableRow>
      <TableHead>Item</TableHead>
      <TableHead align="right">Price</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Widget</TableCell>
      <TableCell align="right">$10.00</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>Gadget</TableCell>
      <TableCell align="right">$25.00</TableCell>
    </TableRow>
  </TableBody>
</TableRoot>

Cell Color

Override the text color for individual cells.

Colored status cells

<TableRoot>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Status</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Alice</TableCell>
      <TableCell color="green">Active</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>Bob</TableCell>
      <TableCell color="red">Inactive</TableCell>
    </TableRow>
  </TableBody>
</TableRoot>

Column Span

Use colSpan to span a cell across multiple columns.

Footer with colSpan

<TableRoot>
  <TableHeader>
    <TableRow>
      <TableHead>Item</TableHead>
      <TableHead>Qty</TableHead>
      <TableHead align="right">Price</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Widget</TableCell>
      <TableCell>2</TableCell>
      <TableCell align="right">$20.00</TableCell>
    </TableRow>
  </TableBody>
  <TableFooter>
    <TableRow>
      <TableCell colSpan={2}>Total</TableCell>
      <TableCell align="right">$20.00</TableCell>
    </TableRow>
  </TableFooter>
</TableRoot>

Compound Components

Component	Description
`TableRoot`	Compound root — computes column widths and provides layout context
`TableHeader`	Wraps header rows with a solid separator below
`TableBody`	Wraps body rows with dimmed separators between them
`TableFooter`	Wraps footer rows with a solid separator above
`TableRow`	Reads `TableHead`/`TableCell` children and renders a styled row
`TableHead`	Header cell — does not render on its own
`TableCell`	Body cell — does not render on its own
`TableCaption`	Muted caption text below the table

API Reference

Data-driven table with automatic column detection.

Prop	Type	Default	Description
`data`	`T[]`	-	Array of data objects to display
`columns`	`(keyof T)[]`	-	Keys to display as columns (auto-detected if omitted)
`padding`	`number`	`1`	Cell padding in characters
`headerColor`	`string`	`theme.foreground`	Header text color
`borderColor`	`string`	`theme.muted`	Separator line color

TableRoot

Compound root that computes column widths from the component tree.

Prop	Type	Default	Description
`children`	`ReactNode`	-	Table sub-components
`padding`	`number`	`1`	Cell padding in characters
`headerColor`	`string`	`theme.foreground`	Header text color
`borderColor`	`string`	`theme.muted`	Separator line color

TableHeader

Prop	Type	Default	Description
`children`	`ReactNode`	-	One or more `TableRow` components

TableBody

Prop	Type	Default	Description
`children`	`ReactNode`	-	One or more `TableRow` components

TableFooter

Prop	Type	Default	Description
`children`	`ReactNode`	-	One or more `TableRow` components

TableRow

Prop	Type	Default	Description
`children`	`ReactNode`	-	`TableHead` or `TableCell` components

TableHead

Prop	Type	Default	Description
`children`	`ReactNode`	-	Cell content (typically a string)
`align`	`"left" \| "right" \| "center"`	`"left"`	Text alignment within the cell
`color`	`string`	-	Override text color for this header cell
`colSpan`	`number`	`1`	Number of columns this cell should span

TableCell

Prop	Type	Default	Description
`children`	`ReactNode`	-	Cell content (typically a string)
`align`	`"left" \| "right" \| "center"`	`"left"`	Text alignment within the cell
`color`	`string`	-	Override text color for this body cell
`colSpan`	`number`	`1`	Number of columns this cell should span

TableCaption

Prop	Type	Default	Description
`children`	`ReactNode`	-	Caption text

Table

Run demo

On this page