Table

Structured data for SaaS interfacesLink to section

The Table component displays structured, comparable data.

Use it for:

• users
• projects
• invoices
• subscriptions
• logs
• reports
• audit events
• admin records

Table provides a consistent visual foundation for dense product data:

• semantic table structure
• design-token styling
• horizontal overflow handling
• row hover feedback
• built-in empty state
• built-in loading state

ImportLink to section

import { Table } from "@pycolors/ui";

Basic usageLink to section

import {
  Table,
  TableHeader,
  TableBody,
  TableRow,
  TableHead,
  TableCell,
} from "@pycolors/ui";

export function UsersTable() {
  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Name</TableHead>
          <TableHead>Email</TableHead>
          <TableHead>Role</TableHead>
        </TableRow>
      </TableHeader>

      <TableBody>
        <TableRow>
          <TableCell>Jane Doe</TableCell>
          <TableCell>jane@example.com</TableCell>
          <TableCell>Admin</TableCell>
        </TableRow>
        <TableRow>
          <TableCell>John Smith</TableCell>
          <TableCell>john@example.com</TableCell>
          <TableCell>User</TableCell>
        </TableRow>
      </TableBody>
    </Table>
  );
}

When to use TableLink to section

Use Table when the interface needs scanning, comparison, and operational density.

CaptionLink to section

Use TableCaption when the table needs a concise summary.

<Table>
  <TableCaption>List of active users</TableCaption>
  {/* rows */}
</Table>

Captions should explain what the table contains, not repeat the page heading.

Empty stateLink to section

Use TableEmpty when the request succeeded but no rows are available.

<TableBody>
  <TableEmpty colSpan={3} />
</TableBody>

<TableBody>
  <TableEmpty
    colSpan={3}
    title="No users found"
    description="Invite your first user to get started."
  />
</TableBody>

Loading stateLink to section

Use TableLoading when the table structure is known but the data is still loading.

<TableBody>
  <TableLoading colSpan={3} />
</TableBody>

Use loading rows instead of removing the table from the page.

This preserves layout and reduces visual jump.

Table compositionLink to section

A production table usually belongs inside a larger feature composition.

export function ProjectsTableSection() {
  return (
    <section className="space-y-4">
      <ProjectsToolbar />
      <Table>
        <ProjectsTableHeader />
        <ProjectsTableBody />
      </Table>
      <ProjectsPagination />
    </section>
  );
}

The table renders structure.

The feature layer owns:

• data fetching
• filters
• sorting
• pagination
• permissions
• mutations
• row actions

Usage patternsLink to section

Table vs Card vs Data Table PatternLink to section

APILink to section

ComponentsLink to section

TableEmpty propsLink to section

TableLoading propsLink to section

All base table components extend their respective native HTML element props.

React.HTMLAttributes<HTMLTableElement>
React.HTMLAttributes<HTMLTableSectionElement>
React.HTMLAttributes<HTMLTableRowElement>
React.ThHTMLAttributes<HTMLTableCellElement>
React.TdHTMLAttributes<HTMLTableCellElement>
React.HTMLAttributes<HTMLTableCaptionElement>

AccessibilityLink to section

Tables should preserve semantic structure.

Guidelines:

• use TableHead for column headers
• include a caption when the context is not obvious
• avoid using tables for layout
• keep cells readable and concise
• ensure interactive row actions are keyboard accessible
• avoid making the whole row clickable unless the interaction is clear
• use visible labels for icon-only row actions

Prefer / avoidLink to section

Product copy guidelinesLink to section

Table labels should be short and scannable.

Common questionsLink to section

RelatedLink to section