Scroll chapters

1. Copy to Webflow

   Add Geist and Geist Mono to your site's fonts (Site settings, Fonts, Google Fonts) before pasting: Webflow removes any font your site has not installed.
   Copy to Webflow

2. Add custom CSS

   To keep things simple, the code ships inside the Webflow embed. You can also copy it here and add it yourself to the page or site custom code. How to choose

   The look of the preview is the scroll-chapters-* classes of the paste: the size of the number, the type of the list, the two columns. The Embed holds what moves, and reads these variables: --scroll-chapters-accent (the small square beside the line being read, and the number of the strip), --scroll-chapters-quiet (the strength of the ink of what is not being read, 42%), --scroll-chapters-pin, --scroll-chapters-shift, --scroll-chapters-top, and for the strip of a narrow window --scroll-chapters-strip, --scroll-chapters-strip-ink, --scroll-chapters-bar and --scroll-chapters-gutter. Set them on the block, or on anything above it, in a rule of your own. No parent of the table may cut its overflow with overflow: hidden, or it stops being held beside the text.

3. Add custom JS

   To keep things simple, the code ships inside the Webflow embed. You can also copy it here and add it yourself to the page or site custom code. How to choose

4. Use it on your own elements

   Custom attributes
   Select the element on the canvas and open the Settings panel. Under Custom attributes, add a pair: the name on the left, the value on the right.

   Custom attribute	What it does
   data-scroll-chapters	Marks the block that holds the text and its table of contents. It takes no value: leave the value field empty. Every title in it that matches the setting headings, every h2 by default, opens a chapter. The settings below go on the same element.
   data-scroll-chapters-nav	On the table of contents, inside the block. It takes no value. It is the part held beside the text on a wide window, and the sheet at the foot of a narrow one. Name it for screen readers with aria-label, "Chapters" in the paste. Without it the block is left alone and the engine says so in the console. [ Required ]
   data-scroll-chapters-list	On the box that holds the lines of the list and nothing else, inside the table. It takes no value. The engine writes one line in it for each title it finds; the lines written by hand are what shows on the canvas and without JavaScript. [ Required ]
   data-scroll-chapters-item	On the lines of the list: a link, or a block that holds one. It takes no value. The first one is the model of every line the engine writes: style that one line and every line follows. The other lines written by hand may carry the mark too, as they do in the preview; the engine replaces them all. Without it the engine writes plain links. [ Optional ]
   data-scroll-chapters-item-number	In the model line, on the element that receives the number of the chapter, 01. It takes no value. [ Optional ]
   data-scroll-chapters-item-title	In the model line, on the element that receives the title of the chapter. It takes no value. Without it the title goes in the link itself. [ Optional ]
   data-scroll-chapters-number	On an element that receives the number of the chapter being read, on wheels that turn with the scroll. It takes no value. Its class gives the size of the figures. [ Optional ]
   data-scroll-chapters-total	On an element that receives how many chapters there are, 06. It takes no value. [ Optional ]
   data-scroll-chapters-left	On an element that receives the minutes of reading left, a figure alone: the words around it, min left, are yours. It takes no value. [ Optional ]
   data-scroll-chapters-title="Short name"	On a title of the page: the wording the list uses for it, when the title itself is too long for the list. [ Optional ]
   data-scroll-chapters-skip	On a title of the page that must not open a chapter. It takes no value. [ Optional ]
   data-scroll-chapters-state	Written by the engine on a line of the list: current on the chapter being read, read on the ones before it. The block carries data-scroll-chapters-mode (side or strip) and data-scroll-chapters-ready, the table data-scroll-chapters-in while the block is on screen and data-scroll-chapters-open while its sheet is up. Never written by hand; the stylesheet reads them, and so can a rule of yours. [ Optional ]

   Settings
   Every setting is a custom attribute too, added the same way and on the same element. An attribute always wins over the defaults written in the code.

   Attribute	Default	What it is
   data-scroll-chapters-headings	h2	The titles that open a chapter, as a CSS selector read inside the block. Options: h2, the default; h2, h3 to list two levels; .chapter-title or [data-chapter] for titles of your own.
   data-scroll-chapters-line	0.4	The height in the window where a chapter becomes the one being read, as a share of the window: 0 its top, 1 its foot.
   data-scroll-chapters-offset	clamp(72px, 14vh, 140px)	Where the title of a chosen chapter lands, measured from the top of the window, in any CSS length.
   data-scroll-chapters-roll	0.3	The stretch of scroll over which the number turns before the next title, as a share of the window height.
   data-scroll-chapters-speed	230	The reading speed the minutes left are worked out from, in words a minute.
   data-scroll-chapters-duration	1.1	The time of the travel to a chosen chapter, in seconds: the page, the square of the list and the number move together over it.
   data-scroll-chapters-strip	900	The width of the window, in px, under which the table of contents leaves the side of the text and docks as a strip at the foot of the window.
   data-scroll-chapters-hash	on	Whether the chosen chapter is written in the address of the page. Options: on, a line chosen by the visitor writes the id of its title after the #, without adding a step to the history; off, the address is left alone.

