Table of Contents

Adds a floating “On this page” menu to long pages. It reads the headings on your page and builds the list for you, so there’s nothing to type and nothing to keep in sync when you edit your content.

On desktop it sits on the right edge of the screen as a stack of small lines, one per heading. Hover over it and the full list slides open. On phones it turns into a small Contents button at the bottom of the screen that opens a sheet. The CSS and JS ship with the component, so there is nothing else to load.

1. Import Component

1. Click Copy JSON above and paste it into any Etch page (Cmd/Ctrl + V on the canvas).
2. Place it right before your article content, after the title and intro. It floats on screen no matter where you put it, but keyboard and screen reader users reach it in structure order. Putting it first lets them use it to jump ahead instead of finding it after the whole article.
3. Make sure your content has headings (H2 and H3 by default) inside the <main> element. If your content lives somewhere else, change the Content Selector property.
4. Adjust the component properties in the sidebar.

Tip: Drop it into your blog post or docs template once and every post gets its own table of contents automatically.

2. How It Works

Where to Place It

The menu looks the same wherever it sits in the structure panel, but placement still matters for accessibility. Keyboard users tab through the page in structure order, and screen readers read it in that order too. Put the component just before your content so they reach it first. It only adds one tab stop, since the links stay hidden until the menu is opened. Avoid placing it inside your site header, and keep it out of wrappers that use transform, filter or backdrop-filter, since those stop it from floating.

Builds Itself From Your Headings

