Table of Contents: sticky TOC with scroll spy

A summary card built from your headings: an ink marker follows the section you read, a ring fills, the time left counts down. A bar on phones.

View the code Ask your AI

Navigation No dependencies tocscrollnavarticle Added Oct 2026

/anim/table-of-contents/ Fullscreen

With your AI

Just ask.

Say it to your AI. It gets the exact code below, not its best guess, and knows where it goes.

Add a Kodza Table of Contents to my long articles.

Not plugged in yet?

claude mcp add -t http kodza https://kodza.dev/api/mcp

Also in Codex, Cursor and VS Code.

kodza-table-of-contents.html

<nav class="kodza-toc" aria-label="On this page">
  <button class="kodza-toc__head" type="button" aria-expanded="true">
    <span class="kodza-toc__ring" aria-hidden="true">
      <svg viewBox="0 0 20 20"><circle class="kodza-toc__ring-track" cx="10" cy="10" r="8"/><circle class="kodza-toc__ring-fill" cx="10" cy="10" r="8" pathLength="1"/></svg>
    </span>
    <span class="kodza-toc__label">
      <span class="kodza-toc__title">On this page</span>
      <span class="kodza-toc__current"></span>
    </span>
    <span class="kodza-toc__percent">0%</span>
    <svg class="kodza-toc__chevron" viewBox="0 0 16 16" aria-hidden="true"><path d="M4 6.5 8 10.5l4-4"/></svg>
  </button>
  <div class="kodza-toc__body">
    <div class="kodza-toc__inner">
      <ol class="kodza-toc__list"></ol>
      <div class="kodza-toc__foot">
        <span class="kodza-toc__left"></span>
        <button class="kodza-toc__top" type="button">Back to top</button>
      </div>
    </div>
  </div>
</nav>

kodza-table-of-contents.css

/* Kodza License: free to use, client work included. Not to resell or redistribute, ported or not: https://kodza.dev/docs/#print-license */
/* Kodza — Table of Contents
   A summary card for a long article, built from its headings (h2 numbered, h3 nested): an ink
   marker slides to the section you are reading, a ring fills with your progress, the time
   left counts down, and "Back to top" shows up once you are in. Sticky beside the article;
   on small screens it folds into a bar that names the current section and opens on tap.
   In WordPress, set data-target=".entry-content".
   Everything is tuned with the --kz-toc-* variables. */
.kodza-toc {
  --kz-toc-bg: #ffffff;
  --kz-toc-fg: #0a0a0a;
  --kz-toc-muted: rgba(10, 10, 10, 0.6);
  --kz-toc-faint: rgba(10, 10, 10, 0.4);
  --kz-toc-line: rgba(10, 10, 10, 0.08);
  --kz-toc-ink: #0a0a0a;
  --kz-toc-top: 32px;
  --kz-toc-offset: 32px;
  --kz-toc-duration: 0.5s;
  --kz-toc-ease: cubic-bezier(0.22, 1, 0.36, 1);
  --kz-toc-mono: ui-monospace, "SF Mono", Menlo, monospace;

  position: sticky;
  top: var(--kz-toc-top);
  border-radius: 16px;
  background: var(--kz-toc-bg);
  box-shadow: inset 0 0 0 1px var(--kz-toc-line);
  color: var(--kz-toc-fg);
}

/* The head: progress ring, title (or the current section, folded), percentage */
.kodza-toc__head {
  display: flex;
  align-items: center;
  gap: 10px;
  width: 100%;
  padding: 16px 18px;
  border: 0;
  border-radius: 16px;
  background: none;
  color: inherit;
  font: inherit;
  text-align: left;
  cursor: pointer;
}

.kodza-toc__head:focus-visible,
.kodza-toc__link:focus-visible,
.kodza-toc__top:focus-visible {
  outline: 2px solid var(--kz-toc-fg);
  outline-offset: 2px;
}

.kodza-toc__ring svg {
  display: block;
  width: 20px;
  height: 20px;
  transform: rotate(-90deg);
}

.kodza-toc__ring circle {
  fill: none;
  stroke-width: 2.4;
}

