Skip to content

Design system

Documentation

DesignComponents / Table

Components / Table

Stable

Table

Use Table for genuinely tabular data where captions, headers, row relationships, and cell semantics help people compare records.

On this page

Examples

Semantic table

Compound parts preserve headers, rows, and cells as native table elements.

ProjectOwnerStatus
Atlas onboardingMai NguyenActive
Orbit billingPhuc TranInvited

Date-range filtering

Stage labeled date inputs and apply an inclusive range without changing Table semantics.

Showing 2 projects in the selected range.

ProjectOwnerLast updated
Atlas onboardingMai Nguyen
Orbit billingPhuc Tran

Fixed header and columns

Pin the header while scrolling vertically and the project column while scrolling horizontally inside one bounded region.

ProjectOwnerStatusTeamRegionHealthLast updatedNotes
Atlas onboardingMai NguyenActiveGrowthAPACOn trackTodayReview activity and recent changes
Orbit billingPhuc TranInvitedFinanceEUNeeds reviewYesterdayReview activity and recent changes
Lumen researchLinh DoPausedResearchUSBlocked2 days agoReview activity and recent changes
Nova supportAn LeActiveSupportAPACOn track3 days agoReview activity and recent changes
Terra migrationBao NguyenReviewPlatformUSNeeds review4 days agoReview activity and recent changes
Helios analyticsQuynh TranActiveInsightsEUOn track5 days agoReview activity and recent changes
Cinder launchMinh PhamPausedMarketingAPACBlocked6 days agoReview activity and recent changes
Sora workspaceThao VuActiveOperationsUSOn track7 days agoReview activity and recent changes

Numeric alignment

Right-align numeric values while keeping the row and column meaning explicit.

MonthEventsChange
August18,420+12%
July16,445—

Loading, error, and empty

Use an overlay spinner, an actionable error alert, and a centered empty state without changing table semantics.

ProjectStatus
Loading projects…
Loading projects…

No data

There are no projects to display yet.

Row selection

Checkboxes can compose with Table while select-all remains scoped to visible rows.

Project
Atlas onboarding
Orbit billing
Lumen research

Wide and long content

A surrounding scroll region protects narrow screens without changing table semantics.

Workspace recordOwnerLast updated
Workspace record with a deliberately long label 1A long owner name that remains readableToday
Workspace record with a deliberately long label 2A long owner name that remains readableToday
Workspace record with a deliberately long label 3A long owner name that remains readableToday
Workspace record with a deliberately long label 4A long owner name that remains readableToday
Workspace record with a deliberately long label 5A long owner name that remains readableToday

When to use

Use Table when rows and columns have stable relationships. Use a list or Card composition when each item is a standalone task or when the content does not compare naturally across columns.

Usage

table-basic.tsx
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@phuctech/ui/components/table";

const rows = [
  ["Atlas onboarding", "Mai Nguyen", "Active"],
  ["Orbit billing", "Phuc Tran", "Invited"],
];

export function Example() {
  return (
    <div className="scrollbar-hover-reveal w-full overflow-x-auto rounded-lg border border-border">
      <Table className="min-w-[34rem]">
        <TableHeader><TableRow><TableHead>Project</TableHead><TableHead>Owner</TableHead><TableHead>Status</TableHead></TableRow></TableHeader>
        <TableBody>{rows.map(([project, owner, status]) => <TableRow key={project}><TableCell className="font-medium">{project}</TableCell><TableCell>{owner}</TableCell><TableCell>{status}</TableCell></TableRow>)}</TableBody>
      </Table>
    </div>
  );
}

The component parts render native table elements at the shared md density. Put the horizontal overflow boundary around the table in a narrow layout; do not replace table semantics with a grid of divs.

Composition

  • Use TableCaption when the data set needs an explicit name for assistive technology; it is optional when the surrounding heading already provides that context.
  • TableHead defaults to scope="col"; pass scope="row" for row headers.
  • TableRow selected exposes data-state="selected" for a selected row.
  • Use colSpan, aria-sort, and other native attributes directly on the relevant parts.

Fixed header and columns

For a wide table, put one bounded overflow-auto region around the table. Use TableHeader sticky to keep the header visible during vertical scrolling, then apply sticky left-0, an opaque background, and a higher stacking order to the first TableHead and TableCell to keep that column visible during horizontal scrolling. The pinned corner cell must sit above both scroll directions.

