Examples
Semantic table
Compound parts preserve headers, rows, and cells as native table elements.
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>
);
}
Date-range filtering
Stage labeled date inputs and apply an inclusive range without changing Table semantics.
Showing 2 projects in the selected range.
"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>
);
}
Fixed header and columns
Pin the header while scrolling vertically and the project column while scrolling horizontally inside one bounded region.
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>
);
}
Numeric alignment
Right-align numeric values while keeping the row and column meaning explicit.
| Month | Events | Change |
|---|---|---|
| August | 18,420 | +12% |
| July | 16,445 | — |
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@phuctech/ui/components/table";
export function Example() {
return (
<Table>
<TableHeader><TableRow><TableHead>Month</TableHead><TableHead className="text-right">Events</TableHead><TableHead className="text-right">Change</TableHead></TableRow></TableHeader>
<TableBody>
<TableRow><TableCell>August</TableCell><TableCell className="text-right tabular-nums">18,420</TableCell><TableCell className="text-right tabular-nums text-[color:var(--color-success-text)]">+12%</TableCell></TableRow>
<TableRow><TableCell>July</TableCell><TableCell className="text-right tabular-nums">16,445</TableCell><TableCell className="text-right tabular-nums">—</TableCell></TableRow>
</TableBody>
</Table>
);
}
Loading, error, and empty
Use an overlay spinner, an actionable error alert, and a centered empty state without changing table semantics.
| Project | Status |
|---|---|
| Loading projects… | |
Couldn't load projects
The request failed. Try again to refresh the table.
No data
There are no projects to display yet.
import { Button } from "@phuctech/ui/components/button";
import { AlertTriangleIcon, InboxIcon, LoaderCircleIcon } from "@phuctech/ui/icons";
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@phuctech/ui/components/table";
function LoadingState() {
return (
<div className="relative overflow-hidden rounded-lg border border-border">
<Table aria-busy="true">
<TableHeader>
<TableRow>
<TableHead>Project</TableHead>
<TableHead>Status</TableHead>
</TableRow>
</TableHeader>
<TableBody>
<TableRow>
<TableCell colSpan={2} className="h-24 text-center text-muted-foreground">
Loading projects…
</TableCell>
</TableRow>
</TableBody>
</Table>
<div className="absolute inset-0 flex items-center justify-center gap-2 bg-background/75" role="status">
<LoaderCircleIcon aria-hidden="true" className="size-[var(--size-icon-md)] animate-spin text-muted-foreground" />
<span className="text-sm font-medium">Loading projects…</span>
</div>
</div>
);
}
function ErrorState() {
return (
<div className="flex items-start gap-3 rounded-lg border border-[color:var(--color-danger-border)] bg-[color:var(--color-danger-bg)] p-4" role="alert">
<AlertTriangleIcon aria-hidden="true" className="mt-0.5 size-[var(--size-icon-md)] shrink-0 text-[color:var(--color-danger-text)]" />
<div className="grid gap-2">
<div>
<p className="font-medium">Couldn't load projects</p>
<p className="text-sm text-muted-foreground">The request failed. Try again to refresh the table.</p>
</div>
<Button type="button" size="sm" variant="outline">Try again</Button>
</div>
</div>
);
}
function EmptyState() {
return (
<div className="grid justify-items-center gap-2 rounded-lg border border-dashed border-border p-8 text-center">
<InboxIcon aria-hidden="true" className="size-8 text-muted-foreground" />
<p className="font-medium">No data</p>
<p className="max-w-sm text-sm text-muted-foreground">There are no projects to display yet.</p>
<Button type="button" size="sm" variant="outline">Create project</Button>
</div>
);
}
export function Example() {
return (
<div className="grid gap-4">
<LoadingState />
<ErrorState />
<EmptyState />
</div>
);
}
Row selection
Checkboxes can compose with Table while select-all remains scoped to visible rows.
| Project | |
|---|---|
| Atlas onboarding | |
| Orbit billing | |
| Lumen research |
"use client";
import { useState } from "react";
import { Checkbox } from "@phuctech/ui/components/checkbox";
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@phuctech/ui/components/table";
const rows = [{ id: "atlas", name: "Atlas onboarding" }, { id: "orbit", name: "Orbit billing" }, { id: "lumen", name: "Lumen research" }];
export function Example() {
const [selected, setSelected] = useState<string[]>(["atlas"]);
const allSelected = selected.length === rows.length;
const partiallySelected = selected.length > 0 && !allSelected;
return (
<Table>
<TableHeader><TableRow selected={partiallySelected || allSelected}><TableHead className="w-12"><Checkbox aria-label="Select all visible projects" checked={allSelected} indeterminate={partiallySelected} onCheckedChange={(checked) => setSelected(checked ? rows.map((row) => row.id) : [])} /></TableHead><TableHead>Project</TableHead></TableRow></TableHeader>
<TableBody>{rows.map((row) => <TableRow key={row.id} selected={selected.includes(row.id)}><TableCell><Checkbox aria-label={`Select ${row.name}`} checked={selected.includes(row.id)} onCheckedChange={(checked) => setSelected((current) => checked ? [...current, row.id] : current.filter((id) => id !== row.id))} /></TableCell><TableCell className="font-medium">{row.name}</TableCell></TableRow>)}</TableBody>
</Table>
);
}
Wide and long content
A surrounding scroll region protects narrow screens without changing table semantics.
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@phuctech/ui/components/table";
const rows = Array.from({ length: 6 }, (_, index) => ({ id: index, name: `Workspace record with a deliberately long label ${index + 1}`, owner: "A long owner name that remains readable" }));
export function Example() {
return (
<div className="scrollbar-hover-reveal max-w-full overflow-x-auto rounded-lg border border-border">
<Table className="min-w-[48rem]"><TableHeader><TableRow><TableHead>Workspace record</TableHead><TableHead>Owner</TableHead><TableHead>Last updated</TableHead></TableRow></TableHeader><TableBody>{rows.map((row) => <TableRow key={row.id}><TableCell className="max-w-72 whitespace-normal font-medium">{row.name}</TableCell><TableCell className="whitespace-normal">{row.owner}</TableCell><TableCell>Today</TableCell></TableRow>)}</TableBody></Table>
</div>
);
}
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
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
TableCaptionwhen the data set needs an explicit name for assistive technology; it is optional when the surrounding heading already provides that context. TableHeaddefaults toscope="col"; passscope="row"for row headers.TableRow selectedexposesdata-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.
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.
"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
Tokens
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.
Related
- Data table composes Table with staged filters, sorting, paging, and selection.
- Checkbox supplies row selection controls.
- Layout & Grid documents wide-content boundaries.