.kodza-toc__ring-track {
  stroke: var(--kz-toc-line);
}

.kodza-toc__ring-fill {
  stroke: var(--kz-toc-ink);
  stroke-dasharray: 1;
  stroke-dashoffset: calc(1 - var(--kz-toc-read, 0));
  stroke-linecap: round;
}

.kodza-toc__label {
  display: grid;
  flex: 1;
  min-width: 0;
}

.kodza-toc__title,
.kodza-toc__current {
  grid-area: 1 / 1;
  overflow: hidden;
  font-size: 14px;
  font-weight: 600;
  letter-spacing: -0.01em;
  text-overflow: ellipsis;
  white-space: nowrap;
  transition: opacity 0.3s ease, transform 0.4s var(--kz-toc-ease);
}

/* Folded, the head names the section you are in */
.kodza-toc__current {
  opacity: 0;
  transform: translateY(6px);
}

.kodza-toc.is-folded .kodza-toc__title {
  opacity: 0;
  transform: translateY(-6px);
}

.kodza-toc.is-folded .kodza-toc__current:not(:empty) {
  opacity: 1;
  transform: none;
}

.kodza-toc.is-folded .kodza-toc__label:has(.kodza-toc__current:empty) .kodza-toc__title {
  opacity: 1;
  transform: none;
}

.kodza-toc__percent {
  font-family: var(--kz-toc-mono);
  font-size: 12px;
  color: var(--kz-toc-muted);
  font-variant-numeric: tabular-nums;
}

.kodza-toc__chevron {
  width: 16px;
  height: 16px;
  fill: none;
  stroke: var(--kz-toc-muted);
  stroke-width: 1.6;
  stroke-linecap: round;
  stroke-linejoin: round;
  transform: rotate(180deg);
  transition: transform var(--kz-toc-duration) var(--kz-toc-ease);
}

.kodza-toc.is-folded .kodza-toc__chevron {
  transform: none;
}

/* The body folds away by its row height: nothing jumps */
.kodza-toc__body {
  display: grid;
  grid-template-rows: 1fr;
  transition: grid-template-rows var(--kz-toc-duration) var(--kz-toc-ease);
}

.kodza-toc.is-folded .kodza-toc__body {
  grid-template-rows: 0fr;
}

.kodza-toc__inner {
  min-height: 0;
  overflow: hidden;
}

/* The list: a track, the part already read, and the marker on the current section */
.kodza-toc__list {
  position: relative;
  display: grid;
  margin: 0 18px;
  padding: 4px 0 12px 14px;
  border-top: 1px solid var(--kz-toc-line);
  list-style: none;
}

.kodza-toc__list::before,
.kodza-toc__fill,
.kodza-toc__marker {
  content: "";
  position: absolute;
  top: 12px;
  left: 0;
  width: 1px;
  height: calc(100% - 24px);
}

.kodza-toc__list::before {
  background: var(--kz-toc-line);
}

.kodza-toc__fill {
  background: var(--kz-toc-faint);
  transform: scaleY(var(--kz-toc-read, 0));
  transform-origin: top;
}

.kodza-toc__marker {
  top: 0;
  left: -0.5px;
  width: 2px;
  height: 1px;
  border-radius: 2px;
  background: var(--kz-toc-ink);
  opacity: var(--kz-toc-on, 0);
  transform: translateY(var(--kz-toc-y, 0)) scaleY(var(--kz-toc-h, 0));
  transform-origin: top;
}

.kodza-toc.is-live .kodza-toc__marker {
  transition: transform var(--kz-toc-duration) var(--kz-toc-ease), opacity 0.3s ease;
}

.kodza-toc__link {
  display: flex;
  gap: 10px;
  padding: 7px 0;
  border-radius: 6px;
  color: var(--kz-toc-muted);
  font-size: 14px;
  font-weight: 500;
  line-height: 1.4;
  text-decoration: none;
  transition: color 0.3s ease, transform 0.4s var(--kz-toc-ease);
}

.kodza-toc__link:hover {
  color: var(--kz-toc-fg);
}

.kodza-toc__link[aria-current="true"] {
  color: var(--kz-toc-fg);
  transform: translateX(3px);
}

