Skip to content
opsinjs
Edit this page

Components

Table

Rows and columns in a real semantic table, the readable twin a chart ships with, with a required caption, right-aligned numeric columns and its own scroll.

Usage

pnpm dlx shadcn@latest add @opsinjs/table

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { Table } from "@/components/ui/table"
<Table
  caption="Example figures by period, and not a real record"
  columns={[
    { key: "period", header: "Period" },
    { key: "count", header: "Count", numeric: true },
  ]}
  rows={[
    { period: "Period one", count: "12" },
    { period: "Period two", count: "1,000" },
  ]}
/>

Examples

Theme
Density
Text
Status
Accent theme
Accent
table · base base · style base-lyraOpen under the product theme

The readable twin of a chart

The chart draws the shape; the table carries the figures. captionHidden hides the caption the heading above already supplies.

Theme
Density
Text
Status
Accent theme
Accent
table-a-chart-twin · base base · style base-lyraOpen under the product theme
table-a-chart-twin.tsx
import { Table } from "@/components/ui/table"

export default function TableAChartTwin() {
  return (
    <figure className="m-0 flex w-full max-w-md flex-col gap-opsin-2">
      <figcaption className="text-opsin-subheadline [color:var(--foreground)]">
        Example series, and not a real record
      </figcaption>
      {/* The chart sits here in a real surface; this table is its readable twin. */}
      <Table
        captionHidden
        caption="Example series by period, the readable twin of the chart above, showing an example count for each period"
        columns={[
          { key: "period", header: "Period" },
          { key: "count", header: "Count", numeric: true },
        ]}
        rows={[
          { period: "Period one", count: "12" },
          { period: "Period two", count: "1,000" },
          { period: "Period three", count: "8" },
        ]}
      />
    </figure>
  )
}

Numeric columns line up on their digits

numeric right-aligns two columns in tabular figures while the first column labels each row.

Theme
Density
Text
Status
Accent theme
Accent
table-numeric-columns · base base · style base-lyraOpen under the product theme
table-numeric-columns.tsx
import { Table } from "@/components/ui/table"
import { Value } from "@/components/ui/value"

export default function TableNumericColumns() {
  return (
    <Table
      caption="Example readings by row, and not a real record of anyone's"
      columns={[
        { key: "row", header: "Example row" },
        { key: "reading", header: "Reading", numeric: true },
        { key: "change", header: "Change", numeric: true },
      ]}
      rows={[
        {
          row: "First example row",
          reading: <Value value={1000.2} unit="kg" precision={1} />,
          change: <Value value={7} unit={null} precision={0} />,
        },
        {
          row: "Second example row",
          reading: <Value value={903.4} unit="kg" precision={1} />,
          change: <Value value={1024} unit={null} precision={0} />,
        },
        {
          row: "Third example row",
          reading: <Value value={888.0} unit="kg" precision={1} />,
          change: <Value value={128} unit={null} precision={0} />,
        },
      ]}
    />
  )
}

When to use it

Use it when

  • The accessible twin of a chart: the same figures a screen reader user can read.
  • A small set of rows and columns a reader compares directly.
  • A comparison read down a column, where lining the digits up is the point.

Do not use it when

  • One reading with a label, a time and a surface of its own.Use metric-tile instead.
  • A trend read as a shape rather than as figures.Use trend-sparkline instead.
  • The data has not arrived and you are holding the layout open.Use skeleton instead.
  • There are no rows, because the result is genuinely empty.Use empty-state instead.
  • An interactive grid with sorting, selection and virtualised scrolling.Use card instead.

Accessibility

The audit changed nothing and found no axe violation, target-size failure, focus-visible gap or sideways page scroll at 320px. A real <caption> always renders, headers carry scope="col", and the first body cell carries scope="row" when rowHeader is on. The overflow-x-auto container is tabIndex=0, reachable and scrollable by keyboard, and padding-based spacing with no fixed cell heights keeps text-spacing overrides from clipping. There is no colour prop, no data-status, no data-category and no transition.

Residual items.

  • An empty caption renders an empty <caption>, warning only in development.
  • The scroll container has no role and no accessible name; adding role="region" would require one, so it is left to the consuming page.
  • Contrast for the header ink, caption ink and hairlines has not been measured.
KeyActionNotes
TabMoves focus onto the scrollable table, then past itPresent even when the table fits.
Shift+TabMoves back out of the tableCells are never focus stops.
Left, RightScroll the table sideways when the container has focusNative to a focusable scroll region.
SpaceScrolls the page, as anywhere elseNo control here captures it.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from TableProps in registry/bases/base/table.tsx.

caption is a required string. rowHeader defaults to true, so the first cell of each row is a th. There is no onSort, no selectedRows and no virtualized.

Data attributes

AttributeConditionValue
data-slotOn the container, the table and every inner part, alwaystable-container, table, table-caption, table-header, table-head, table-body, table-row, table-cell
data-opsinjs-valueOn a td in a numeric columnThe empty string, deliberately: a tabular-figures hook, not a magnitude