Skip to content
Browse documentation
whisk/ui

Table

Present structured data with semantic table markup.

Overview

Table renders a native HTML table through styled parts for captions, column and row headers, sections, rows, and cells. It handles table presentation, not sorting, filtering, pagination, selection, or row activation.

Use when

Rows and columns represent structured data with meaningful headers.

Use instead

Use Grid for visual layout or DataTable for simple read-only text data from the portable contract.

Usage

Open projects
ProjectStatus
AtlasActive
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableColumnHeader,
  TableHeader,
  TableRow,
} from "@smoothie-framework/whisk-react";

<Table>
  <TableCaption>Open projects</TableCaption>
  <TableHeader>
    <TableRow><TableColumnHeader>Project</TableColumnHeader><TableColumnHeader>Status</TableColumnHeader></TableRow>
  </TableHeader>
  <TableBody>
    <TableRow><TableCell>Atlas</TableCell><TableCell>Active</TableCell></TableRow>
  </TableBody>
</Table>

Examples

Start with a caption and scoped headers

A caption names the whole table. Use column headers for each field, and keep the data in the same order as the headers.

Open projects
ProjectStatusMembers
AtlasActive12
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableColumnHeader,
  TableHeader,
  TableRow,
} from "@smoothie-framework/whisk-react";

<Table>
  <TableCaption side="top">Open projects</TableCaption>
  <TableHeader>
    <TableRow>
      <TableColumnHeader>Project</TableColumnHeader>
      <TableColumnHeader>Status</TableColumnHeader>
      <TableColumnHeader textAlign="end">Members</TableColumnHeader>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Atlas</TableCell>
      <TableCell>Active</TableCell>
      <TableCell textAlign="end">12</TableCell>
    </TableRow>
  </TableBody>
</Table>

Add totals and row headers

Use scope="row" when the first cell names the rest of that row. A footer is appropriate for a summary or total, not for ordinary rows.

Monthly storage
WorkspaceStorage
Atlas12 GB
Total12 GB
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableColumnHeader,
  TableFooter,
  TableHeader,
  TableRow,
} from "@smoothie-framework/whisk-react";

<Table striped>
  <TableCaption side="top">Monthly storage</TableCaption>
  <TableHeader>
    <TableRow>
      <TableColumnHeader scope="col">Workspace</TableColumnHeader>
      <TableColumnHeader scope="col" textAlign="end">Storage</TableColumnHeader>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableColumnHeader scope="row">Atlas</TableColumnHeader>
      <TableCell textAlign="end">12 GB</TableCell>
    </TableRow>
  </TableBody>
  <TableFooter>
    <TableRow>
      <TableColumnHeader scope="row">Total</TableColumnHeader>
      <TableCell textAlign="end">12 GB</TableCell>
    </TableRow>
  </TableFooter>
</Table>

Contain a wide table

Wrap a table that cannot fit its container in TableScrollArea. It preserves the native table and adds horizontal scrolling instead of clipping essential columns.

Project metrics
ProjectMembersTasksStorage
Atlas124812 GB
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableColumnHeader,
  TableHeader,
  TableRow,
  TableScrollArea,
} from "@smoothie-framework/whisk-react";

<TableScrollArea frame="outline" aria-label="Project metrics table">
  <Table style={{ minWidth: "42rem" }} stickyHeader>
    <TableCaption side="top">Project metrics</TableCaption>
    <TableHeader>
      <TableRow>
        <TableColumnHeader sticky="start">Project</TableColumnHeader>
        <TableColumnHeader textAlign="end">Members</TableColumnHeader>
        <TableColumnHeader textAlign="end">Tasks</TableColumnHeader>
        <TableColumnHeader textAlign="end">Storage</TableColumnHeader>
      </TableRow>
    </TableHeader>
    <TableBody>
      <TableRow>
        <TableColumnHeader scope="row" sticky="start">Atlas</TableColumnHeader>
        <TableCell textAlign="end">12</TableCell>
        <TableCell textAlign="end">48</TableCell>
        <TableCell textAlign="end">12 GB</TableCell>
      </TableRow>
    </TableBody>
  </Table>