.kodza-toc__num {
  flex-shrink: 0;
  width: 2ch;
  padding-top: 1px;
  font-family: var(--kz-toc-mono);
  font-size: 11px;
}

.kodza-toc__item--sub .kodza-toc__link {
  padding-left: calc(2ch + 10px);
  font-weight: 400;
}

/* The foot: the time left, and a way back up once you are in */
.kodza-toc__foot {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  margin: 0 18px;
  padding: 12px 0 16px;
  border-top: 1px solid var(--kz-toc-line);
  font-family: var(--kz-toc-mono);
  font-size: 12px;
  color: var(--kz-toc-muted);
}

.kodza-toc__top {
  padding: 4px 0;
  border: 0;
  border-radius: 4px;
  background: none;
  color: var(--kz-toc-fg);
  font: inherit;
  cursor: pointer;
  opacity: 0;
  transform: translateY(4px);
  visibility: hidden;
  transition: opacity 0.3s ease, transform 0.4s var(--kz-toc-ease), visibility 0s linear 0.4s;
}

.kodza-toc.is-in .kodza-toc__top {
  opacity: 1;
  transform: none;
  visibility: visible;
  transition-delay: 0s;
}

/* Small screens: a bar at the top of the screen, folded until tapped */
@media (max-width: 900px) {
  .kodza-toc {
    top: 12px;
    z-index: 20;
    box-shadow: inset 0 0 0 1px var(--kz-toc-line), 0 10px 30px -12px rgba(10, 10, 10, 0.2);
  }

  .kodza-toc__inner {
    max-height: 60vh;
    overflow-y: auto;
  }
}

@media (prefers-reduced-motion: reduce) {
  .kodza-toc.is-live .kodza-toc__marker,
  .kodza-toc__link,
  .kodza-toc__title,
  .kodza-toc__current,
  .kodza-toc__chevron,
  .kodza-toc__body,
  .kodza-toc__top {
    transition-duration: 0.01ms !important;
    transition-delay: 0s !important;
  }
}

/* Theming example — on a dark background:
.dark-section .kodza-toc {
  --kz-toc-bg: #161616;
  --kz-toc-fg: #f2f2f0;
  --kz-toc-muted: rgba(242, 242, 240, 0.6);
  --kz-toc-faint: rgba(242, 242, 240, 0.4);
  --kz-toc-line: rgba(255, 255, 255, 0.1);
  --kz-toc-ink: #f2f2f0;
}
*/

/* kodza-guard a34adb4d90d9 — generated by Kodza, do not edit.
   Theme guard: keeps a site's own CSS (WordPress themes, Bootstrap, CSS resets…) off this
   component. :not(#_) is always true and weighs as much as an id, so these lines win over
   theme rules made of classes and tags. Customise the component through its --kz-* variables. */

/* What the browser gives, where the component sets it only in some states: at the lowest weight, so its own rules below put it back */

