First table

Rows of records to scan, sort, search and select (also called a data table or data grid). Reach for it when people compare many records by the same fields; from a few rows to a million on a server.

import { useTable } from "@umriss-ui/table";

useTable takes the rows and hands back the Table and the Column that belong to them, so a column can only name a field the row has. The parts that touch no row, such as Toolbar or Search, are ordinary imports.

Every option of the hook and every prop of the table stands in the tables below; each feature has a page of its own in the sidebar.

Examples

Show a list of services

Pass the rows to useTable and declare a Column per field; rowHeader names the row, and numbers align right and sort by value.

import { useTable } from "@umriss-ui/table";

interface Service {
  id: string;
  name: string;
  team: string;
  tier: number;
  latencySlo: number;
}

const SERVICES: Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800 },
];

export default function FirstTable() {
  const { Table, Column } = useTable(SERVICES, { rowKey: (s) => s.id });

  return (
    <Table ariaLabel="Services">
      <Column value="name" label="Service" rowHeader />
      <Column value="team" label="Team" />
      <Column value="tier" label="Tier" />
      <Column value="latencySlo" label="Latency objective (ms)" />
    </Table>
  );
}

Search and page from a header of your own

t.search and t.setSearch bind a field of the application's own, t.page and t.setPage a pager in the card's header. The table pages only while a Pagination stands in it; both pagers move the same page.

import { Button, Card, CardBody, CardHeader, Input, Stack, Text } from "@umriss-ui/core";
import { Pagination, useTable } from "@umriss-ui/table";
import type { TableRef } from "@umriss-ui/table";

interface Service {
  id: string;
  name: string;
  team: string;
  tier: number;
}

const SERVICES: Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1 },
  { id: "refunds", name: "Refunds", team: "Payments", tier: 2 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1 },
  { id: "accounts", name: "Accounts", team: "Identity", tier: 2 },
  { id: "search", name: "Search", team: "Discovery", tier: 1 },
  { id: "recommendations", name: "Recommendations", team: "Discovery", tier: 3 },
  { id: "catalogue", name: "Catalogue", team: "Discovery", tier: 2 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2 },
  { id: "webhooks", name: "Webhooks", team: "Messaging", tier: 3 },
  { id: "image-service", name: "Image service", team: "Platform", tier: 2 },
  { id: "reporting", name: "Reporting", team: "Platform", tier: 3 },
];

/* Written once for every table of the application, so it takes the table as
   `of`, as the package's own parts do. It says which rows stand on the page,
   out of how many: `rowCount` is what the search leaves, `rows` all there are.
   A table that scrolls instead of paging has no page to step through. */
function RangePager({ of }: { of: TableRef }) {
  if (of.virtual || of.rowCount === 0) return null;
  const first = (of.page - 1) * of.pageSize + 1;
  const last = Math.min(of.page * of.pageSize, of.rowCount);
  return (
    <Stack direction="row" gap={1} align="center">
      <Text size="sm" tone="secondary">
        {first}–{last} of {of.rowCount}
        {of.rowCount < of.rows.length && ` (${of.rows.length} in all)`}
      </Text>
      <Button size="sm" aria-label="Previous page" disabled={of.page <= 1} onClick={() => of.setPage(of.page - 1)}>
        ‹
      </Button>
      <Button size="sm" aria-label="Next page" disabled={of.page >= of.pageCount} onClick={() => of.setPage(of.page + 1)}>
        ›
      </Button>
    </Stack>
  );
}

export default function SearchAndPageFromAHeader() {
  const t = useTable(SERVICES, { rowKey: (s) => s.id, pageSize: 5 });
  const { Table, Column } = t;
  const all = t.pageSize >= t.rows.length;

  return (
    <Card>
      <CardHeader
        divider
        title="Services"
        actions={
          <Stack direction="row" gap={2} align="center" wrap>
            <Input
              type="search"
              size="sm"
              chars={18}
              placeholder="Service or team"
              aria-label="Search the services"
              value={t.search}
              onChange={(event) => t.setSearch(event.target.value)}
            />
            <RangePager of={t} />
            <Button size="sm" onClick={() => t.setPageSize(all ? 5 : t.rows.length)}>
              {all ? "Five per page" : "Show all"}
            </Button>
          </Stack>
        }
      />
      <CardBody>
        <Table ariaLabel="Services">
          <Column value="name" label="Service" rowHeader />
          <Column value="team" label="Team" />
          <Column value="tier" label="Tier" />
          <Pagination pageSizes={[5, 10]} />
        </Table>
      </CardBody>
    </Card>
  );
}

Sort, arrange and export from controls of your own

t.toggleSort, t.toggleColumn and t.setOrder change what the headers and the column menu change; t.sort, t.hidden and t.order say how it stands. t.asCsv() is the text an export writes.

import { useState } from "react";
import { Button, Checkbox, Select, Stack } from "@umriss-ui/core";
import { useTable } from "@umriss-ui/table";
import type { TableRef } from "@umriss-ui/table";

interface Service {
  id: string;
  name: string;
  team: string;
  tier: number;
  latencySlo: number;
}

const SERVICES: Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800 },
  { id: "reporting", name: "Reporting", team: "Platform", tier: 3, latencySlo: 2000 },
];

/** The columns the panel arranges, by id - the row header stays where it is. */
const COLUMNS = [
  { id: "team", label: "Team" },
  { id: "tier", label: "Tier" },
  { id: "latencySlo", label: "Latency objective (ms)" },
] as const;