Two files and their pictures (8), no build step. It runs in the browser only. Load it with a script tag in plain HTML, in a client-side script in Astro, never in the frontmatter. In React, call ScrollChapters.mount(ref.current) in useEffect and destroy() in its cleanup.

1. Tune it, either way

   Per element with an attribute, or once for the whole site by editing DEFAULTS at the top of the file.

   Attribute	Default	What it is	Lower	Higher
   data-scroll-chapters-headings	h2	The titles that open a chapter, as a CSS selector read inside the block. Options: h2, the default; h2, h3 to list two levels; .chapter-title or [data-chapter] for titles of your own.
   data-scroll-chapters-line	0.4	The height in the window where a chapter becomes the one being read, as a share of the window: 0 its top, 1 its foot.	The next chapter takes over later, once its title is near the top of the window	The next chapter takes over sooner, while its title is still low in the window; over 0.6 the list runs ahead of the reading
   data-scroll-chapters-offset	clamp(72px, 14vh, 140px)	Where the title of a chosen chapter lands, measured from the top of the window, in any CSS length.	The title lands closer to the top. Give it at least the height of a bar held at the top of the page	More of the end of the chapter before stays in sight above the title
   data-scroll-chapters-roll	0.3	The stretch of scroll over which the number turns before the next title, as a share of the window height.	The number turns late and fast, like a click; 0 makes it roll once the title has arrived	The number starts to turn long before the title arrives; over 0.6 it is rarely still
   data-scroll-chapters-speed	230	The reading speed the minutes left are worked out from, in words a minute.	More minutes for the same page: a slow reader, or a dense text	Fewer minutes: 230 is an adult reading prose, 300 someone skimming
   data-scroll-chapters-duration	1.1	The time of the travel to a chosen chapter, in seconds: the page, the square of the list and the number move together over it.	Quicker; under 0.6 the number has no time to be seen turning; 0 jumps	Slower and more shown; over 1.6 the page feels late on the click
   data-scroll-chapters-strip	900	The width of the window, in px, under which the table of contents leaves the side of the text and docks as a strip at the foot of the window.	The table stays beside the text on narrower windows: set it where your two columns stop fitting	The strip is used on wider windows; a very large value uses it everywhere
   data-scroll-chapters-hash	on	Whether the chosen chapter is written in the address of the page. Options: on, a line chosen by the visitor writes the id of its title after the #, without adding a step to the history; off, the address is left alone.

2. Drive it from JavaScript

   When a script follows the chapter being read, an analytics call or a picture that changes with the chapter, or sends the page to a chapter.
   JavaScript Expand Copy

   const element = document.querySelector('[data-scroll-chapters]');
   element.addEventListener('scrollchapters:change', (e) => {
     console.log(e.detail);
   });
   
   // Follow the chapter being read.
   element.addEventListener('scrollchapters:change', (event) => {
     console.log(event.detail.index, event.detail.title);
   });
   
   const toc = ScrollChapters.mount(element);   // the block auto() mounted, or a new one
   toc.go('glass');                              // by the id of a title, or by a number counted from 0
   toc.progress();                               // { index, chapter, page, minutes }
   
   // When the page leaves:
   ScrollChapters.destroy(element);   // removes what the engine added, gives the markup back as it was

   Show all 16 lines

