Skip to content

Table of contents

A post's headings as links, a sticky column when wide or a disclosure when narrow.

<div class="toc-demo" id="toc-demo">
  <nav class="cap-toc" data-variant="sidebar" data-cap="toc" aria-labelledby="toc-side-t" id="toc-side">
    <p class="cap-toc-title" id="toc-side-t">Contents</p>
    <ol class="cap-toc-list"><li class="cap-toc-item"><a class="cap-toc-link" href="#t-why">Why payments fail</a></li><li class="cap-toc-item" data-level="3"><a class="cap-toc-link" href="#t-cards">Expired cards</a></li><li class="cap-toc-item"><a class="cap-toc-link" href="#t-retry">When to retry</a></li><li class="cap-toc-item"><a class="cap-toc-link" href="#t-notes">Field notes</a></li></ol>
  </nav>
  <article class="toc-demo-post">
    <h3 id="t-why">Why payments fail</h3><p>Most failed payments are soft declines that a later try clears.</p>
    <h4 id="t-cards">Expired cards</h4><p>A card past its date fails every try until it is updated.</p>
    <h3 id="t-retry">When to retry</h3><p>Retry on the days a bank settles, not every hour.</p>
    <h3 id="t-notes">Field notes</h3><p>What the spring update changed.</p>
  </article>
</div>

Installation

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

enhance();

Usage

<nav class="cap-toc" data-variant="sidebar" data-cap="toc" aria-labelledby="toc-t">
  <p class="cap-toc-title" id="toc-t">Contents</p>
  <ol class="cap-toc-list">
    <li class="cap-toc-item"><a class="cap-toc-link" href="#why">Why it fails</a></li>
    <li class="cap-toc-item" data-level="3"><a class="cap-toc-link" href="#retries">Retries</a></li>
  </ol>
</nav>

<details class="cap-toc" data-variant="inline">
  <summary class="cap-toc-title">Contents</summary>
  <nav data-cap="toc" aria-label="Contents"><ol class="cap-toc-list">...</ol></nav>
</details>

Examples

Inline, on a narrow screen: closed, and open

<details class="cap-toc" data-variant="inline" id="toc-inline-closed">
  <summary class="cap-toc-title">Contents</summary>
  <nav data-cap="toc" aria-label="Contents"><ol class="cap-toc-list"><li class="cap-toc-item"><a class="cap-toc-link" href="#t-why">Why payments fail</a></li><li class="cap-toc-item" data-level="3"><a class="cap-toc-link" href="#t-cards">Expired cards</a></li><li class="cap-toc-item"><a class="cap-toc-link" href="#t-retry">When to retry</a></li><li class="cap-toc-item"><a class="cap-toc-link" href="#t-notes">Field notes</a></li></ol></nav>
</details>
<details class="cap-toc" data-variant="inline" open>
  <summary class="cap-toc-title">Contents</summary>
  <nav aria-label="Contents"><ol class="cap-toc-list"><li class="cap-toc-item"><a class="cap-toc-link" href="#t-why">Why payments fail</a></li><li class="cap-toc-item" data-level="3"><a class="cap-toc-link" href="#t-cards">Expired cards</a></li><li class="cap-toc-item"><a class="cap-toc-link" href="#t-retry">When to retry</a></li><li class="cap-toc-item"><a class="cap-toc-link" href="#t-notes">Field notes</a></li></ol></nav>
</details>

API reference

Toc

PropTypeRequiredDoes
itemsTocItem[]Yes
variant"sidebar" | "inline"Yes"sidebar": a sticky column, shown from 64rem. "inline": a disclosure, shown under 64rem. Render both for a post that has a sidebar column on a wide screen.
titleReactNode
minnumberUnder this many items nothing renders: a short post needs no contents.

Functions

FunctionSignatureDoes
linkedHeadings(nav: Element): HTMLElement[]The headings a contents list links to, in its order.
markCurrent(nav: Element, id: string | null): void
attach(nav: HTMLElement): () => voidOne contents list: a click scrolls to its section, and the current section is marked as the page scrolls. Returns a function that undoes it.
enhance(root?: ParentNode): () => void

Parts and data attributes

ClassIs
.cap-tocthe root
.cap-toc-itema part
.cap-toc-linka part
.cap-toc-lista part
.cap-toc-titlea part
AttributeValues
data-level3
data-variantinline sidebar
StateRead from
:hoverthe platform
[aria-current="location"]an attribute
[open]an attribute

Accessibility

KeyDoes
TabMoves through the links (inline: the summary first)
Enter, SpaceOn the summary: opens or closes the contents
EnterOn a link: scrolls to the heading and moves focus to it
  • The sidebar is a nav named by its visible title; the inline one is a nav named "Contents" inside the details.
  • The current link's mark is a 2px edge and the text color; in forced colors the edge is drawn in LinkText.
  • The + and − are CSS content with empty alternative text, so they are not read.