/* Written once for every table of the application. In server mode the table
   holds one page of the server's, and that is all `asCsv` can write - so the
   button says so instead of pretending to copy the whole list. */
function CopyAsCsv({ of }: { of: TableRef }) {
  const [copied, setCopied] = useState(false);
  return (
    <Button
      size="sm"
      onClick={() => {
        void navigator.clipboard.writeText(of.asCsv()).then(() => setCopied(true));
      }}
    >
      {copied ? "Copied" : of.server ? "Copy this page as CSV" : "Copy as CSV"}
    </Button>
  );
}

export default function SortArrangeAndExport() {
  const t = useTable(SERVICES, { rowKey: (s) => s.id, defaultSort: { column: "tier", direction: "asc" } });
  const { Table, Column } = t;
  /* Empty until somebody arranges: then the natural order. */
  const order = t.order.length > 0 ? t.order.filter((id) => COLUMNS.some((c) => c.id === id)) : COLUMNS.map((c) => c.id);
  const sorted = t.sort[0];

  const moveLeft = (id: string) => {
    const at = order.indexOf(id);
    t.setOrder(["name", ...order.slice(0, at - 1), id, order[at - 1]!, ...order.slice(at + 1)]);
  };

  return (
    <Stack gap={3}>
      <Stack direction="row" gap={2} align="center" wrap>
        <Select size="sm" aria-label="Sort by" value={sorted?.column ?? ""} onChange={(event) => t.toggleSort(event.target.value)}>
          <option value="name">Service</option>
          {COLUMNS.map((c) => (
            <option key={c.id} value={c.id}>
              {c.label}
            </option>
          ))}
        </Select>
        <Button size="sm" variant="ghost" onClick={() => sorted && t.toggleSort(sorted.column)}>
          {sorted?.direction === "desc" ? "Descending" : "Ascending"}
        </Button>
        <CopyAsCsv of={t} />
      </Stack>
      <Stack direction="row" gap={3} align="center" wrap>
        {order.map((id, i) => {
          const label = COLUMNS.find((c) => c.id === id)!.label;
          return (
            <Stack key={id} direction="row" gap={1} align="center">
              <Button size="sm" variant="ghost" aria-label={`Move ${label} to the left`} disabled={i === 0} onClick={() => moveLeft(id)}>
                ←
              </Button>
              <Checkbox label={label} checked={!t.hidden.includes(id)} onChange={() => t.toggleColumn(id)} />
            </Stack>
          );
        })}
      </Stack>
      <Table ariaLabel="Services">
        <Column value="name" label="Service" rowHeader />
        <Column value="team" label="Team" />
        <Column value="tier" label="Tier" />
        <Column value="latencySlo" label="Latency objective (ms)" />
      </Table>
    </Stack>
  );
}

When to use something else

• Measured values read against their limits → VerdictColumn
• Three or four key figures side by side → Stat from @umriss-ui/core

Keyboard

Accessibility

A native table, named by ariaLabel: without it a screen reader announces a table with no name, so pass one, the more so where a page holds two. The rowHeader column's cells are row headers, so a reader names the row as it moves along it, and the row's checkbox, expander and actions are named after it too.

A sortable header holds a button, and its cell carries aria-sort, so the reader says which column orders the rows and in which direction. While loading is set the table is aria-busy.

A value cut short at the edge of its cell shows whole in a tip, under the pointer and on keyboard focus alike; the cell's text is the whole value all along, so a reader never meets the cut.

API

type RowAttributes = { className?: string } & {
  [data: `data-${string}`]: string | undefined;
};

type GroupingId<Z> = Field<Z> | (string & {});

type Pin = "start" | "end";

interface SetFilter<Z> {
  <B>(filter: RowFilter<Z, B>, condition: B | null): void;
  <K extends Field<Z>>(column: K, condition: FieldCondition<Z[K]> | null): void;
  <I extends string>(column: I & (I extends Field<Z> ? never : unknown), condition: unknown): void;
}

type SortDirection = "asc" | "desc";

type Field<Z> = Extract<keyof Z, string>;

type FieldCondition<W> =
  | ListCondition<W>
  | ([Present<W>] extends [number] ? RangeCondition<number> : [Present<W>] extends [Date] ? RangeCondition<Date> : never);

type ListCondition<W> = readonly (Present<W> | null)[];

type Present<W> = Exclude<W, Absent>;

type Absent = null | undefined;

Known limits

• No cell range selection and no undo: an edit is reported, never applied, and the application owns the rows (ADR-0032).
• No pivot: compute the pivoted rows and declare their columns (ADR-0032).

What umriss deliberately does not build, and why: ADR-0032.

Every page of @umriss-ui/table

Getting started

• Installation
• First table
• Provider

Columns

• Column
• Formats
• Width and pinning
• Presets

Finding rows

• Sorting
• Search
• Filter
• Pre-filter

Grouping

• Grouping
• Tree rows
• Aggregate

Rows

• Selection
• Row appearance
• RowDetail
• RowActions

Around the table

• Toolbar
• Toolbar controls
• ColumnMenu
• Export
• View

Many rows

• Pagination
• Virtualisation
• Benchmark
• Server mode

Editing

• Grid mode
• Edits

Limits and alarms

• VerdictColumn

API index

• API index