Skip to content

Row list

Rows that each open a detail, the title stretched as the row's one link, with j and k to move.

<ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="s-mixed" data-cap-primary id="list-mixed">
  <li class="cap-row" data-tone="crit">
    <span class="cap-row-status" id="m1-s"><span class="cap-status" data-tone="crit"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M5 1h6l4 4v6l-4 4H5l-4-4V5z" /><path fill="var(--surface)" d="M7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z" /></svg>Critical</span></span>
    <div class="cap-row-title"><a href="#site-example-org" aria-describedby="m1-s m1-d">example.org is not answering</a></div>
    <p class="cap-row-detail" id="m1-d">3 failed checks in a row, first at 14:02</p>
    <span class="cap-row-meta"><time datetime="2026-09-30T14:02Z">11 minutes ago</time></span>
  </li>
  <li class="cap-row">
    <span class="cap-row-status" id="m2-s"><span class="cap-status" data-tone="warn"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 1.2 15.4 14H.6z" /><path fill="var(--surface)" d="M7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z" /></svg>Warning</span></span>
    <div class="cap-row-title"><a href="#usage-d1" aria-describedby="m2-s m2-d">D1 rows read will run out before the reset</a></div>
    <p class="cap-row-detail" id="m2-d">78% used, full in about 3 hours</p>
    <span class="cap-row-meta">projected</span>
  </li>
  <li class="cap-row">
    <span class="cap-row-status" id="m3-s"><span class="cap-status" data-tone="warn"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 1.2 15.4 14H.6z" /><path fill="var(--surface)" d="M7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z" /></svg>Warning</span></span>
    <div class="cap-row-title"><a href="#queue-blocked" aria-describedby="m3-s m3-d">2 jobs are waiting for approval</a></div>
    <p class="cap-row-detail" id="m3-d">Oldest has waited 26 minutes</p>
    <span class="cap-row-meta"><time datetime="2026-09-30T13:47Z">26 minutes ago</time></span>
  </li>
  <li class="cap-row">
    <span class="cap-row-status" id="m4-s"><span class="cap-status" data-tone="nodata"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="6.2" fill="none" stroke="currentColor" stroke-width="1.6"/><path d="M5 8h6" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>No data</span></span>
    <div class="cap-row-title"><a href="#site-example-net" aria-describedby="m4-s m4-d">example.net: no backup reported</a></div>
    <p class="cap-row-detail" id="m4-d">Its health route does not report one yet</p>
    <span class="cap-row-meta">since setup</span>
  </li>
  <li class="cap-row">
    <span class="cap-row-status" id="m5-s"><span class="cap-status" data-tone="info"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><rect x="1.5" y="1.5" width="13" height="13" rx="2" fill="none" stroke="currentColor" stroke-width="1.6" /><path fill="currentColor" d="M7.2 7h1.6v5H7.2zM7.2 4h1.6v1.7H7.2z" /></svg>Notice</span></span>
    <div class="cap-row-title"><a href="#notices" aria-describedby="m5-s m5-d">4 notices</a></div>
    <p class="cap-row-detail" id="m5-d">Dependency updates, none urgent</p>
    <span class="cap-row-meta"><time datetime="2026-09-30T09:10Z">5 hours ago</time></span>
  </li>
</ul>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/row-list.css";
import { enhance } from "capsomer/behavior/row-list";

enhance();

Usage

<ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="attention-h" data-cap-primary>
  <li class="cap-row" data-tone="crit">
    <span class="cap-row-status" id="r1-s"><span class="cap-status" data-tone="crit">[glyph] Critical</span></span>
    <div class="cap-row-title"><a href="/sites/example-org" aria-describedby="r1-s r1-d">example.org is not answering</a></div>
    <p class="cap-row-detail" id="r1-d">3 failed checks in a row, first at 14:02</p>
    <span class="cap-row-meta"><time class="cap-time" datetime="2026-09-30T14:02Z">11 minutes ago</time></span>
    <div class="cap-row-actions"><button type="button" class="cap-btn">Retry</button></div>
  </li>
