Overview

A sticky table of contents, generated on the page from the headings of a sibling content area, with the section the reader is in highlighted as they scroll. Every page of this wiki uses it.


Usage

Place the block beside the content it should index — typically in the narrow column of a two-column grid, with the content in the wide column — and point Target selector at a class on the content column. The selector is a plain document.querySelector() argument, so give the content column a class of its own (this wiki uses .method-doc-content on the content’s method/advanced-grid-col) rather than relying on a generated one. Choose which heading levels make the list (H2–H4; H3s nest under H2s), a sticky offset when the site has a fixed header, and the width at which the block becomes sticky; below that width it flows with the page.

This is the block as every page of this wiki stores it:

HTML
<!-- wp:method/scrollspy {"targetSelector":".method-doc-content","stickyOffset":152,"textColor":"#261A3A","linkColor":"#261A3A","linkHoverColor":"#563D7C","linkActiveColor":"#563D7C"} /-->

Headings without an id get one generated from their text (lowercased, non-alphanumerics collapsed to -, deduplicated with a counter), so the links work on content that was never given anchors. Headings that already have an id keep it. When the target has no matching headings the nav is hidden; when the target selector matches no element at all the nav is left as printed — the label over an empty list — so check the selector on a page that shows one.


Attributes

AttributeTypeDefaultDescription
targetSelectorstring".docs-content"CSS selector of the container whose headings are listed. Printed as data-target.
labelstring"On this page"The heading above the list, and the nav’s aria-label.
headingLevelsarray["h2","h3"]Which heading tags to list; h1–h6 are accepted on render, the editor offers H2–H4. Printed as data-levels (comma-separated). The highest level present becomes the top of the list; each level below it is a --sub then --deep item.
stickyOffsetnumber0Pixels between the top of the viewport and the stuck nav. Also offsets the active-heading observer and the click scroll. Printed as data-sticky-offset and set as --scrollspy-offset.
stickyAtstring"md"Theme breakpoint key at and above which the nav is sticky. Resolved to its pixel value on render through method_get_all_bs_breakpoint_options() (e.g. md → 768px) and printed as data-sticky-at.
textColorstring—Color of the label.
linkColorstring—Color of the links.
linkHoverColorstring—Hover and :focus-visible color of the links.
linkActiveColorstring—Color of the active link (.is-active).

The block has no responsiveSettings; the four colors are the only generated CSS, scoped to the instance id.


Control Sets

ComponentPanelBreakpointsNotes
Block panel: Scrollspy SettingsScrollspy SettingsbaseTarget selector, Label, Heading levels to include (H2 / H3 / H4 checkboxes; at least one stays checked), Sticky top offset (px) (0–200, step 4), Width to Become Sticky.
MethodBreakpointSelectScrollspy SettingsbaseWrites a theme breakpoint key to stickyAt; the options come from the theme’s configured breakpoints.
MethodColorControlsColor Settingsbaseinclude={['textColor', 'linkColor', 'linkHoverColor', 'linkActiveColor']}

The editor shows a labelled placeholder list with the chosen colors as swatches rather than a live table of contents — the headings live in another block, and the list is built on the page.


Data & Dependencies

  • Breakpoints: method_get_all_bs_breakpoint_options() reads the breakpoints.dimensions map from METHOD_CHILD_OPTIONS (or METHOD_OPTIONS) and returns each key with its pixel hint; the render callback looks stickyAt up in it. On the page the view script toggles is-sticky on the nav from matchMedia( '(min-width: …)' ), and the stylesheet gates position: sticky on that class.
  • Active state: an IntersectionObserver over the listed headings with a rootMargin of -{offset}px 0px -70% 0px, so a heading becomes active as it enters the top 30% of the viewport; the topmost visible heading wins, and when none is visible the last active one stays. The active link is scrolled into view inside the nav when the list overflows.
  • Clicks: the list’s click handler scrolls smoothly to the heading minus the offset and 16px, then history.pushState()s the hash. A hash in the URL on load marks the matching heading active.
  • Sticky inside Method layouts: overflow: hidden on an ancestor creates a scroll container that breaks position: sticky, so assets/scss/global.scss sets overflow: clip !important on .wp-site-blocks:has(.method-scrollspy) and .method-container-content:has(.method-scrollspy). The nav is align-self: start with a max-height of the viewport minus the offset; the scrollable area is .method-scrollspy__inner, not the nav itself.
  • Custom properties: --scrollspy-offset, --scrollspy-active-color, --scrollspy-text-color, --scrollspy-muted-color, --scrollspy-border-color, --scrollspy-font-size, --scrollspy-line-height, --scrollspy-transition on .method-scrollspy, with theme preset colors as the fallbacks. The four color attributes override the first three through the generated instance CSS.
  • Responsive CSS: method_get_block_responsive_styles() and method_collect_css(), as in every Method block.

Frontend Rendering

What PHP prints:

HTML
<nav class="wp-block-method-scrollspy method-scrollspy" id="method-68f1b2c3a4d5e" data-target=".method-doc-content" data-levels="h2,h3" data-sticky-offset="152" data-sticky-at="768px" aria-label="On this page">
  <div class="method-scrollspy__inner">
    <p class="method-scrollspy__label">On this page</p>
    <ol class="method-scrollspy__list" role="list"></ol>
  </div>
</nav>

What the view script makes of it:

HTML
<nav class="… method-scrollspy is-sticky" style="--scrollspy-offset: 152px;" …>
  <div class="method-scrollspy__inner">
    <p class="method-scrollspy__label">On this page</p>
    <ol class="method-scrollspy__list" role="list">
      <li class="method-scrollspy__item is-active"><a href="#overview" class="method-scrollspy__link is-active">Overview</a></li>
      <li class="method-scrollspy__item"><a href="#attributes" class="method-scrollspy__link">Attributes</a></li>
      <li class="method-scrollspy__item method-scrollspy__item--sub"><a href="#responsivesettings-structure" class="method-scrollspy__link">responsiveSettings Structure</a></li>
      …
    </ol>
  </div>
</nav>

Generated CSS (per instance): #method-{id} .method-scrollspy__label → color; … .method-scrollspy__link → linkColor; … .method-scrollspy__link:hover, … :focus-visible → linkHoverColor; … .method-scrollspy__link.is-active → linkActiveColor.


Filters

This block exposes no PHP filters. The heading ids it generates are the ones a page’s anchor links should use; give a heading an explicit id (the editor’s HTML anchor) to control it.


Changelog

VersionDescription
2.0.0-beta5Introduced (ccc789b).
2.0.0-beta17Inserter title prefixed, “Method Scrollspy”, like every top-level Method block (c34e9bb).
2.0.0-beta22Retitled “Scrollspy (Method)” and given the method keyword so the inserter ranks a search for “scrollspy” first (93e1fcf).
2.0.0-beta31An SVG icon of its own (a contents list with its current entry marked) in place of the list-view Dashicon, declared in index.js rather than block.json (cd6f63f).