Table

Name

Role

Value

State

Ref

Create your account

heading

@e1

textbox

[email protected]

focused

@e2

Password

textbox

required

@e3

Keep me signed in

checkbox

checked

@e4

Create account

button

@e5

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

<Table
  aria-label="Elements on the page"
  columns={[
    { key: "name", label: "Name" },
    { key: "role", label: "Role" },
    { key: "value", label: "Value" },
    { key: "state", label: "State" },
    { key: "ref", label: "Ref", tone: "quiet" },
  ]}
  rows={[
    { key: "e1", cells: { name: "Create your account", role: "heading", ref: "@e1" } },
    { key: "e2", cells: { name: "Email", role: "textbox", value: "[email protected]", state: "focused", ref: "@e2" } },
    { key: "e3", cells: { name: "Password", role: "textbox", state: "required", ref: "@e3" } },
    { key: "e4", cells: { name: "Keep me signed in", role: "checkbox", state: "checked", ref: "@e4" } },
    { key: "e5", cells: { name: "Create account", role: "button", ref: "@e5" } },
  ]}
/>

What an agent read off a sign-up page: each element's name, role, value and state, and the faint ref it acts on.

TSX

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

<Table
  aria-label="Files"
  columns={[{ key: "name", label: "Name" }, { key: "size", label: "Size", align: "end" }]}
  rows={[{ key: "readme", cells: { name: "README.md", size: "2.4 kB" } }]}
/>

A table for reading: rows of facts under named columns, one line per row. Give each column a key and a label, and each row a key and its cells by column key. A string or a number in a cell is one line that fades at its end when its column runs short of room, never wrapping and never ending in dots; any other node is drawn as you pass it. There is no frame and no fill: a hairline between rows, and the header in the label ink.

Each column is as wide as its widest cell, so the table is no wider than what it holds. A column with tone="quiet" is drawn in the third ink, for what is read after the rest: an id, a handle, the ref above.

Examples

An empty column

With hideEmpty, the default, a column no row fills is left out, header and all: buttons and links have no value, so there is no Value column.

Leave out empty columns

Name

Role

Ref

Create account

button

@e5

link

@e6

Terms

link

@e7

import { useState } from "react";
import { Switch, Table } from "@arcadia/ui";

function Empty() {
  const [hide, setHide] = useState(true);
  return (
    <div {...stylex.props(s.stack)}>
      <Switch label="Leave out empty columns" checked={hide} onCheckedChange={setHide} />
      <Table
        aria-label="Buttons and links"
        hideEmpty={hide}
        columns={[
          { key: "name", label: "Name" },
          { key: "role", label: "Role" },
          { key: "value", label: "Value" },
          { key: "ref", label: "Ref", tone: "quiet" },
        ]}
        rows={[
          { key: "e5", cells: { name: "Create account", role: "button", ref: "@e5" } },
          { key: "e6", cells: { name: "Sign in instead", role: "link", ref: "@e6" } },
          { key: "e7", cells: { name: "Terms", role: "link", ref: "@e7" } },
        ]}
      />
    </div>
  );
}

Turn it off to keep every column in place, as when rows arrive one by one and the columns should not move.

Numbers

align="end" sets a column at its end in tabular figures, so sizes and times line up by their digits.

File

Type

Size

Time

signup

document

14.2 kB

182 ms

app.js

script

214 kB

1,312 ms

app.css

stylesheet

38.6 kB

96 ms

session

fetch

1.2 kB

84 ms

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

<Table
  aria-label="Requests"
  columns={[
    { key: "file", label: "File" },
    { key: "type", label: "Type" },
    { key: "size", label: "Size", align: "end" },
    { key: "time", label: "Time", align: "end" },
  ]}
  rows={[
    { key: "doc", cells: { file: "signup", type: "document", size: "14.2 kB", time: "182 ms" } },
    { key: "js", cells: { file: "app.js", type: "script", size: "214 kB", time: "1,312 ms" } },
    { key: "css", cells: { file: "app.css", type: "stylesheet", size: "38.6 kB", time: "96 ms" } },
    { key: "api", cells: { file: "session", type: "fetch", size: "1.2 kB", time: "84 ms" } },
  ]}
/>

Short of room

Each column is offered an equal share of the room.

Name

Role

Value

Ref

Email address for receipts

textbox

[email protected]

@e2

Keep me signed in on this device

checkbox

@e4

Create account

button

@e5

import { useState } from "react";
import { Table } from "@arcadia/ui";

function Narrow() {
  const [w, setW] = useState(100);
  return (
    <div {...stylex.props(s.frame)}>
      <div style={{ width: `${w}%` }}>
        <Table
          aria-label="Fields on the page"
          columns={[
            { key: "name", label: "Name" },
            { key: "role", label: "Role" },
            { key: "value", label: "Value" },
            { key: "ref", label: "Ref", tone: "quiet" },
          ]}
          rows={[
            { key: "e2", cells: { name: "Email address for receipts", role: "textbox", value: "[email protected]", ref: "@e2" } },
            { key: "e4", cells: { name: "Keep me signed in on this device", role: "checkbox", value: "on", ref: "@e4" } },
            { key: "e5", cells: { name: "Create account", role: "button", ref: "@e5" } },
          ]}
        />
      </div>
      <input {...sx(null, cmp.scrubInput)} type="range" min={30} max={100} value={w} aria-label="Room for the table" onChange={(e) => setW(Number(e.target.value))} />
    </div>
  );
}

One that needs less keeps its whole width, and the longer ones split the rest, each cell fading at its end. Narrow the room: the long value gives way first, then the name with it.

rootStyle takes where the table sits and these knobs, each a token of its kind: a cell's inline padding and a row's least height.

--table-px: Ref<Space>Default var(--space-2-5)
--table-row-h: Ref<Control>Default var(--control-md)

The table is built of divs with role="table", row, columnheader and cell, so a screen reader announces its rows and columns and reads each cell with its column's name. Name it with aria-label or aria-labelledby, as every example here does. A column hideEmpty leaves out is gone from the reading too, and a cell that fades is still read whole.

It is for reading: there is no sorting, no selection and no arrow-key movement between cells. A link or a button you put in a cell takes Tab like any other. A quiet column differs from the rest by its ink alone, so it should never be the only place a fact is said.

columnsrequired: readonly TableColumn[]
rowsrequired: readonly TableRow[]
hideEmpty: booleanDefault true; Drops a column no row fills.
rootStyle: RootStyle<TableKnobs>
aria-label: string; Names the table for a screen reader.

Rest props go to <div> props.

Usage

Examples

An empty column

Numbers

Short of room

Customising

Accessibility

API reference

Table