</ul>
<li class="cap-row">
  <span class="cap-row-status" id="g-s"><span class="cap-status" data-tone="warn">[glyph] Warning</span></span>
  <div class="cap-row-title"><button type="button" aria-expanded="false" aria-controls="g-rows" aria-describedby="g-s g-d">3 pull requests await the seat</button></div>
  <p class="cap-row-detail" id="g-d">web, docs, billing</p>
  <span class="cap-row-meta"><time datetime="...">26 minutes ago</time><span class="cap-row-chevron" aria-hidden="true"></span></span>
</li>

Examples

A critical row

<ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="s-crit" id="list-crit">
  <li class="cap-row" data-tone="crit">
    <span class="cap-row-status" id="c1-s"><span class="cap-status" data-tone="crit"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M5 1h6l4 4v6l-4 4H5l-4-4V5z" /><path fill="var(--surface)" d="M7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z" /></svg>Critical</span></span>
    <div class="cap-row-title"><a href="#job-failed" aria-describedby="c1-s c1-d">billing-driver stopped</a></div>
    <p class="cap-row-detail" id="c1-d">The type check failed twice on the same file</p>
    <span class="cap-row-meta"><time datetime="2026-09-30T13:32Z">41 minutes ago</time></span>
  </li>
</ul>

A focused row

<ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="s-focus" id="list-focus">
  <li class="cap-row">
    <span class="cap-row-status" id="f1-s"><span class="cap-status" data-tone="ok"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="currentColor" /><path fill="none" stroke="var(--surface)" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" d="m4.6 8.3 2.3 2.3 4.5-4.9" /></svg>Running</span></span>
    <div class="cap-row-title"><a href="#job-running" aria-describedby="f1-s f1-d">Run the browser tests for capsomer</a></div>
    <p class="cap-row-detail" id="f1-d">Held by capsid-driver, file 3 of 5</p>
    <span class="cap-row-meta"><time datetime="2026-09-30T13:55Z">18 minutes ago</time></span>
  </li>
  <li class="cap-row">
    <span class="cap-row-status" id="f2-s"><span class="cap-status" data-tone="nodata"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="6.2" fill="none" stroke="currentColor" stroke-width="1.6"/><path d="M5 8h6" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>Queued</span></span>
    <div class="cap-row-title"><a href="#job-queued" aria-describedby="f2-s f2-d">Refresh the uptime strip fixtures</a></div>
    <p class="cap-row-detail" id="f2-d">Priority 2</p>
    <span class="cap-row-meta"><time datetime="2026-09-30T12:40Z">1 hour ago</time></span>
  </li>
</ul>

A row with actions

<ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="s-actions" id="list-actions">
  <li class="cap-row">
    <span class="cap-row-status" id="a1-s"><span class="cap-status" data-tone="warn"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 1.2 15.4 14H.6z" /><path fill="var(--surface)" d="M7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z" /></svg>Blocked</span></span>
    <div class="cap-row-title"><a href="#job-push" aria-describedby="a1-s a1-d">Push design/capsomer and open a pull request</a></div>
    <p class="cap-row-detail" id="a1-d">capsomer-driver asks; it cannot reach main</p>
    <span class="cap-row-meta"><time datetime="2026-09-30T14:10Z">3 minutes ago</time></span>
    <div class="cap-row-actions">
      <button type="button" class="cap-btn" data-variant="primary" id="act-approve">Approve</button>
      <button type="button" class="cap-btn" id="act-decline">Decline</button>
    </div>
  </li>
</ul>

A long title, cut with an ellipsis

<ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="s-long" id="list-long">
  <li class="cap-row">
    <span class="cap-row-status" id="l1-s"><span class="cap-status" data-tone="info"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><rect x="1.5" y="1.5" width="13" height="13" rx="2" fill="none" stroke="currentColor" stroke-width="1.6" /><path fill="currentColor" d="M7.2 7h1.6v5H7.2zM7.2 4h1.6v1.7H7.2z" /></svg>Notice</span></span>
    <div class="cap-row-title"><a href="#mention" aria-describedby="l1-s l1-d" id="long-title">A mention on a reading list about the spring survey, its sampling and counting rules, the 2019 field notes paper, and why the measured numbers in that paper disagree with the model by a factor of two, and what the second team found when it counted them again with the same tally sheet, the same plots and a fresh count every time</a></div>
    <p class="cap-row-detail" id="l1-d">From a blog that has linked here three times this year, each time with a long excerpt and a request to reply</p>
    <span class="cap-row-meta"><time datetime="2026-09-30T08:00Z">6 hours ago</time></span>
  </li>
</ul>

A row that opens in place (a group)

<ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="s-group" id="list-group">
  <li class="cap-row">
    <span class="cap-row-status" id="g1-s"><span class="cap-status" data-tone="warn"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 1.2 15.4 14H.6z" /><path fill="var(--surface)" d="M7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z" /></svg>Warning</span></span>
    <div class="cap-row-title"><button type="button" aria-expanded="false" aria-controls="g1-kids" aria-describedby="g1-s g1-d" id="group-toggle">3 pull requests await the seat</button></div>
    <p class="cap-row-detail" id="g1-d">web, docs, billing</p>
    <span class="cap-row-meta"><time datetime="2026-09-30T13:47Z">26 minutes ago</time><span class="cap-row-chevron" aria-hidden="true"></span></span>
  </li>
</ul>
<p id="g1-kids" hidden>The rows it holds are shown here.</p>