table-fixed-header-columns.tsx
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@phuctech/ui/components/table";

const rows = [
  { id: "atlas", project: "Atlas onboarding", owner: "Mai Nguyen", status: "Active", team: "Growth", region: "APAC", health: "On track", updatedAt: "Today" },
  { id: "orbit", project: "Orbit billing", owner: "Phuc Tran", status: "Invited", team: "Finance", region: "EU", health: "Needs review", updatedAt: "Yesterday" },
  { id: "lumen", project: "Lumen research", owner: "Linh Do", status: "Paused", team: "Research", region: "US", health: "Blocked", updatedAt: "2 days ago" },
  { id: "nova", project: "Nova support", owner: "An Le", status: "Active", team: "Support", region: "APAC", health: "On track", updatedAt: "3 days ago" },
  { id: "terra", project: "Terra migration", owner: "Bao Nguyen", status: "Review", team: "Platform", region: "US", health: "Needs review", updatedAt: "4 days ago" },
  { id: "helios", project: "Helios analytics", owner: "Quynh Tran", status: "Active", team: "Insights", region: "EU", health: "On track", updatedAt: "5 days ago" },
  { id: "cinder", project: "Cinder launch", owner: "Minh Pham", status: "Paused", team: "Marketing", region: "APAC", health: "Blocked", updatedAt: "6 days ago" },
  { id: "sora", project: "Sora workspace", owner: "Thao Vu", status: "Active", team: "Operations", region: "US", health: "On track", updatedAt: "7 days ago" },
];

const pinnedColumnClass = "sticky left-0 z-10 border-r border-border bg-background";
const pinnedHeaderClass = "sticky left-0 z-30 border-r border-border bg-background";

