Scrollspy
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.
- Block name:
method/scrollspy - Title: Scrollspy (Method)
- Category:
method-component-blocks - Supports:
className;htmlandanchorare off, andmultiple: false— one Scrollspy per post - Render type: Dynamic (PHP
render_callback:scrollspy_render()) — PHP prints an empty<nav>with data attributes; the view script builds the list - Inner blocks: No
- Scripts:
editorScript(index.js, a static preview) andviewScript(frontend.js) - Source: lib/blocks/method-scrollspy/method-scrollspy.php, lib/blocks/method-scrollspy/src/editor.js, lib/blocks/method-scrollspy/src/frontend.js
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:
<!-- 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
| Attribute | Type | Default | Description |
|---|---|---|---|
targetSelector | string | ".docs-content" | CSS selector of the container whose headings are listed. Printed as data-target. |
label | string | "On this page" | The heading above the list, and the nav’s aria-label. |
headingLevels | array | ["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. |
stickyOffset | number | 0 | Pixels 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. |
stickyAt | string | "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. |
textColor | string | — | Color of the label. |
linkColor | string | — | Color of the links. |
linkHoverColor | string | — | Hover and :focus-visible color of the links. |
linkActiveColor | string | — | 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
| Component | Panel | Breakpoints | Notes |
|---|---|---|---|
| Block panel: Scrollspy Settings | Scrollspy Settings | base | Target 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. |
MethodBreakpointSelect | Scrollspy Settings | base | Writes a theme breakpoint key to stickyAt; the options come from the theme’s configured breakpoints. |
MethodColorControls | Color Settings | base | include={['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 thebreakpoints.dimensionsmap fromMETHOD_CHILD_OPTIONS(orMETHOD_OPTIONS) and returns each key with its pixel hint; the render callback looksstickyAtup in it. On the page the view script togglesis-stickyon the nav frommatchMedia( '(min-width: …)' ), and the stylesheet gatesposition: stickyon that class. - Active state: an
IntersectionObserverover the listed headings with arootMarginof-{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: hiddenon an ancestor creates a scroll container that breaksposition: sticky, so assets/scss/global.scss setsoverflow: clip !importanton.wp-site-blocks:has(.method-scrollspy)and.method-container-content:has(.method-scrollspy). The nav isalign-self: startwith amax-heightof 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-transitionon.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()andmethod_collect_css(), as in every Method block.
Frontend Rendering
What PHP prints:
<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:
<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
| Version | Description |
|---|---|
| 2.0.0-beta5 | Introduced (ccc789b). |
| 2.0.0-beta17 | Inserter title prefixed, “Method Scrollspy”, like every top-level Method block (c34e9bb). |
| 2.0.0-beta22 | Retitled “Scrollspy (Method)” and given the method keyword so the inserter ranks a search for “scrollspy” first (93e1fcf). |
| 2.0.0-beta31 | An 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). |