Every heading it finds becomes a link. If a heading doesn’t have an ID yet, one is created from the heading text (for example, “Gear you actually need” becomes #gear-you-actually-need). Headings you already gave an ID keep it.

Shows Where You Are

As the reader scrolls, the current section is highlighted and a small marker slides down the rail to follow along. Inside the open panel or mobile sheet, a soft highlight sits behind the current section’s link and glides to the next one as you read. Hover over (or tab to) another link and the highlight slides over to it, then returns to where you are when you move away. Short sections near the bottom of the page still get their turn, even if they can’t scroll all the way to the top.

Desktop Rail, Mobile Pill

Above the breakpoint (768px by default) you get the slim rail on the right. Below it, you get a Contents pill at the bottom of the screen with a ring that fills up as you scroll. Tap it and the list opens as a sheet. You can also lock it to one style with the Mode property.

Only Shows Up When It’s Useful

If a page has fewer headings than the Minimum Headings setting (2 by default), the menu hides itself. It also fades away when your content scrolls out of view, like when the reader reaches the footer.

Stays in Sync

If your headings change after the page loads (filters, tabs, content loaded in later, or editing in the builder), the list rebuilds itself. Hidden headings and empty headings are skipped.

Smooth Jumps With Room for Your Header

Clicking a link smoothly scrolls to that heading. If you have a sticky header, set Scroll Offset so the heading doesn’t end up hidden underneath it.

Handles Messy Outlines

If you skip a level (an H2 followed by an H4), the H4 still indents just one step, so the list always looks tidy.

Accessibility

The menu is a proper navigation landmark named after its title, so screen reader users can jump straight to it. The current section is announced, Esc closes the menu, and after clicking a link, keyboard focus moves to that heading so the next Tab continues from there. On desktop, a short hover delay keeps the panel from flashing open when your cursor just passes by, and clicking the rail pins it open.

Reduced Motion

Users with prefers-reduced-motion turned on get instant jumps and no sliding or staggered animations. The link highlight still follows along, it just moves instantly instead of gliding.

Print

The menu is hidden when the page is printed.

3. Component Properties

Each instance has a set of component properties that control its behavior.

For colors, sizes, spacing and animation timing, see the Customization page. For scripting, see the JavaScript API page.

This page covers everything you can change beyond the component properties, without touching the JS. Most sites only need to change a color or two.

Available CSS Variables

These CSS variables control how the menu looks. Set them on the .c-toc root (inline, in a class added with the TOC Class property, or globally on :root). The defaults use your ACSS colors and spacing when they’re available, so the menu matches your site out of the box.

Position and layering

The panel

Links

Desktop rail and marker

Mobile pill

The pill sizes itself from its font size, so changing --toc-pill-font-size scales the whole thing. The rest are optional fine-tuning.

Animation timing

Example:

<nav
  class="c-toc"
  style="
    --toc-panel-width: 300px;
    --toc-link-active-color: var(--primary);
    --toc-marker-color: var(--primary);
    --toc-indicator-bg: var(--primary-ultra-light);
  "
>
  ...
</nav>

Working with a sticky header

If your header stays stuck to the top of the screen, it can cover the heading you just jumped to. There are three ways to fix it. Pick one.

• Scroll Offset property: the easiest. Type your header height, like 80 or var(--header-height).
• --toc-offset variable: same result, but you can use a different value on mobile with a media query.
• Your own CSS: if your site already sets scroll-margin-top on headings or scroll-padding-top on the page, leave the offset empty and the menu respects it.

Leaving headings out

Some headings shouldn’t be in the menu, like the ones in a sidebar, a newsletter box or a related posts section. You have two options:

• Add the data-toc-ignore attribute to the heading, or to any element wrapped around it.
• Put a selector in the Exclude Selector property, like .sidebar, .newsletter.

Styling the parts

Useful selectors if you want to go beyond the variables:

.c-toc { /* the whole menu */ }
.c-toc__rail { /* desktop rail button */ }
.c-toc__marker { /* sliding marker on the rail */ }
.c-toc__line { /* one rail line per heading */ }
.c-toc__pill { /* mobile Contents button */ }
.c-toc__panel { /* the panel / mobile sheet */ }
.c-toc__title { /* "On This Page" label */ }
.c-toc__close { /* close button in the mobile sheet */ }
.c-toc__list { /* the list of links */ }
.c-toc__list::before { /* sliding highlight behind the current link */ }
.c-toc__link { /* every link */ }
.c-toc__link--sub { /* links for nested headings */ }
.c-toc__link[aria-current] { /* the current section */ }

State attributes

The menu adds these attributes to the .c-toc root, so you can style it based on what it’s doing.

• [data-state="open"] / [data-state="closed"]: whether the panel is open.
• [data-mode="desktop"] / [data-mode="mobile"]: whether it’s showing the rail or the pill.
• [data-in-view]: your content is on screen, so the menu is visible.
• [hidden]: the page doesn’t have enough headings, so the menu is hidden.

Without JavaScript

The menu is built by the script, so without JavaScript it simply doesn’t show. Your headings and content are untouched.

Common recipes

Brand-colored current section

.c-toc {
  --toc-link-active-color: var(--primary);
  --toc-line-active-color: var(--primary);
  --toc-marker-color: var(--primary);
}

Dark panel

.c-toc {
  --toc-panel-bg: #111;
  --toc-panel-border: #222;
  --toc-link-color: #aaa;
  --toc-link-active-color: #fff;
  --toc-link-hover-bg: #1c1c1c;
}

Different header offset on mobile

Leave the Scroll Offset property empty and use the variable instead:

.c-toc { --toc-offset: 100px; }

@media (max-width: 767px) {
  .c-toc { --toc-offset: 70px; }
}

Only include one part of the page

Set Content Selector to the wrapper around your article, like .post-content. The menu only lists headings inside it and only shows while that part of the page is on screen.

Most sites don’t need any of this. The menu sets itself up on every .c-toc on the page as soon as the page loads. Reach for the JavaScript API when you want to open or close the menu from your own button, jump to a section from code, rebuild the list after a big content change, or remove the menu cleanly.

Getting an instance

Once it’s set up, each menu has its instance attached as _toc:

const toc = document.querySelector(".c-toc")._toc;
toc.open();

If you’d rather grab them all at once, TableOfContents.init() returns every instance:

const [toc] = TableOfContents.init(".c-toc");
if (toc) toc.scrollTo("the-recipe");

Or create one directly on an element you already have:

const nav = document.querySelector(".my-toc");
const toc = new TableOfContents(nav);

Instance methods

Instance properties

Settings as attributes

Each component property is written to the .c-toc element as a data- attribute. Change one with JavaScript and the menu updates on its own, no need to call refresh().

Static methods

Examples

Open the menu from your own button

const toc = document.querySelector(".c-toc")._toc;

document.querySelector("#show-contents").addEventListener("click", () => {
  toc.open();
});

Jump to a section from code

document.querySelector(".c-toc")._toc.scrollTo("common-mistakes");

Know when the menu opens or closes
There are no custom events. Watch the data-state attribute instead:

const nav = document.querySelector(".c-toc");

new MutationObserver(() => {
  console.log("menu is", nav.dataset.state); // "open" or "closed"
}).observe(nav, { attributes: true, attributeFilter: ["data-state"] });

Show which section the reader is in

const toc = document.querySelector(".c-toc")._toc;

window.addEventListener("scroll", () => {
  document.querySelector("#current-section").textContent =
    toc.active ? toc.active.text : "";
}, { passive: true });

Switch to the pill layout from code
Works when Mode is set to Responsive, since that outputs both the rail and the pill.

document.querySelector(".c-toc").dataset.layout = "pill";

Set up a menu added after page load

// after dropping new .c-toc markup into the page
TableOfContents.init(".new-section .c-toc");

Clean teardown before removing it

const nav = document.querySelector(".c-toc");
nav._toc.destroy();
nav.remove();