Hover, and the outline and muted variants (shadcn's Item)

<ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="s-hover" data-gap="sm" id="list-variants">
  <li class="cap-row">
    <div class="cap-row-title"><a href="#hover-row">A row under the pointer</a></div>
    <p class="cap-row-detail">The title underlines and the row takes the raised tint</p>
    <span class="cap-row-meta">2 min</span>
  </li>
  <li class="cap-row" data-variant="outline">
    <span class="cap-row-media" data-variant="icon"><svg viewBox="0 0 16 16" aria-hidden="true"><path fill="none" stroke="currentColor" stroke-width="1.6" d="M3 2h7l3 3v9H3z" /></svg></span>
    <div class="cap-row-title"><a href="#outline-row">Outline variant, with an icon</a></div>
    <p class="cap-row-detail">The row draws its own edge, rows are separate cards</p>
    <span class="cap-row-meta">Draft</span>
  </li>
  <li class="cap-row" data-variant="muted" data-tone="crit">
    <span class="cap-row-media" data-variant="icon"><svg viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="6" fill="none" stroke="currentColor" stroke-width="1.6" /></svg></span>
    <div class="cap-row-title"><a href="#muted-row">Muted variant, critical</a></div>
    <p class="cap-row-detail">A tinted row; the critical edge stays</p>
    <span class="cap-row-meta">now</span>
  </li>
  <li class="cap-row" data-variant="outline" data-size="sm">
    <span class="cap-row-media" data-variant="image"><svg viewBox="0 0 16 16" aria-hidden="true"><rect width="16" height="16" fill="var(--accent)" /></svg></span>
    <div class="cap-row-title"><a href="#small-row">Small size with a picture</a></div>
    <p class="cap-row-detail">Small: tighter, with a smaller picture</p>
  </li>
  <li class="cap-row" data-variant="outline" data-size="xs">
    <div class="cap-row-title"><a href="#xs-row">Extra small size</a></div>
    <p class="cap-row-detail">Extra small: tighter still, a size smaller</p>
  </li>
</ul>

Comfortable density

<ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="s-comfortable" data-density="comfortable" id="list-comfortable">
  <li class="cap-row">
    <span class="cap-row-status"><span class="cap-status" data-tone="ok">Running</span></span>
    <div class="cap-row-title"><a href="#comfortable-1">Run the browser tests for capsomer</a></div>
    <p class="cap-row-detail">Held by capsid-driver, file 3 of 5</p>
    <span class="cap-row-meta">18 minutes ago</span>
  </li>
  <li class="cap-row">
    <span class="cap-row-status"><span class="cap-status" data-tone="nodata">Queued</span></span>
    <div class="cap-row-title"><a href="#comfortable-2">Refresh the uptime strip fixtures</a></div>
    <p class="cap-row-detail">Priority 2</p>
    <span class="cap-row-meta">1 hour ago</span>
  </li>
</ul>

A reply opened in a row

<div id="rl-reply" data-mount="reply"></div>

Phone width: the status above the title

<main class="specimen-page">
  <h1 id="phone-h">Queue</h1>
  <ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="phone-h" id="list-phone">
    <li class="cap-row">
      <span class="cap-row-status" id="p1-s"><span class="cap-status" data-tone="warn"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 1.2 15.4 14H.6z" /><path fill="var(--surface)" d="M7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z" /></svg>Blocked</span></span>
      <div class="cap-row-title"><a href="#job-push" aria-describedby="p1-s p1-d">Push design/capsomer</a></div>
      <p class="cap-row-detail" id="p1-d">Waits on: your approval</p>
      <span class="cap-row-meta"><time datetime="2026-09-30T14:10Z">3 minutes ago</time></span>
    </li>
    <li class="cap-row">
      <span class="cap-row-status" id="p2-s"><span class="cap-status" data-tone="ok"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="7" fill="currentColor" /><path fill="none" stroke="var(--surface)" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" d="m4.6 8.3 2.3 2.3 4.5-4.9" /></svg>Running</span></span>
      <div class="cap-row-title"><a href="#job-running" aria-describedby="p2-s p2-d">Run the browser tests</a></div>
      <p class="cap-row-detail" id="p2-d">Held by capsid-driver</p>
      <span class="cap-row-meta"><time datetime="2026-09-30T13:55Z">18 minutes ago</time></span>
    </li>
    <li class="cap-row">
      <span class="cap-row-status" id="p3-s"><span class="cap-status" data-tone="info"><svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true"><rect x="1.5" y="1.5" width="13" height="13" rx="2" fill="none" stroke="currentColor" stroke-width="1.6" /><path fill="currentColor" d="M7.2 7h1.6v5H7.2zM7.2 4h1.6v1.7H7.2z" /></svg>Notice</span></span>
      <div class="cap-row-title"><a href="#job-long" aria-describedby="p3-s p3-d" id="phone-long-title">Certificate for members.example.org renews in 21 days and the renewal has to be approved by hand</a></div>
      <p class="cap-row-detail" id="p3-d">Renewal is not automatic here</p>
      <span class="cap-row-meta">yesterday</span>
    </li>
  </ul>
</main>

API reference

RowList

PropTypeRequiredDoes
labelledBystringThe list's name: the heading id that names it (preferred), or a label.
labelstring
primarybooleanThe page's main list: j and k work on it even before focus is inside it. One per page.
gap"sm" | "xs" | "default"shadcn's ItemGroup gap: separate the rows (use with variant "outline" or "muted" on the rows).
childrenReactNodeYes

Row

PropTypeRequiredDoes
titleReactNodeYes
hrefstringThe row opens its detail by following href (a link), or by calling onOpen (a button) when the detail opens in place, such as a side panel. With neither, the row is read, not opened (a checklist step, a fact): its title is plain text, and only its actions are controls.
onOpen() => void
statusReactNodeA status (.cap-status: glyph, word and color), shown first.
detailReactNode
metaReactNodeThe time or other trailing fact, usually a .cap-time.
actionsReactNodeReal buttons, raised above the stretched link.
tone"crit"
variant"outline" | "muted"shadcn's Item variants and sizes: "outline" draws the row's edge, "muted" tints it.
size"sm" | "xs"
mediaReactNodeshadcn's ItemMedia, shown in the first column instead of a status: an icon or a picture.
mediaVariant"icon" | "image"
expandedbooleanA row that opens in place (a group of like rows): its button reports aria-expanded and names what it controls, and a chevron after the time turns when it is open.
controlsstring
classNamestringA class a composing component adds to the row (the attention list's cap-attention-child).
renderLink(props: RowLinkProps) => ReactNodeA router's link component; a plain <a> by default.
replyReactNodeA reply opened in the row (an answer to a question, a note that unblocks a job): a RowReply, shown under the row's text across the row, above the stretched link.

RowReply

PropTypeRequiredDoes
labelstringYesWhat the words are for, as the box's label: "Your answer, sent to its driver".
onSend(text: string) => string | void | Promise<string | void>YesSends the words; return a string to show why they were not sent ("Write what you did first").
onCancel() => voidYes
sendLabelstring
emptyHintstringShown when Send is pressed with nothing written.
failedHintstringShown when onSend throws or rejects; the draft stays in the box.
defaultValuestring
rowsnumber

Functions

FunctionSignatureDoes
usePlainRowForm(): RowFormThe default: a plain form that posts and loads the page the server answers with.
rowTargets(list: ParentNode): HTMLElement[]Every row's one link or button, in order, skipping rows hidden or disabled.
moveRowFocus(list: ParentNode, step: 1 | -1): HTMLElement | nullMoves focus to the next (1) or previous (-1) row's title. From outside the list, j starts at the first row and k at the last (the Portal's rule, App.tsx "step"). At either end focus stays where it is. Focus moves without the browser's own scroll, then the row is scrolled the least distance that shows it ("nearest"), as the Portal does: a row already in view does not jump, and the scroller's scroll-padding keeps it clear of a sticky bar. Returns the element focused, or null when nothing moved.
isTypingKey(e: KeyboardEvent): booleanA key typed into a field, or with a modifier, is never a list shortcut. A checkbox, a radio or a button is not a field (shortcuts' isTyping), so a list key works from a box a person has just ticked.
listOwnsKeys(list: HTMLElement): booleanWhether j and k should act on this list now: focus is in it, or it is the page's primary list and focus is in no other list and no open dialog.
queueKey(e: KeyboardEvent, list: HTMLElement | null | undefined): booleanThe keys a queue's rows share (approval queue, mentions list, moderation queue): j and k move through list as attachRowList does, and nothing acts on a held key, a key typed into a field, or while single keys are off. Returns true when the key is the caller's to act on (a, r, d, x).
attachRowList(list: HTMLElement): () => voidAttaches j and k to one list. Returns a function that detaches them. A list already attached (by enhance or by the React wrapper) is left alone, so keys never act twice.
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="row-list"] under root that is not attached yet. Returns a function that detaches them all.

Parts and data attributes

ClassIs
.cap-row-chevronits own class
.cap-row-mediaits own class
.cap-row-replyits own class
.cap-row-reply-actionsits own class
.cap-row-reply-formits own class
.cap-row-textits own class
.cap-rowsthe root
AttributeValues
data-gapsm xs
data-sizesm xs
data-staticpresent or absent
data-tonecrit
data-varianticon image muted outline
StateRead from
:focus-visiblethe platform
:hoverthe platform
[aria-expanded="true"]an attribute

Accessibility

KeyDoes
TabMoves to the next row's title, then into that row's actions, if any
jMoves focus to the next row's title (from outside the primary list, to its first row)
kMoves focus to the previous row's title (from outside the primary list, to its last row)
EnterFollows the focused row's link, or presses its button
Enter or Space on a group row's buttonShows or hides the rows it holds
  • A reply opens in its row (reply, with RowReply): answering a question or saying what unblocked a job happens where the row is, not on another page. The box is labeled for what the words are for ("Your answer, sent to its driver"), takes focus when it opens, says why an empty or refused reply was not sent (announced), sends on Ctrl or Cmd+Enter (not during an IME composition) and cancels on Esc. It sits under the row's text, across the row and above the stretched link.
  • A ul with role="list": Safari drops list semantics from a list with list-style: none otherwise.
  • The list is named by the heading above it (aria-labelledby).
  • One focus indicator, on the row, as an outline, so it survives forced colors; the critical edge turns CanvasText there.
  • The stretched hit area makes the whole row at least --target high.