:where(.kodza-toc__head):not(#_),
:where(.kodza-toc__link):not(#_),
:where(.kodza-toc__top):not(#_) {
  outline: revert;
  outline-offset: revert;
}

/* What the browser gives, on everything the component leaves to it */

.kodza-toc:not(#_) {
  border: revert;
  padding: revert;
  outline: revert;
  text-decoration: revert;
  transition: revert;
  list-style: revert;
  box-sizing: revert;
  outline-offset: revert;
  appearance: revert;
  max-height: revert;
  font-family: revert;
  font-size: revert;
  font-weight: revert;
  font-style: revert;
  line-height: revert;
  letter-spacing: revert;
  text-transform: revert;
  text-underline-offset: revert;
  text-align: revert;
  text-indent: revert;
  text-shadow: revert;
  vertical-align: revert;
}

.kodza-toc__head:not(#_) {
  margin: revert;
  text-decoration: revert;
  transition: revert;
  list-style: revert;
  box-sizing: revert;
  float: revert;
  position: revert;
  box-shadow: revert;
  appearance: revert;
  max-width: revert;
  max-height: revert;
  letter-spacing: revert;
  text-transform: revert;
  text-underline-offset: revert;
  text-indent: revert;
  text-shadow: revert;
  vertical-align: revert;
  white-space: revert;
  min-height: revert;
}

.kodza-toc__ring:not(#_),
.kodza-toc__ring-track:not(#_),
.kodza-toc__ring-fill:not(#_),
.kodza-toc__label:not(#_),
.kodza-toc__title:not(#_),
.kodza-toc__current:not(#_),
.kodza-toc__percent:not(#_),
.kodza-toc__body:not(#_),
.kodza-toc__inner:not(#_),
.kodza-toc__fill:not(#_),
.kodza-toc__marker:not(#_),
.kodza-toc__num:not(#_),
.kodza-toc__foot:not(#_),
.kodza-toc__left:not(#_) {
  box-sizing: revert;
}

.kodza-toc__chevron:not(#_) {
  border: revert;
  margin: revert;
  padding: revert;
  border-radius: revert;
  outline: revert;
  text-decoration: revert;
  list-style: revert;
  box-sizing: revert;
  float: revert;
  position: revert;
  background-color: revert;
  background-image: revert;
  box-shadow: revert;
  outline-offset: revert;
  appearance: revert;
  max-width: revert;
  max-height: revert;
  color: revert;
  font-family: revert;
  font-size: revert;
  font-weight: revert;
  font-style: revert;
  line-height: revert;
  letter-spacing: revert;
  text-transform: revert;
  text-underline-offset: revert;
  text-align: revert;
  text-indent: revert;
  text-shadow: revert;
  vertical-align: revert;
}

.kodza-toc__list:not(#_) {
  border-radius: revert;
  outline: revert;
  text-decoration: revert;
  transition: revert;
  box-sizing: revert;
  float: revert;
  border-right-width: revert;
  border-bottom-width: revert;
  border-left-width: revert;
  border-right-style: revert;
  border-bottom-style: revert;
  border-left-style: revert;
  border-right-color: revert;
  border-bottom-color: revert;
  border-left-color: revert;
  background-color: revert;
  background-image: revert;
  box-shadow: revert;
  outline-offset: revert;
  appearance: revert;
  max-width: revert;
  max-height: revert;
  color: revert;
  font-family: revert;
  font-size: revert;
  font-weight: revert;
  font-style: revert;
  line-height: revert;
  letter-spacing: revert;
  text-transform: revert;
  text-underline-offset: revert;
  text-align: revert;
  text-indent: revert;
  text-shadow: revert;
  vertical-align: revert;
}

.kodza-toc__item:not(#_),
.kodza-toc__ring svg:where(:not([class*="kodza-"])):not(#_) {
  border: revert;
  margin: revert;
  padding: revert;
  border-radius: revert;
  outline: revert;
  text-decoration: revert;
  transition: revert;
  list-style: revert;
  box-sizing: revert;
  float: revert;
  position: revert;
  background-color: revert;
  background-image: revert;
  box-shadow: revert;
  outline-offset: revert;
  appearance: revert;
  max-width: revert;
  max-height: revert;
  color: revert;
  font-family: revert;
  font-size: revert;
  font-weight: revert;
  font-style: revert;
  line-height: revert;
  letter-spacing: revert;
  text-transform: revert;
  text-underline-offset: revert;
  text-align: revert;
  text-indent: revert;
  text-shadow: revert;
  vertical-align: revert;
}

.kodza-toc__link:not(#_) {
  border: revert;
  margin: revert;
  list-style: revert;
  box-sizing: revert;
  float: revert;
  position: revert;
  background-color: revert;
  background-image: revert;
  box-shadow: revert;
  appearance: revert;
  max-width: revert;
  max-height: revert;
  font-family: revert;
  font-style: revert;
  letter-spacing: revert;
  text-transform: revert;
  text-underline-offset: revert;
  text-align: revert;
  text-indent: revert;
  text-shadow: revert;
  vertical-align: revert;
}

.kodza-toc__top:not(#_) {
  margin: revert;
  text-decoration: revert;
  list-style: revert;
  box-sizing: revert;
  float: revert;
  position: revert;
  box-shadow: revert;
  appearance: revert;
  max-width: revert;
  max-height: revert;
  letter-spacing: revert;
  text-transform: revert;
  text-underline-offset: revert;
  text-align: revert;
  text-indent: revert;
  text-shadow: revert;
  vertical-align: revert;
  white-space: revert;
  min-height: revert;
}

.kodza-toc:not(#_):where(:not([hidden])),
.kodza-toc__chevron:not(#_):where(:not([hidden])),
.kodza-toc__item:not(#_):where(:not([hidden])),
.kodza-toc__top:not(#_):where(:not([hidden])) {
  display: revert;
}

.kodza-toc:not(#_):where([hidden]),
.kodza-toc__chevron:not(#_):where([hidden]),
.kodza-toc__item:not(#_):where([hidden]),
.kodza-toc__top:not(#_):where([hidden]) {
  display: none;
}

.kodza-toc__list:not(#_)::before {
  box-sizing: revert;
}

/* The component's own rules, one step stronger: real buttons and fields, what it sets on tags themes style (links, lists, headings, images…), and the root width (a theme may narrow it, never widen it) */

.kodza-toc:not(#_) {
  position: sticky;
  border-radius: 16px;
  background: var(--kz-toc-bg);
  box-shadow: inset 0 0 0 1px var(--kz-toc-line);
  color: var(--kz-toc-fg);
}

.kodza-toc__head:not(#_) {
  display: flex;
  align-items: center;
  gap: 10px;
  width: 100%;
  padding: 16px 18px;
  border: 0;
  border-radius: 16px;
  background: none;
  color: inherit;
  font: inherit;
  text-align: left;
  cursor: pointer;
}

.kodza-toc__head:focus-visible:not(#_),
.kodza-toc__top:focus-visible:not(#_) {
  outline: 2px solid var(--kz-toc-fg);
  outline-offset: 2px;
}

.kodza-toc__link:focus-visible:not(#_) {
  outline: 2px solid var(--kz-toc-fg);
  outline-offset: 2px;
}

.kodza-toc__ring svg:not(#_) {
  display: block;
}

.kodza-toc__chevron:not(#_) {
  transition: transform var(--kz-toc-duration) var(--kz-toc-ease);
}

.kodza-toc__list:not(#_) {
  position: relative;
  display: grid;
  margin: 0 18px;
  padding: 4px 0 12px 14px;
  border-top: 1px solid var(--kz-toc-line);
  list-style: none;
}

.kodza-toc__link:not(#_) {
  display: flex;
  padding: 7px 0;
  border-radius: 6px;
  color: var(--kz-toc-muted);
  font-size: 14px;
  font-weight: 500;
  line-height: 1.4;
  text-decoration: none;
  transition: color 0.3s ease, transform 0.4s var(--kz-toc-ease);
}

.kodza-toc__link:hover:not(#_) {
  color: var(--kz-toc-fg);
}

.kodza-toc__link[aria-current="true"]:not(#_) {
  color: var(--kz-toc-fg);
}

.kodza-toc__item--sub .kodza-toc__link:not(#_) {
  padding-left: calc(2ch + 10px);
  font-weight: 400;
}

.kodza-toc__top:not(#_) {
  padding: 4px 0;
  border: 0;
  border-radius: 4px;
  background: none;
  color: var(--kz-toc-fg);
  font: inherit;
  cursor: pointer;
  opacity: 0;
  transform: translateY(4px);
  visibility: hidden;
  transition: opacity 0.3s ease, transform 0.4s var(--kz-toc-ease), visibility 0s linear 0.4s;
}

.kodza-toc.is-in .kodza-toc__top:not(#_) {
  opacity: 1;
  transform: none;
  visibility: visible;
  transition-delay: 0s;
}

@media (max-width: 900px) {
  .kodza-toc:not(#_) {
    box-shadow: inset 0 0 0 1px var(--kz-toc-line), 0 10px 30px -12px rgba(10, 10, 10, 0.2);
  }
}

@media (prefers-reduced-motion: reduce) {
  .kodza-toc__link:not(#_),
  .kodza-toc__chevron:not(#_) {
    transition-duration: 0.01ms !important;
    transition-delay: 0s !important;
  }
}

@media (prefers-reduced-motion: reduce) {
  .kodza-toc__top:not(#_) {
    transition-duration: 0.01ms !important;
    transition-delay: 0s !important;
  }
}

kodza-table-of-contents.js

// Kodza License: free to use, client work included. Not to resell or redistribute, ported or not: https://kodza.dev/docs/#print-license
// Kodza — Table of Contents
// Builds the list from the headings of the article next to it (data-target, or the nearest
// article / main / .entry-content), gives them ids if they have none, and follows the reading:
// current section, progress ring and percentage, time left, "Back to top". The head folds the
// list away (folded from the start on small screens, where the head names the current section).
(() => {
  const SELECTOR = '.kodza-toc';
  const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
  const small = window.matchMedia('(max-width: 900px)');
  const slug = (text) => text.toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'section';
  const WORDS_PER_MINUTE = 220;

  // One instance. Everything it starts is tied to `signal`, so kodza:destroy stops it all
  function mount(root, signal) {
    const list = root.querySelector('.kodza-toc__list');
    const head = root.querySelector('.kodza-toc__head');
    const current = root.querySelector('.kodza-toc__current');
    const percent = root.querySelector('.kodza-toc__percent');
    const left = root.querySelector('.kodza-toc__left');
    const top = root.querySelector('.kodza-toc__top');
    const selector = root.dataset.target || 'article, main, .entry-content';
    // The closest article around (or beside) the summary
    let scope = root.parentElement;
    while (scope && !scope.querySelector(selector)) scope = scope.parentElement;
    const article = scope?.querySelector(selector);
    if (!list || !article) return;
    const headings = [...article.querySelectorAll(root.dataset.headings || 'h2, h3')];
    if (!headings.length) return;
    const minutes = Math.max(1, Math.round(article.textContent.trim().split(/\s+/).length / WORDS_PER_MINUTE));
    const offset = () => parseFloat(getComputedStyle(root).getPropertyValue('--kz-toc-offset')) || 0;
    const goTo = (y) => window.scrollTo({ top: y, behavior: reduceMotion ? 'auto' : 'smooth' });

    let number = 0;
    const named = []; // the headings given an id here, which lose it again on abort
    const links = headings.map((heading) => {
      if (!heading.id) {
        let id = slug(heading.textContent);
        for (let n = 2; document.getElementById(id); n++) id = `${slug(heading.textContent)}-${n}`;
        heading.id = id;
        named.push(heading);
      }
      const sub = heading.tagName === 'H3';
      const item = document.createElement('li');
      item.className = `kodza-toc__item${sub ? ' kodza-toc__item--sub' : ''}`;
      const link = document.createElement('a');
      link.className = 'kodza-toc__link';
      link.href = `#${heading.id}`;
      if (!sub) {
        const num = document.createElement('span');
        num.className = 'kodza-toc__num';
        num.setAttribute('aria-hidden', 'true');
        num.textContent = String(++number).padStart(2, '0');
        link.append(num);
      }
      link.append(heading.textContent);
      link.addEventListener('click', (event) => {
        event.preventDefault();
        goTo(heading.getBoundingClientRect().top + window.scrollY - offset());
        history.replaceState(null, '', `#${heading.id}`);
        if (small.matches) fold(true);
      }, { signal });
      item.append(link);
      return link;
    });
    signal.addEventListener('abort', () => named.forEach((heading) => heading.removeAttribute('id')));

    const fill = document.createElement('span');
    const marker = document.createElement('span');
    fill.className = 'kodza-toc__fill';
    marker.className = 'kodza-toc__marker';
    fill.setAttribute('aria-hidden', 'true');
    marker.setAttribute('aria-hidden', 'true');
    list.replaceChildren(fill, marker, ...links.map((link) => link.parentElement));

    const fold = (on) => {
      root.classList.toggle('is-folded', on);
      head?.setAttribute('aria-expanded', String(!on));
    };
    head?.addEventListener('click', () => fold(!root.classList.contains('is-folded')), { signal });
    top?.addEventListener('click', () => goTo(article.getBoundingClientRect().top + window.scrollY - offset()), { signal });

    let active = -2;
    const update = () => {
      // The section being read: the last heading above the top third of the screen
      const line = innerHeight * 0.3;
      let index = -1;
      headings.forEach((heading, i) => {
        if (heading.getBoundingClientRect().top <= line) index = i;
      });
      const box = article.getBoundingClientRect();
      const read = Math.min(1, Math.max(0, (line - box.top) / Math.max(1, box.height - innerHeight * 0.5)));
      root.style.setProperty('--kz-toc-read', read.toFixed(4));
      if (percent) percent.textContent = `${Math.round(read * 100)}%`;
      if (left) left.textContent = read > 0.98 ? 'All read' : `${Math.max(1, Math.ceil(minutes * (1 - read)))} min left`;
      root.classList.toggle('is-in', read > 0.08);
      if (index === active) return;
      active = index;
      links.forEach((link, i) => link.setAttribute('aria-current', String(i === index)));
      const link = links[index];
      if (current) current.textContent = link ? link.lastChild.textContent : '';
      root.style.setProperty('--kz-toc-on', link ? 1 : 0);
      if (link) {
        root.style.setProperty('--kz-toc-y', `${link.parentElement.offsetTop}px`);
        root.style.setProperty('--kz-toc-h', link.parentElement.offsetHeight);
      }
    };

    let ticking = false;
    window.addEventListener('scroll', () => {
      if (ticking) return;
      ticking = true;
      requestAnimationFrame(() => {
        if (signal.aborted) return;
        ticking = false;
        update();
      });
    }, { passive: true, signal });
    window.addEventListener('resize', () => {
      active = -2;
      update();
    }, { signal });
    small.addEventListener?.('change', (event) => fold(event.matches), { signal });

    fold(small.matches);
    update();
    requestAnimationFrame(() => !signal.aborted && root.classList.add('is-live'));
  }

  // Kodza lifecycle, the same in every component: `kodza:init` starts the instances inside
  // event.detail.root (the whole page by default), `kodza:destroy` stops them and puts their
  // markup back. For themes and apps that swap content without a page load.
  const instances = new WeakMap();
  const find = (scope = document) => [scope, ...scope.querySelectorAll(SELECTOR)].filter((el) => el.matches?.(SELECTOR));
  const init = (scope) => find(scope).forEach((root) => {
    if (root.classList.contains('is-ready')) return; // already running, maybe from another copy of this script
    const controller = new AbortController();
    instances.set(root, { controller, html: root.innerHTML, attrs: [...root.attributes].map((a) => [a.name, a.value]) });
    mount(root, controller.signal);
    root.classList.add('is-ready');
  });
  const destroy = (scope) => find(scope).forEach((root) => {
    const instance = instances.get(root);
    if (!instance) return;
    instances.delete(root);
    instance.controller.abort();
    [...root.attributes].forEach((a) => root.removeAttribute(a.name));
    instance.attrs.forEach(([name, value]) => root.setAttribute(name, value));
    root.innerHTML = instance.html;
  });
  document.addEventListener('kodza:init', (event) => init(event.detail?.root));
  document.addEventListener('kodza:destroy', (event) => destroy(event.detail?.root));
  init();
  // Loaded in <head>, the script runs before the markup exists: once more when it is parsed
  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', () => init(), { once: true });
})();

TableOfContents.tsx

'use client';
// Kodza — Table of Contents, for React. From https://kodza.dev/components/table-of-contents/
// Kodza License: free to use, client work included. Not to resell or redistribute, ported or not: https://kodza.dev/docs/#print-license
// Next to this file: table-of-contents.css and table-of-contents.js, the component's CSS and JS from Kodza, as they are.
// Yours to edit: the markup is plain JSX below.
// The script changes this markup once React has rendered it (it adds layers, splits text, moves
// nodes), so React must not patch it afterwards. When a prop changes, the key gives React a fresh
// element: kodza:destroy stops the script on the old one, kodza:init starts it on the new one.
import { useRef, useEffect, type ComponentPropsWithoutRef, type ComponentRef, type CSSProperties } from 'react';
import './table-of-contents.css';

export type TableOfContentsProps = Omit<ComponentPropsWithoutRef<'nav'>, "children" | "vars"> & {
  /** Settings, as CSS variables on the root */
  vars?: {
    /** default: #ffffff */
    "--kz-toc-bg"?: string | number;
    /** default: #0a0a0a */
    "--kz-toc-fg"?: string | number;
    /** default: rgba(10, 10, 10, 0.6) */
    "--kz-toc-muted"?: string | number;
    /** default: rgba(10, 10, 10, 0.4) */
    "--kz-toc-faint"?: string | number;
    /** default: rgba(10, 10, 10, 0.08) */
    "--kz-toc-line"?: string | number;
    /** default: #0a0a0a */
    "--kz-toc-ink"?: string | number;
    /** default: 32px */
    "--kz-toc-top"?: string | number;
    /** default: 32px */
    "--kz-toc-offset"?: string | number;
    /** default: 0.5s */
    "--kz-toc-duration"?: string | number;
    /** default: cubic-bezier(0.22, 1, 0.36, 1) */
    "--kz-toc-ease"?: string | number;
    /** default: ui-monospace, "SF Mono", Menlo, monospace */
    "--kz-toc-mono"?: string | number;
  };
  className?: string;
};

export function TableOfContents({ vars, className, style, ...rest }: TableOfContentsProps) {
  const ref = useRef<ComponentRef<'nav'>>(null);
  const classes = ["kodza-toc", className].filter(Boolean).join(' ');
  // Everything the markup is made of: when it changes, React gets a fresh element (see the top)
  const key = JSON.stringify([classes, vars, style, rest]);

  // Starts the script on this element once React has rendered it, stops it when it goes
  useEffect(() => {
    const root = ref.current;
    let live = true;
    // @ts-ignore: a plain script, no types to find
    import('./table-of-contents.js').then(() => {
      if (live) document.dispatchEvent(new CustomEvent('kodza:init', { detail: { root } }));
    });
    return () => {
      live = false;
      document.dispatchEvent(new CustomEvent('kodza:destroy', { detail: { root } }));
    };
  }, [key]);

  return (
    <nav aria-label="On this page" key={key} {...rest} className={classes} style={{ ...vars, ...style } as CSSProperties} ref={ref}>
      <button className="kodza-toc__head" type="button" aria-expanded="true">
        <span className="kodza-toc__ring" aria-hidden="true">
          <svg viewBox="0 0 20 20">
            <circle className="kodza-toc__ring-track" cx="10" cy="10" r="8" />
            <circle className="kodza-toc__ring-fill" cx="10" cy="10" r="8" pathLength="1" />
          </svg>
        </span>
        {' '}
        <span className="kodza-toc__label">
          <span className="kodza-toc__title">On this page</span>
          {' '}
          <span className="kodza-toc__current" />
        </span>
        {' '}
        <span className="kodza-toc__percent">0%</span>
        {' '}
        <svg className="kodza-toc__chevron" viewBox="0 0 16 16" aria-hidden="true">
          <path d="M4 6.5 8 10.5l4-4" />
        </svg>
      </button>
      <div className="kodza-toc__body">
        <div className="kodza-toc__inner">
          <ol className="kodza-toc__list" />
          <div className="kodza-toc__foot">
            <span className="kodza-toc__left" />
            {' '}
            <button className="kodza-toc__top" type="button">Back to top</button>
          </div>
        </div>
      </div>
    </nav>
  );
}

Checked

Checked before you paste.

Robots poked at it before you did. Every component goes through the same checks, and again each time it changes.

What ranLast run Oct 19, 2026

Accessibilityaxe-core 4.10.2: the WCAG 2.1 A and AA rules, plus best practices. 0 issues

KeyboardThe Tab key gets there, and the focus ring shows when it does. Passed

Reduced motionTurn on reduced motion and what moved just appears. Nothing loops. Passed

Light and darkThe same checks on both themes, contrast included. Passed

WordPressPasted into Twenty Twenty-Five, Twenty Twenty-One, Astra, Blocksy, GeneratePress, Hello Elementor, Kadence and OceanWP. Nothing to flag. 8 / 8 themes

Robots checked this. A human with VoiceOver hasn't yet.