Many of you have emailed or DM'ed me asking about how I implemented my table of content component, the little list of titles you'll see appear on the left gutter once you scroll a bit more down, and how I manage to highlight in that list the title of the current paragraph in view. Well, by popular demand, I finally took the time to write about this specific piece of code, and also use this as an opportunity to deep dive into the inner workings of the main trick behind it named...
✨Scrollspy✨
In this article, we'll analyze together an elegant way to implement a Scrollspy, how to abstract it with a Hook for your React project, and finally, I'll add some tips at the end on how you can integrate it with a markdown or MDX based blog to build a little table of content component similar to mine.
It's all about knowing what's intersecting the viewport
Scrollspy is a "technique" that's used to keep track of the content of the user's viewport and highlight the corresponding navigation item.
There are many ways to implement a Scrollspy, some of them are very complicated and involve a lot of maths. But you know me, I always prefer simple yet elegant solutions when it comes to tackling UI-related problems; it's just more satisfying that way ✨. In this case, that elegant solution is called the Intersection Observer API.
What is the Intersection Observer API?
In a nutshell, it's a little tool that you can use in your Javascript frontend code to detect whether a given DOM Node intersects with the document's viewport or another parent element.
How can it be used in the context of a Scrollspy?
As mentioned above, the aim of a Scrollspy is being able to keep track of what's currently "in view" for the user, thus what's intersecting with the viewport. In this blog post right now, if your window is big enough to display the table of content, you should see that the title It's all about knowing what's intersecting the viewport being highlighted since its corresponding part is currently "in view". This is because the DOM element wrapping this first part is currently "intersecting" with our viewport, and also because I built my table of content component to highlight the title corresponding to whichever section is intersecting.
Sounds pretty straightforward so far right? Well, it because that's pretty much all there is behind this kind of implementation of a Scrollspy. However, there can be more nuances such as:
- What if 2 elements intersect at the same time? Should we highlight both corresponding titles?
- How to take into account something like a fixed header?
Regarding the first question, the implementation I introduce here only considers that one section can be highlighted at a time, thus the first section to intersect will be the one highlighted.
To answer the second one, we're lucky: the Intersection Observer API allows us to pass a rootMargin
option. This option adds margins around the root element/the viewport, before computing whether a section is intersecting or not.
For example, adding a rootMargin of "-100px 0px 0px 0px"
will add a margin top for our viewport of -100px
thus making the intersection of a given element end 100px "earlier".
To help visualize these 2 nuances listed above, I built this little widget below:
- The mini browser lets you scroll a mock web page with different sections.
- Each section will be highlighted whenever it intersects with the viewport using the Intersection Observer API.
- You can modify the "offset" or
rootMargin
by adding some negativemargin-top
to see the intersection between the section and the viewport start/end earlier the more offset you add. - You can modify the height of the sections to see how the first section in view is always the one being highlighted.
Why use this rather than a scroll event and detecting if the element's scroll position fits in the viewport?
Well, there are 2 main reasons behind that:
- Performance: scroll event listeners run on the main thread whereas Intersection Observers do not. Thus using scroll events to continuously keep track of the current section in view is less performant and you'd probably end up needing to add some kind of throttling mechanism. @AggArvanitakis covers this in-depth in his blog post comparing both Intersection Observers and Scroll event performance.
- Finding if an element's scroll position fits within the viewport requires ~~a bit of~~ maths and I didn't like it 🤢. You can see by yourself with the code snippet below which is way harder to parse than what we're about to see.
Implementation of isInView, a function that returns true if an element is in view
1const isInView = (element: Element, offset: number = 0) => {2const rect = element.getBoundingClientRect();34const scrollTop =5document.documentElement.scrollTop || document.body.scrollTop;67const scrollBottom = scrollTop + window.innerHeight;89const elemTop = rect.top + scrollTop;10const elemBottom = elemTop + element.offsetHeight;1112const isVisible =13elemTop < scrollBottom - offset && elemBottom > scrollTop + offset;14return isVisible;15};
Abstracting the implementation in a React Hook
Now that we've taken a look at how we can leverage the Intersection Observer API to implement a Scrollspy, let's abstract all the implementation details in a little React Hook so it can be easily used in any current or future project.
First steps with Intersection Observers
Let's take a look at the code necessary to instantiate a new Intersection Observer in Javascript and have it observe a set of elements:
Basic usage of the Intersection Observers API
1const observer = new IntersectionObserver((entries) => {2entries.forEach((entry) => {3console.log(entry.isIntersecting); // returns true if this entry is intersecting with the viewport4console.log(entry.intersectionRatio); // returns a number between 0 and 1 representing the ratio of the element intersecting with the viewport5});6});78const targetElements = document.querySelectorAll('section');910observer.observe(targetElements);
As you can see, there're 2 main things to do to get started:
- Create the Intersection Observer and pass a callback function to it. That callback takes 2 arguments
entries
andobserver
but we only need to use the first one in our use-case.Entries
is an array of objects where each object describes the intersection of one of the elements that we're observing. - Start observing 🔍! For that, we need to create an array of elements to observe and call
observer.observe(...)
.
That's it! You now know how to use the Intersection Observer API to observe how a set of elements intersects with the viewport 🎉!
Building an efficient Hook
I'm sure there are many ways to abstract this but building an efficient Hook and avoid instantiating Intersection Observers all over the place can be pretty challenging.
First, we need to create our Intersection Observer as we did above and wrap it in a useRef
Hook. This way we can keep track of the state of any intersection across rerenders and also if we were to update our Intersection Observer, we would not trigger a rerender.
The second key step for our Hook implementation is to know when we should start observing. For that, we can use useEffect
so we can start observing as soon as the component using our Hook mounts:
First iteration of our useScrollspy Hook
1const useScrollspy = (elements: Element[]): [number] => {2const observer = React.useRef<IntersectionObserver>(3new IntersectionObserver((entries) => {4// find the index of the section that is currently intersecting5const indexOfElementIntersecting = entries.findIndex((entry) => {6// if intersection > 0 it means entry is intersecting with the view port7return entry.intersectionRatio > 0;8});910// TODO store the value of indexOfElementIntersecting11})12);1314React.useEffect(() => {15// observe all the elements passed as argument of the hook16elements.forEach((element) => observer.current.observe(element));1718// disconnect the observer once the component unmounts;19return () => observer.current.disconnect();20}, [elements]);2122// TODO return the index of the element in the elements array that is currently intersecting23return [0];24};
This works perfectly, but a few things could go wrong:
- accessing
current
directly as we do here to observe and disconnect our Intersection Observer is not safe. Thecurrent
we access on mount is not guaranteed to be the same when unmounting (remember, we can update the ref without triggering a rerender). - if we were to change the target elements our effect will run again and we'll start keeping track of the new elements which is great! But... we didn't stop keeping track of the older elements (since we didn't unmount). Thus to avoid this scenario from breaking our app, the best thing to do is to check for any existing Intersection Observers currently instantiated and disconnect them every time our effect runs:
Improved version of our useScrollspy Hook handling unwanted side effect
1const useScrollspy = (elements: Element[]): [number] => {2const observer = React.useRef<IntersectionObserver>(3new IntersectionObserver((entries) => {4// find the index of the section that is currently intersecting5const indexOfElementIntersecting = entries.findIndex((entry) => {6// if intersection > 0 it means entry is intersecting with the view port7return entry.intersectionRatio > 0;8});910// TODO store the value of indexOfElementIntersecting11})12);1314React.useEffect(() => {15const { current: ourObserver } = observer;16// disconnect any previously instanciated observers17ourObserver.disconnect();1819// observe all the elements passed as argument of the hook20elements.forEach((element) => ourObserver.observe(element));2122// disconnect the observer once the component unmounts;23return () => ourObserver.disconnect();24}, [elements]);2526// TODO return the index of the element in the elements array that is currently intersecting27return [];28};
Great, we're almost there! The last step now is to set what to return! For simplicity here, we're only going to return the index of the target currently intersecting with the viewport.
For that, we can initiate a new state to keep track of the index of the target currently intersecting, and set that state accordingly in the callback of our Intersection Observer:
Implementation of useScrollspy returning the index of the current target intersecting
1const useScrollspy = (elements: Element[]): [number] => {2const [3currentIntersectingElementIndex,4setCurrentIntersectingElementIndex,5] = React.useState(-1);67const observer = React.useRef<IntersectionObserver>(8new IntersectionObserver((entries) => {9// find the index of the section that is currently intersecting10const indexOfElementIntersecting = entries.findIndex((entry) => {11// if intersection > 0 it means entry is intersecting with the view port12return entry.intersectionRatio > 0;13});1415// store the value of indexOfElementIntersecting16setCurrentIntersectingElementIndex(indexOfElementIntersecting);17})18);1920React.useEffect(() => {21const { current: ourObserver } = observer;22// disconnect any previously instanciated observers23ourObserver.disconnect();2425// observe all the elements passed as argument of the hook26elements.forEach((element) => ourObserver.observe(element));2728// disconnect the observer once the component unmounts;29return () => ourObserver.disconnect();30}, [elements]);3132// return the index of the element in the elements array that is currently intersecting33return [currentIntersectingElementIndex];34};
A few things to note here:
- using
findIndex
will return the index of the first target intersecting. - we set this index in a local state in that hook. Even though we may be calling set state over and over in that callback it will not impact performance since most of the time we'll be setting the same value that is already in the state.
Handling offsets and custom settings
Our Hook is now almost operational! One last thing to take into account is to have the ability to pass a custom root element and a custom root margin:
- we need the first one so I can set a custom parent element that is not the main viewport, like for the playground below 😛 (it might also come in handy for you in the future)
- we need the second one to allow our ScrollSpy to handle offset such as a header as we saw in the widget in the first part of this blog post.
Here's how I abstracted them:
Implementation of useScrollspy with options
1const useScrollspy = (2elements: Element[],3options?: {4offset?: number;5root?: Element;6}7): [number] => {8const [9currentIntersectingElementIndex,10setCurrentIntersectingElementIndex,11] = React.useState(-1);1213const rootMargin = `-${(options && options.offset) || 0}px 0px 0px 0px`;1415const observer = React.useRef<IntersectionObserver>(16new IntersectionObserver(17(entries) => {18// find the index of the section that is currently intersecting19const indexOfElementIntersecting = entries.findIndex((entry) => {20// if intersection > 0 it means entry is intersecting with the view port21return entry.intersectionRatio > 0;22});2324// store the value of indexOfElementIntersecting25setCurrentIntersectingElementIndex(indexOfElementIntersecting);26},27{28root: (options && options.root) || null,29// use this option to handle custom offset30rootMargin,31}32)33);3435// ....36};
However, we now have a little problem: changing those options won't update our Intersection Observer 😱! But don't worry, working around this problem does not require too many changes:
- Instead of creating our ref with our Intersection Observer, we simply set it as
null
first - Then, after disconnecting any pre-existing Intersection Oservers, we create a new one with the current set of options and point the current value of the ref to it.
- We make sure to pass the options in the dependency array of our
useEffect
Hook so any change in options will disconnect the old observer and create a new one with the latest set of options.
Final implementation of useScrollspy
1const useScrollspy = (2elements: Element[],3options?: {4offset?: number;5root?: Element;6}7): [number, Element[], number[]] => {8const [9currentIntersectingElementIndex,10setCurrentIntersectingElementIndex,11] = React.useState(-1);1213const rootMargin = `-${(options && options.offset) || 0}px 0px 0px 0px`;1415const observer = React.useRef<IntersectionObserver>();1617React.useEffect(() => {18if (observer.current) {19observer.current.disconnect();20}2122observer.current = new IntersectionObserver(23(entries) => {24// find the index of the section that is currently intersecting25const indexOfElementIntersecting = entries.findIndex((entry) => {26// if intersection > 0 it means entry is intersecting with the view port27return entry.intersectionRatio > 0;28});2930// store the value of indexOfElementIntersecting31setCurrentIntersectingElementIndex(indexOfElementIntersecting);32},33{34root: (options && options.root) || null,35// use this option to handle custom offset36rootMargin,37}38);3940const { current: ourObserver } = observer;4142// observe all the elements passed as argument of the hook43elements.forEach((element) =>44element ? ourObserver.observe(element) : null45);4647return () => ourObserver.disconnect();48}, [elements, options, rootMargin]);4950return [currentIntersectingElementIndex];51};
It's now time to try out our new shiny Hook! Below you will find a playground containing the implementation of useScrollspy
used to highlight the title of the corresponding section in view! (just like my table of content component)
To see our Hook in action you can:
- scroll up and down the scrollable section in the playground and see the table of content component highlighting the proper title
- try to modify the offset option
- try to add or remove sections and see the Scrollspy updating accordingly.
import { styled } from '@stitches/react'; import React from 'react'; import './scene.css'; const Wrapper = styled('div', { display: 'flex', width: '300px', paddingTop: '56px', }); const Content = styled('div', { height: '500px', overflowY: 'scroll', paddingRight: '8px', '&::-webkit-scrollbar': { WebkitAppearance: 'none', width: '8px', }, '&::-webkit-scrollbar-track': { backgroundColor: 'hsla(222, 15%, 70%, 0.2)', borderRadius: '8px', }, '&::-webkit-scrollbar-thumb': { borderRadius: '8px', backgroundColor: '#C4C9D4', }, }); const TableOfContent = styled('div', { width: '100px', }); const List = styled('ul', { position: 'absolute', }); const Section = styled('section', { height: '450px', width: '175px', display: 'block !important', background: '#16181D', borderRadius: '8px', color: '#C4C9D4', marginBottom: '24px', display: 'flex', flexDirection: 'column', justifyContent: 'center', alignItems: 'center', }); const useScrollspy = (elements, options) => { const [ currentIntersectingElementIndex, setCurrentIntersectingElementIndex, ] = React.useState(-1); const rootMargin = `-${(options && options.offset) || 0}px 0px 0px 0px`; const observer = React.useRef(); React.useEffect(() => { if (observer.current) { observer.current.disconnect(); } observer.current = new IntersectionObserver( (entries) => { // find the index of the section that is currently intersecting const indexOfElementIntersecting = entries.findIndex((entry) => { return entry.intersectionRatio > 0; }); // set this index to the state setCurrentIntersectingElementIndex(indexOfElementIntersecting); }, { root: (options && options.root) || null, // use this option to handle custom offset rootMargin, } ); const { current: currentObserver } = observer; // observe all the elements passed as argument of the hook elements.forEach((element) => element ? currentObserver.observe(element) : null ); return () => currentObserver.disconnect(); }, [elements, options, rootMargin]); return [currentIntersectingElementIndex]; }; const Article = () => { const ids = ['part1', 'part2', 'part3']; const [elements, setElements] = React.useState([]); const [currentActiveIndex] = useScrollspy(elements, { root: document.querySelector('#demo-root'), offset: 20, }); /** You can ignore this, it's only here so it plays nicely with SSR :) */ React.useEffect(() => { const widgetElements = ids.map((item) => document.querySelector(`section[id="${item}"]`) ); setElements(widgetElements); }, []); return ( <Wrapper> <TableOfContent> <List> {ids.map((id, index) => ( <li key={id} style={{ color: currentActiveIndex === index ? '#5786F5' : '#C4C9D4', }} > Part {index + 1} </li> ))} </List> </TableOfContent> <Content id="demo-root"> {ids.map((id, index) => ( <Section key={id} id={id}> <p>Part {index + 1}</p> <p>Some Content</p> </Section> ))} </Content> </Wrapper> ); }; export default Article;
Markdown and MDX integration
We did it! 🎉 We now know how to implement a Scrollspy using Intersection Observer in a React Hook and how to leverage the output of the Hook to highlight the title of the current section "in-view"!
However, we only know how to do this for an arbitrary set of sections in a document. How shall we handle use-cases, like a blog post layout for instance, where we don't know the content/section we'll have to track?
I was facing this challenge myself not long ago. Each post of my blog is an individual Markdown/MDX file with raw text and maybe a bit of markup. I didn't want to hardcode the sections that my Scrollspy needed to track for each blog post:
- It would be one extra thing to think about before releasing a new article.
- I'd have to remember to update the set of sections every time I'd update a blog post.
My solution to this: sectionize my content with remark plugins
If you've built a Markdown/MDX-based blog before you've probably heard about remark. It's a little markdown processor that has a lot of plugins to automate some transformations in your markdown/MDX files.
I'm using remark here to automatically "sectionize" my Markdown/MDX posts with the help of 2 plugins:
remark-slug
: This plugin parses your markdown file to find anyh1
,h2
,h3
element you may have in your markdown, "slugifies" the text within that element, and adds it as an id.- a modified version of
remark-sectionize
: This plugin parses your markdown and will sectionize each part by wrapping both titles and the corresponding content under them in a<section/>
tag. You can find the original implementation here. My version is slightly different as not only it will sectionize but it will also add anid
tag to the section:
Modified version of remark-sectionize
1// This snippet only contains the code I modified from remark-sectionize23function sectionize(node, ancestors) {4const id = node.data.id;5// some other code from remark-sectionize67const section = {8type: 'section',9depth: depth,10children: between,11data: {12hName: 'section',13// I only added the following to append ids to the section element14hProperties: {15id: `${id}-section`,16},17},18};1920// some other code from remark-sectionize21}
I then added both plugins in my Markdown processor pipeline and magic 🪄 the output generated was exactly what was needed:
1// Markdown Input23## My awesome content45Some code, some text67// DOM output89<section id="my-awesome-content-section">10<h2 id="my-awesome-content">My awesome content</h2>11<p>Some code, some text</p>12</section>
By clicking on the checkbox below, you can highlight the <section/>
tags from this blog post, thus visualizing how I sectionize with this method my own blog posts. Try to scroll up and down the post and see how the table of content updates depending on which section is in view!
Wiring up everything
Now it was time to wire everything up. The last thing I needed was to get the ids of the sections and pass them to the Hook. There were multiple ways I could have proceeded:
- Doing it at build time: use some regex magic to get all those ids and pass them in the frontmatter of my markdown, complex but reliable.
- Doing it at render time: on mount query all
<section/>
elements in the document, get the ids and set them in a local state, easy but hacky.
For now I chose the second option:
Example of usage of useScrollspy in an Markdown/MDX based blog post layout
1const BlogPost = () => {2const [ids, setIds] = React.useState<Array<{ id: string; title: string }>>(3[]4);56React.useEffect(() => {7const titles = document.querySelectorAll('h2');8const idArrays = Array.prototype.slice9.call(titles)10.map((title) => ({ id: title.id, title: title.innerText })) as Array<{11id: string;12title: string;13}>;14setIds(idArrays);15}, [slug]);1617/**18* Get the index of the current active section that needs19* to have its corresponding title highlighted in the20* table of content21*/22const [currentActiveIndex] = useScrollspy(23ids.map(24(item) => document.querySelector(`section[id="${item.id}-section"]`)!25),26{ offset: YOUROFFSET }27);2829// Render blog post and table of content30};
But Maxime, I want to build the same table of content as you did
But Maxime, I want to build the same table of content as you did
What about the progress bar next to your table of content? I want the same as you!
What about the progress bar next to your table of content? I want the same as you!
I hope this blog post brought some light on what a Scrollspy is, Intersection Observers, and also how I implemented my table of content components that so many of you seem to like so much (thank you all for the overall compliments on my blog by the way, I really appreciate them 😄).
If you have any questions, suggestions, or if something in my codebase isn't clear enough, do not hesitate to reach out! I'm always looking for ways to improve the way I write React components and set a good example for other frontend developers.
Liked this article? Share it with a friend on Twitter or support me to take on more ambitious projects to write about. Have a question, feedback or simply wish to contact me privately? Shoot me a DM and I'll do my best to get back to you.
Have a wonderful day.
– Maxime
A deep dive into how the inner workings of a Scrollspy, Intersection Observers, and how to integrate it with Markdown-based static sites without the need of third party libraries.