export function Example() {
  return (
    <div className="scrollbar-hover-reveal max-h-64 max-w-full overflow-auto rounded-lg border border-border">
      <Table className="min-w-[72rem]">
        <TableHeader sticky className="z-20">
          <TableRow>
            <TableHead className={pinnedHeaderClass}>Project</TableHead>
            <TableHead>Owner</TableHead>
            <TableHead>Status</TableHead>
            <TableHead>Team</TableHead>
            <TableHead>Region</TableHead>
            <TableHead>Health</TableHead>
            <TableHead>Last updated</TableHead>
            <TableHead>Notes</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {rows.map((row) => (
            <TableRow key={row.id}>
              <TableCell className={`${pinnedColumnClass} font-medium`}>{row.project}</TableCell>
              <TableCell>{row.owner}</TableCell>
              <TableCell>{row.status}</TableCell>
              <TableCell>{row.team}</TableCell>
              <TableCell>{row.region}</TableCell>
              <TableCell>{row.health}</TableCell>
              <TableCell>{row.updatedAt}</TableCell>
              <TableCell>Review activity and recent changes</TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  );
}

Date-range filtering

When records have a meaningful date, compose Table with two labeled Input type="date" controls and a submit action. Keep draft dates local, apply both values together, and derive the visible rows from the applied range so a partial edit does not trigger a request or change the table unexpectedly.

table-date-range.tsx
"use client";

import { useState } from "react";

import { Button } from "@phuctech/ui/components/button";
import { Input } from "@phuctech/ui/components/input";
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@phuctech/ui/components/table";

const rows = [
  { id: "atlas", project: "Atlas onboarding", owner: "Mai Nguyen", updatedAt: "2026-08-12" },
  { id: "orbit", project: "Orbit billing", owner: "Phuc Tran", updatedAt: "2026-08-19" },
  { id: "lumen", project: "Lumen research", owner: "Linh Do", updatedAt: "2026-09-03" },
];

function formatDate(date: string) {
  const [year, month, day] = date.split("-");
  return `${day}/${month}/${year}`;
}

export function Example() {
  const [draftFrom, setDraftFrom] = useState("2026-08-01");
  const [draftTo, setDraftTo] = useState("2026-08-31");
  const [from, setFrom] = useState("2026-08-01");
  const [to, setTo] = useState("2026-08-31");
  const visibleRows = rows.filter(
    (row) => (!from || row.updatedAt >= from) && (!to || row.updatedAt <= to),
  );

  return (
    <div className="grid gap-3">
      <form
        className="grid gap-3 sm:grid-cols-[minmax(0,1fr)_minmax(0,1fr)_auto] sm:items-end"
        onSubmit={(event) => {
          event.preventDefault();
          setFrom(draftFrom);
          setTo(draftTo);
        }}
      >
        <label className="grid gap-1.5 text-sm font-medium" htmlFor="table-date-range-from">
          From date
          <Input
            id="table-date-range-from"
            type="date"
            value={draftFrom}
            onChange={(event) => setDraftFrom(event.target.value)}
          />
        </label>
        <label className="grid gap-1.5 text-sm font-medium" htmlFor="table-date-range-to">
          To date
          <Input
            id="table-date-range-to"
            type="date"
            value={draftTo}
            onChange={(event) => setDraftTo(event.target.value)}
          />
        </label>
        <Button type="submit">Apply date range</Button>
      </form>
      <p aria-live="polite" className="text-sm text-muted-foreground">
        Showing {visibleRows.length} {visibleRows.length === 1 ? "project" : "projects"} in the selected range.
      </p>
      <div className="scrollbar-hover-reveal w-full overflow-x-auto rounded-lg border border-border">
        <Table className="min-w-[40rem]">
          <TableHeader>
            <TableRow>
              <TableHead>Project</TableHead>
              <TableHead>Owner</TableHead>
              <TableHead>Last updated</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {visibleRows.length > 0 ? (
              visibleRows.map((row) => (
                <TableRow key={row.id}>
                  <TableCell className="font-medium">{row.project}</TableCell>
                  <TableCell>{row.owner}</TableCell>
                  <TableCell>
                    <time dateTime={row.updatedAt}>{formatDate(row.updatedAt)}</time>
                  </TableCell>
                </TableRow>
              ))
            ) : (
              <TableRow>
                <TableCell colSpan={3} className="py-8 text-center text-muted-foreground">
                  No projects in this date range.
                </TableCell>
              </TableRow>
            )}
          </TableBody>
        </Table>
      </div>
    </div>
  );
}

Sorting and controlled state

Table stays a semantic rendering primitive and does not own sorting, filtering, paging, selection, or requests. Keep those states in the feature that owns the records. The Data Table pattern composes the public table parts with staged filters, keyboard-accessible sorting, visible-page selection, pagination, and loading/empty/error feedback. When Apply is present, keep edits staged until submission; clear page and selection when the applied result set changes. Batch any selected-row detail request instead of issuing one request per row.

API

Component API
PropTypeDefaultDescriptionConstraints
Tabletable propsmd densitySemantic table root with the shared md row and cell density.Wrap in overflow-x-auto when it can exceed the viewport. Feature state owns sorting, filtering, paging, and selection.
TableHeaderthead props + stickyfalseHeader section; sticky keeps it visible while the body scrolls.Use sticky inside a bounded scroll region.
TableBody / TableFootersection props—Native table sections.Keep header and body structure valid.
TableRowtr props + selectedfalseData row with selected-state styling.Use stable row IDs in feature selection state.
TableHeadth props + scopescope=colColumn or row header cell.Set the correct scope for the relationship.
TableCelltd props—Data cell with shared md padding.Use colSpan for state rows.
TableCaptioncaption props—Optionally names the table data set.Use when the surrounding heading does not provide enough context.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-border-default / --color-bg-subtleTable boundariessemantic rolesSeparates rows and headers without heavy decoration.
--space-3 / --space-2.5Cell paddingmd densityKeeps the single table rhythm consistent across examples.
--motion-duration-normalRow state180msSoftens selected and hover transitions while respecting reduced motion.

Accessibility

  • Add a caption when the surrounding heading does not name the data set; otherwise keep the table visually focused.
  • Keep pinned cells opaque and preserve their header associations; fixed positioning is a visual aid, not a replacement for table semantics.
  • Give date inputs explicit labels and expose the active result count with a polite status message.
  • Keep selection checkboxes labeled with the row identity and scope select-all to the visible set.
  • Allow horizontal scrolling at narrow widths; do not clip long labels.
  • Keep loading, error, and empty feedback inside a stable table boundary.
  • Data table composes Table with staged filters, sorting, paging, and selection.
  • Checkbox supplies row selection controls.
  • Layout & Grid documents wide-content boundaries.