3. Fit it to your page

   The chapters

   • A chapter is a title and what follows it, up to the next title. No wrapper is needed around a chapter, and none is in the way: the engine reads the titles, wherever they are in the block.
   • To add a chapter, write a title. The list, the total and the minutes follow, also when the title arrives later from a script or a CMS.
   • **Give each title an id** in the page's own words (pricing, not section-2): it is what the address shows and what a link elsewhere points at. A title without one gets an id made from its words.
   • Three chapters or fifteen. A list taller than the window scrolls on its own, with no bar, and keeps the line being read in sight.
   • A long title wraps in the list and takes its ink line after line. To shorten it in the list only, add data-scroll-chapters-title to the title.
   • What comes before the first title belongs to no chapter: the number shows 01 and the first line waits, quiet. Its words count in the minutes left.

   The table of contents

   It is plain markup, and everything in it is optional but the list: a large number, a total, the minutes left, in any order and any layout. The lines written in the list are what a page without JavaScript shows, and what the Designer canvas shows; the engine replaces them with one line for each title it finds, built on the first one.

   On a narrow window

   Under the width given by strip the table leaves the flow and becomes a sheet in --scroll-chapters-strip under the foot of the window. Only its bar shows: the number, in the accent, the title being read with its ink, and how many chapters there are. The number and the title roll together to the next chapter. Pressing the bar raises the sheet, with everything the table holds; a line, the cross, Escape or a touch outside lowers it. The strip is away while the block is not on screen, so it never sits over a footer or a hero.

   The keyboard

   Tab goes through the lines of the list; Enter travels to the chapter and moves the focus to its title, so the next Tab carries on from there. On a narrow window Tab reaches the bar, Enter or Space raises the sheet, Tab goes on into the list, and Escape lowers the sheet and gives the focus back to the bar. The line being read carries aria-current="location".

   The colours and the sizes

   Custom properties, set at zero specificity on the block. Give them your own values on the block or on anything above it:

   • --scroll-chapters-accent: the small square beside the line being read, and the number of the strip.
   • --scroll-chapters-quiet: the strength of the ink of what is not being read, as a percentage, 42% in the preview. The colour itself is the colour of the list.
   • --scroll-chapters-pin: the side of the square, 5px.
   • --scroll-chapters-shift: how far the square hangs to the left of the list, in the margin.
   • --scroll-chapters-top: the distance kept between the top of the window and the table held beside the text.
   • --scroll-chapters-strip and --scroll-chapters-strip-ink: the ground and the text of the strip and of its sheet.
   • --scroll-chapters-bar: the height of the bar of the strip.
   • --scroll-chapters-gutter: the padding of the sheet on its sides.

   The type, the size of the number and the spacing of the list are the classes of the table itself.

   From JavaScript

   • ScrollChapters.mount(element, overrides) returns the instance of a block, mounting it if it was not: { element, settings, chapters(), index(), progress(), go(which, options), next(), prev(), open(), close(), refresh(), destroy() }. go takes a number counted from 0, the id of a title or the title element, and { instant: true } to jump. ScrollChapters.auto(root) mounts every marked block inside root, and runs once on its own; ScrollChapters.destroy(element) gives the markup back.
   • progress() returns { index, chapter, page, minutes }: the chapter being read, how far through it and through the whole from 0 to 1, and the minutes left.
   • Events, all bubbling from the block: scrollchapters:ready; scrollchapters:change when another chapter becomes the one being read, with { index, previous, heading, title } in detail; scrollchapters:open and scrollchapters:close for the sheet.
   • The state is in the markup: data-scroll-chapters-state on a line, current or read; aria-current="location" on the link being read; data-scroll-chapters-mode on the block, side or strip; data-scroll-chapters-in and data-scroll-chapters-open on the table; data-scroll-chapters-ready on the block.
   • **Under prefers-reduced-motion: reduce** the number changes at once, a chosen chapter is reached with no travel, and the sheet appears without rising. The ink still follows the scroll, since the reader moves it.
   • Without JavaScript the table is the list of links written in the page, in the flow, above or beside the text.
   • The essay of the demo was written for it and its photographs come from Unsplash: on a real page every title and every word is the user's own.

4. Avoid the pitfalls

   • The table of contents is inside the marked block, next to the text. The engine does not look for it elsewhere on the page.
   • **strip is your own breakpoint.** It is a width of the window, and the layout of the two columns is yours: set it to the width where the table and the text stop fitting side by side, 900 in the preview.
   • No parent of the table may cut its overflow with overflow: hidden or auto: the table stops being held beside the text. Use overflow-x: clip where a parent has to cut. And nothing above it may carry a transform or a filter, or the strip is no longer held to the window.
   • The table is held inside the marked block, for as long as that block scrolls by: the block has to be as tall as the text, which it is when it holds the text. The stylesheet hangs the table from the top of the block itself (align-self: flex-start); do not stretch it to the height of the block, or it has nowhere to be held.
   • The page must scroll in the window, not in a wrapper with overflow: auto.
   • A page that ends with its last chapter cannot bring the last titles up to the reading line: on the last screen of the page the line slides down to the foot of the window, so every chapter is reached, the last ones quickly. A chosen chapter that cannot be brought to offset stops where the page ends.
   • A bar held at the top of the page covers a title that lands under it: give offset at least its height.
   • The ink is a gradient clipped to the letters, in the colour of the line at two strengths. A color set on the line reaches it; a -webkit-text-fill-color or a background of your own on the title does not go with it. A browser without color-mix() shows every title at full strength, and the square alone says which one is being read.
   • A chapter chosen in the list stays the one shown until the reader moves the page, also when the page could not bring its title up to offset because it ends first.
   • In Webflow, do not use a Rich Text element's own table of contents or an interaction on the same list: the engine rewrites the lines of the list. The titles may live in a Rich Text element: set headings to h2 as usual.
   • **id used twice on a page** breaks the address and the travel: the link goes to the first element that carries it.
   • In React or any framework that owns the DOM, mount in an effect and call destroy() in its cleanup; the engine rewrites the children of the list, adds the bar of the strip to the table, and writes attributes.

One click on Copy the AI prompt copies everything an assistant needs to build this effect: the complete code, the markup, the dependency, every setting and every pitfall.