</TableScrollArea>

Set fixed column widths with native columns

Use TableColumnGroup before the header and body. TableColumn is a native void element, so set width through style.width rather than passing children or a component-specific width prop.

tsx
import {
  Table,
  TableBody,
  TableCell,
  TableColumnHeader,
  TableHeader,
  TableRow,
} from "@smoothie-framework/whisk-react";

<Table layout="fixed" showColumnBorder>
  <TableColumnGroup>
    <TableColumn style={{ width: "65%" }} />
    <TableColumn style={{ width: "35%" }} />
  </TableColumnGroup>
  <TableHeader>
    <TableRow>
      <TableColumnHeader>File</TableColumnHeader>
      <TableColumnHeader textAlign="end">Size</TableColumnHeader>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow><TableCell>release-notes.md</TableCell><TableCell textAlign="end">24 KB</TableCell></TableRow>
  </TableBody>
</Table>

Use real controls for row actions

interactive only adds hover styling. Keep each operation a real control in a labelled column rather than turning the row into an undocumented interaction.

ProjectOwnerActions
AtlasRosa
import {
  Button,
  Table,
  TableBody,
  TableCell,
  TableColumnHeader,
  TableHeader,
  TableRow,
} from "@smoothie-framework/whisk-react";

<Table interactive>
  <TableHeader>
    <TableRow>
      <TableColumnHeader>Project</TableColumnHeader>
      <TableColumnHeader>Owner</TableColumnHeader>
      <TableColumnHeader>Actions</TableColumnHeader>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Atlas</TableCell>
      <TableCell>Rosa</TableCell>
      <TableCell><Button size="sm" variant="secondary">Open project</Button></TableCell>
    </TableRow>
  </TableBody>
</Table>

Props

Component props

PropTypeDefaultDescription
size | variant | layoutsm | md | lg | line | outline | auto | fixedmd | line | autoSet density, visual treatment, and the native table layout algorithm. These props are static, not responsive.
striped | interactive | showColumnBorder | stickyHeaderbooleanfalseAdd a visual row treatment, hover treatment, column dividers, or sticky headers. interactive does not make a row focusable or clickable.
TableCaption sidetop | bottombottomKeep a native caption in the table DOM and choose its visual placement with CSS.
TableColumnHeader scopecol | row | colgroup | rowgroupcolState how a header labels related cells. Pass native aria-sort only when application code implements sorting.
TableCell | TableColumnHeader: sticky | textAlignsticky: "start" | "end"; textAlign: "start" | "end" | "left" | "center" | "right"none | nonePin one boundary column or align cell content. Multiple pinned columns need application-authored CSS offsets.
TableRow selected | emphasizedboolean | (() => boolean) | booleanfalse | falseAdd visual state only. Use an actual Checkbox or other native control when people select rows.
TableColumnGroup | TableColumnnative colgroup | native colnoneControl column metadata and widths. TableColumn is void; use span and style.width, and keep the group before table sections.
TableScrollAreaScrollAreaProps & { frame?: none | outline }horizontal | stable | noneContain wide tables with native horizontal scrolling. It forwards ScrollArea props; name the scroll region when it needs an accessible landmark.
className | style | native table attributesnative table attributesnoneTarget the table element directly. Use native colSpan, rowSpan, headers, and scope attributes for complex associations.

Accessibility

Use TableCaption to name what the table contains, then use TableColumnHeader for column labels and scope="row" for row headers. Native table semantics provide the relationships, so do not replace them with grid roles. In complex tables, preserve correct HTML section order and use colSpan, rowSpan, and headers when scope alone cannot describe the relationship. Table does not add keyboard navigation, focus movement, selection, or sort behavior. Use real Buttons, Links, and Checkboxes in cells for those tasks, and set aria-sort only when the application actually changes the sort order. Wrap wide tables in a named TableScrollArea rather than clipping columns or hiding essential data.

Content guidance

Write a caption that says what the table contains. Keep column headers short, specific, and consistently phrased.