Scrollspy demystified

Mar 9 2021

/ 10 min read /

0 Likes β€’

0 Replies β€’

0 Reposts

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.

My deepest apologies to anyone who tried to read the implementation of my TableOfContent component that's currently being used here, it's far from my best work πŸ˜…. I hope this blog post will make up for the time lost trying to decipher my code.

I also took some time to refactor it and have it not rely on any 3rd party package and will link/feature some of the code at the end of this article.

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.

πŸ‘‰ I'll introduce some of the basic concepts and how to use the Intersection Observer API in this blog post. However, if you'd like to read more details about it I encourage you to take a look at the corresponding MDN documentation.

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:

  1. What if 2 elements intersect at the same time? Should we highlight both corresponding titles?
  2. 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 negative margin-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:

  1. 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.
  2. 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

1
const isInView = (element: Element, offset: number = 0) => {
2
const rect = element.getBoundingClientRect();
3
4
const scrollTop =
5
document.documentElement.scrollTop || document.body.scrollTop;
6
7
const scrollBottom = scrollTop + window.innerHeight;
8
9
const elemTop = rect.top + scrollTop;
10
const elemBottom = elemTop + element.offsetHeight;
11
12
const isVisible =
13
elemTop < scrollBottom - offset && elemBottom > scrollTop + offset;
14
return 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.

The implementation I'm going to introduce here is very opinionated towards making this work solely for the use-case of a Scrollspy. It can be abstracted/implemented in many different ways that are more or less opinionated but for this article, I'm keeping this close to our main topic on purpose.

Of course, do reach out if you have a better implementation πŸ˜„ I'm always looking for new patterns or ways to build stuff!

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

1
const observer = new IntersectionObserver((entries) => {
2
entries.forEach((entry) => {
3
console.log(entry.isIntersecting); // returns true if this entry is intersecting with the viewport
4
console.log(entry.intersectionRatio); // returns a number between 0 and 1 representing the ratio of the element intersecting with the viewport
5
});
6
});
7
8
const targetElements = document.querySelectorAll('section');
9
10
observer.observe(targetElements);

As you can see, there're 2 main things to do to get started:

  1. Create the Intersection Observer and pass a callback function to it. That callback takes 2 arguments entries and observer 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.
  2. Start observing πŸ”! For that, we need to create an array of elements to observe and call observer.observe(...).

Once you're done "observing" one of the target elements or the whole set you can either call:

  • observer.unobserve(...) to stop observing a specific element
  • observer.disconnect() to stop the Intersection Observer completely.

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

1
const useScrollspy = (elements: Element[]): [number] => {
2
const observer = React.useRef<IntersectionObserver>(
3
new IntersectionObserver((entries) => {
4
// find the index of the section that is currently intersecting
5
const indexOfElementIntersecting = entries.findIndex((entry) => {
6
// if intersection > 0 it means entry is intersecting with the view port
7
return entry.intersectionRatio > 0;
8
});
9
10
// TODO store the value of indexOfElementIntersecting
11
})
12
);
13
14
React.useEffect(() => {
15
// observe all the elements passed as argument of the hook
16
elements.forEach((element) => observer.current.observe(element));
17
18
// disconnect the observer once the component unmounts;
19
return () => observer.current.disconnect();
20
}, [elements]);
21
22
// TODO return the index of the element in the elements array that is currently intersecting
23
return [0];
24
};

This works perfectly, but a few things could go wrong:

  1. accessing current directly as we do here to observe and disconnect our Intersection Observer is not safe. The current we access on mount is not guaranteed to be the same when unmounting (remember, we can update the ref without triggering a rerender).
  2. 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

1
const useScrollspy = (elements: Element[]): [number] => {
2
const observer = React.useRef<IntersectionObserver>(
3
new IntersectionObserver((entries) => {
4
// find the index of the section that is currently intersecting
5
const indexOfElementIntersecting = entries.findIndex((entry) => {
6
// if intersection > 0 it means entry is intersecting with the view port
7
return entry.intersectionRatio > 0;
8
});
9
10
// TODO store the value of indexOfElementIntersecting
11
})
12
);
13
14
React.useEffect(() => {
15
const { current: ourObserver } = observer;
16
// disconnect any previously instanciated observers
17
ourObserver.disconnect();
18
19
// observe all the elements passed as argument of the hook
20
elements.forEach((element) => ourObserver.observe(element));
21
22
// disconnect the observer once the component unmounts;
23
return () => ourObserver.disconnect();
24
}, [elements]);
25
26
// TODO return the index of the element in the elements array that is currently intersecting
27
return [];
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

1
const useScrollspy = (elements: Element[]): [number] => {
2
const [
3
currentIntersectingElementIndex,
4
setCurrentIntersectingElementIndex,
5
] = React.useState(-1);
6
7
const observer = React.useRef<IntersectionObserver>(
8
new IntersectionObserver((entries) => {
9
// find the index of the section that is currently intersecting
10
const indexOfElementIntersecting = entries.findIndex((entry) => {
11
// if intersection > 0 it means entry is intersecting with the view port
12
return entry.intersectionRatio > 0;
13
});
14
15
// store the value of indexOfElementIntersecting
16
setCurrentIntersectingElementIndex(indexOfElementIntersecting);
17
})
18
);
19
20
React.useEffect(() => {
21
const { current: ourObserver } = observer;
22
// disconnect any previously instanciated observers
23
ourObserver.disconnect();
24
25
// observe all the elements passed as argument of the hook
26
elements.forEach((element) => ourObserver.observe(element));
27
28
// disconnect the observer once the component unmounts;
29
return () => ourObserver.disconnect();
30
}, [elements]);
31
32
// return the index of the element in the elements array that is currently intersecting
33
return [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

1
const useScrollspy = (
2
elements: Element[],
3
options?: {
4
offset?: number;
5
root?: Element;
6
}
7
): [number] => {
8
const [
9
currentIntersectingElementIndex,
10
setCurrentIntersectingElementIndex,
11
] = React.useState(-1);
12
13
const rootMargin = `-${(options && options.offset) || 0}px 0px 0px 0px`;
14
15
const observer = React.useRef<IntersectionObserver>(
16
new IntersectionObserver(
17
(entries) => {
18
// find the index of the section that is currently intersecting
19
const indexOfElementIntersecting = entries.findIndex((entry) => {
20
// if intersection > 0 it means entry is intersecting with the view port
21
return entry.intersectionRatio > 0;
22
});
23
24
// store the value of indexOfElementIntersecting
25
setCurrentIntersectingElementIndex(indexOfElementIntersecting);
26
},
27
{
28
root: (options && options.root) || null,
29
// use this option to handle custom offset
30
rootMargin,
31
}
32
)
33
);
34
35
// ....
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

1
const useScrollspy = (
2
elements: Element[],
3
options?: {
4
offset?: number;
5
root?: Element;
6
}
7
): [number, Element[], number[]] => {
8
const [
9
currentIntersectingElementIndex,
10
setCurrentIntersectingElementIndex,
11
] = React.useState(-1);
12
13
const rootMargin = `-${(options && options.offset) || 0}px 0px 0px 0px`;
14
15
const observer = React.useRef<IntersectionObserver>();
16
17
React.useEffect(() => {
18
if (observer.current) {
19
observer.current.disconnect();
20
}
21
22
observer.current = new IntersectionObserver(
23
(entries) => {
24
// find the index of the section that is currently intersecting
25
const indexOfElementIntersecting = entries.findIndex((entry) => {
26
// if intersection > 0 it means entry is intersecting with the view port
27
return entry.intersectionRatio > 0;
28
});
29
30
// store the value of indexOfElementIntersecting
31
setCurrentIntersectingElementIndex(indexOfElementIntersecting);
32
},
33
{
34
root: (options && options.root) || null,
35
// use this option to handle custom offset
36
rootMargin,
37
}
38
);
39
40
const { current: ourObserver } = observer;
41
42
// observe all the elements passed as argument of the hook
43
elements.forEach((element) =>
44
element ? ourObserver.observe(element) : null
45
);
46
47
return () => ourObserver.disconnect();
48
}, [elements, options, rootMargin]);
49
50
return [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.

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?

πŸ‘‰ This part is optional! If you want to know how I worked around this issue in the specific use-case of a Markdown/MDX-based blog.

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 any h1, 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 an id tag to the section:

Modified version of remark-sectionize

1
// This snippet only contains the code I modified from remark-sectionize
2
3
function sectionize(node, ancestors) {
4
const id = node.data.id;
5
// some other code from remark-sectionize
6
7
const section = {
8
type: 'section',
9
depth: depth,
10
children: between,
11
data: {
12
hName: 'section',
13
// I only added the following to append ids to the section element
14
hProperties: {
15
id: `${id}-section`,
16
},
17
},
18
};
19
20
// some other code from remark-sectionize
21
}

I then added both plugins in my Markdown processor pipeline and magic πŸͺ„ the output generated was exactly what was needed:

1
// Markdown Input
2
3
## My awesome content
4
5
Some code, some text
6
7
// DOM output
8
9
<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!

Here's a great detailed tutorial about custom remark plugins with Gatsby

In my case, I implemented this in NextJS you can check out the related code here πŸ‘‰ MDX tools for blog.maximeheckel.com Next

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

1
const BlogPost = () => {
2
const [ids, setIds] = React.useState<Array<{ id: string; title: string }>>(
3
[]
4
);
5
6
React.useEffect(() => {
7
const titles = document.querySelectorAll('h2');
8
const idArrays = Array.prototype.slice
9
.call(titles)
10
.map((title) => ({ id: title.id, title: title.innerText })) as Array<{
11
id: string;
12
title: string;
13
}>;
14
setIds(idArrays);
15
}, [slug]);
16
17
/**
18
* Get the index of the current active section that needs
19
* to have its corresponding title highlighted in the
20
* table of content
21
*/
22
const [currentActiveIndex] = useScrollspy(
23
ids.map(
24
(item) => document.querySelector(`section[id="${item.id}-section"]`)!
25
),
26
{ offset: YOUROFFSET }
27
);
28
29
// Render blog post and table of content
30
};
But Maxime, I want to build the same table of content as you did

Today is your lucky day! I refactored the whole implementation so it's easier and more accessible: TableOfContent.tsx

Note: This code is for my upcoming NextJS based blog. It's not deployed/available to the public just yet. I still have 1 or 2 hacks in there to workaround weird race conditions due to server-side rendering/next router, I'll fix those in the future.


What about the progress bar next to your table of content? I want the same as you!

Same! I refactored it as well and isolated it so it's easier to read: ProgressBar.tsx Keep an eye on it, I still have some cleanup to do.

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.

Fetching Replies...

Do you have any questions, comments or simply wish to contact me privately? Don’t hesitate to shoot me a DM on Twitter.


Have a wonderful day.
Maxime


Β© 2021 Maxime Heckel β€”β€” SF/NY