How to build a table of contents in React

Emma Goto 🍙 - Apr 2 '21 - - Dev Community

A table of contents lets your readers see a high-level summary of your page. In this tutorial, we’ll be building a table of contents with React. This component will dynamically render a list of page headings and highlight which heading you are currently viewing.

Here's our final product:

If you are viewing this post on my website, you will be able to see it in action there as well.

Looking for a full code example? Check out the tutorial’s Codepen.

Get started with a new component file

To begin, let’s create a new TableOfContents file.

// src/components/tableOfContents.js
const TableOfContents = () => {
    return (
        <nav aria-label="Table of contents">
            Hello world!
        </nav>
    );
};

export default TableOfContents;
Enter fullscreen mode Exit fullscreen mode

💡 The nav HTML element indicates parts of the page that provide navigation links, like a table of contents. The aria-label identifies this nav element to screen reader users.

Plop this component into where you want it to render. If you have a main App.js file, you could render it there alongside your main content:

// src/App.js
import TableOfContents from '../components/tableOfContents';

const App = () => (
    <Layout>
        <MainContent />
        <TableOfContents />
    </Layout>
);

export default App;
Enter fullscreen mode Exit fullscreen mode

Add some CSS to make it sticky

There’s a couple of features that we want to add to our table of contents:

  • Keeping it sticky as the user scrolls down the page
  • Showing a scrollbar if it’s longer than the height of the page 
nav {
  position: sticky;
  position: -webkit-sticky; /* For Safari */
  top: 24px; /* How far down the page you want your ToC to live */

  /* Give table of contents a scrollbar */
  max-height: calc(100vh - 40px);
  overflow: auto;
}
Enter fullscreen mode Exit fullscreen mode

Now, you’ll have a sticky component that will follow you up and down the page as you scroll.

Make sure all your headings have IDs

For your headings to be link-able, they will need to have a unique id value:

<h2 id="initial-header">Initial header</h2>
Enter fullscreen mode Exit fullscreen mode

Create a hook to find all headings on the page

For this table of contents component, I'll be rendering all the <h2> and <h3> elements on the page.

We'll create a useHeadingsData hook, which will be responsible for getting our headings. We'll do this using querySelectorAll:

const useHeadingsData = () => {
  const [nestedHeadings, setNestedHeadings] = useState([]);

  useEffect(() => {
    const headingElements = Array.from(
      document.querySelectorAll("h2, h3")
    );

    const newNestedHeadings = getNestedHeadings(headingElements);
    setNestedHeadings(newNestedHeadings);
  }, []);

  return { nestedHeadings };
};
Enter fullscreen mode Exit fullscreen mode

You'll notice there's a getNestedHeadings function. Since the query selector returns a list of h2 and h3 elements, we have to determine the nesting ourselves.

If our headings looked something like this:

<h2>Initial header</h2>
<h2>Second header</h2>
<h3>Third header</h3>
Enter fullscreen mode Exit fullscreen mode

We would want to nest the "Third header" underneath its parent:

Initial header
Second header
    Third header
Enter fullscreen mode Exit fullscreen mode

To achieve this, we're going to store all h2 objects in a list. Each h2 will have a items array, where any children h3s will go:

[
    {
        id: "initial-header",
        title: "Initial header",
        items: []
    },
    {
        id: "second-header",
        title: "Second header",
        items: [{
            id: "third-header",
            title: "Third header",
        }]
    },
]
Enter fullscreen mode Exit fullscreen mode

In getNestedHeadings, we'll loop through the heading elements and add all h2s to the list. Any h3s will live inside the last known h2.

const getNestedHeadings = (headingElements) => {
  const nestedHeadings = [];

  headingElements.forEach((heading, index) => {
    const { innerText: title, id } = heading;

    if (heading.nodeName === "H2") {
      nestedHeadings.push({ id, title, items: [] });
    } else if (heading.nodeName === "H3" && nestedHeadings.length > 0) {
      nestedHeadings[nestedHeadings.length - 1].items.push({
        id,
        title,
      });
    }
  });

  return nestedHeadings;
};
Enter fullscreen mode Exit fullscreen mode

Render your headings as a list of links

Now that we have our nestedHeadings value, we can use it to render our table of contents!

Let's keep things simple and start by rendering all the h2 elements. We'll create a new Headings component to take care of that.

const Headings = ({ headings }) => (
  <ul>
    {headings.map((heading) => (
      <li key={heading.id}>
        <a href={`#${heading.id}`}>{heading.title}</a>
      </li>
    ))}
  </ul>
);

const TableOfContents = () => {
  const { nestedHeadings } = useHeadingsData();

  return (
    <nav aria-label="Table of contents">
      <Headings headings={nestedHeadings} />
    </nav>
  );
};
Enter fullscreen mode Exit fullscreen mode

Add your nested headings

We’ll then want to render our nested h3s. We’ll do this by creating a new sub-list underneath each h2:

const Headings = ({ headings }) => (
  <ul>
    {headings.map((heading) => (
      <li key={heading.id}>
        <a href={`#${heading.id}`}>{heading.title}</a>
        {heading.items.length > 0 && (
          <ul>
            {heading.items.map((child) => (
              <li key={child.id}>
                <a href={`#${child.id}`}>{child.title}</a>
              </li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
);
Enter fullscreen mode Exit fullscreen mode

Make your browser smoothly scroll to headings

Right now if we click on a header link, it will immediately jump to the header.

With scrollIntoView, we can instead ensure that it smoothly scrolls into view.

const Headings = ({ headings }) => (
  <ul>
    {headings.map((heading) => (
      <li key={heading.id}>
        <a
          href={`#${heading.id}`}
          onClick={(e) => {
            e.preventDefault();
            document.querySelector(`#${heading.id}`).scrollIntoView({
              behavior: "smooth"
            });
          }}
        >
          {heading.title}
        </a>
        {heading.items.length > 0 && (
          <ul>
            {heading.items.map((child) => (
              <li key={child.id}>
                <a
                  href={`#${child.id}`}
                  onClick={(e) => {
                    e.preventDefault();
                    document.querySelector(`#${child.id}`).scrollIntoView({
                      behavior: "smooth"
                    });
                  }}
                >
                  {child.title}
                </a>
              </li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
);
Enter fullscreen mode Exit fullscreen mode

(Unfortunately this is not supported on Safari!)

Add an offset when you jump to a heading

You might also notice that the heading is very close to the top of the page. We can create a bit of space between the heading and the top of the page when it is jumped to:

h2, h3 {
    scroll-margin-top: 16px;
}
Enter fullscreen mode Exit fullscreen mode

However scroll-margin-top doesn't work on Safari. Alternatively, you can do this:

h2, h3 {
    padding-top: 16px;
    margin-top: -16px;
}
Enter fullscreen mode Exit fullscreen mode

Depending on the size of your offset, anything directly above the header won't be clickable (e.g. links). This won't be a problem if the offset is very small, but can cause problems if you have larger offsets (which you will need if you have a sticky header).

In this case, the "best of both worlds" approach would be to use scroll-margin-top where we can, and fall back to the alternate approach for Safari users.

h2, h3 {
    scroll-margin-top: 16px;
}

/* Safari-only */
@supports (-webkit-hyphens:none) {
    h2, h3 {
        padding-top: 16px;
        margin-top: -16px;
    }
}
Enter fullscreen mode Exit fullscreen mode

Find the currently “active” heading

The final step is to highlight the currently visible heading on the page in the table of contents. This acts as a progress bar of sorts, letting the user know where they are on the page. We’ll determine this with the Intersection Observer API. This API lets you know when elements become visible on the page.

Instantiate your Intersection Observer

Let's create an Intersection Observer. It takes in a callback function as its first argument, which we'll keep empty for now.

You can also pass in a rootMargin value. This determines the zone for when an element is "visible". For instance on my site I have -110px on top and -40% on the bottom:

const useIntersectionObserver = () => {
  useEffect(() => {
    const callback = () => {};

    const observer = new IntersectionObserver(callback, {
      rootMargin: '-110px 0px -40% 0px',
    });
  }, []);
};
Enter fullscreen mode Exit fullscreen mode

The -110px is the height of my sticky nav at the top, so I don't want any content hidden under there to count as "visible".

The -40% means that if a header is in the bottom 40% of the page, this doesn’t count as being "visible". If a heading is visible near the bottom of the page, you're probably not actually reading it yet.

Observe your headings to listen for when they scroll in and out of view

After creating the observer, you need to call observe() on each of the elements we want to observe. In our case, this is all the h2 and h3 elements on the page.

You'll also want to call disconnect() when you unmount.

const useIntersectionObserver = () => {
  useEffect(() => {
    const callback = () => {};

    const observer = new IntersectionObserver(callback, {
      rootMargin: "-110px 0px -40% 0px"
    });

    const headingElements = Array.from(document.querySelectorAll("h2, h3"));
    headingElements.forEach((element) => observer.observe(element));

    return () => observer.disconnect();
  }, []);
};
Enter fullscreen mode Exit fullscreen mode

Store heading elements from callback function

Next, we’ll need to write the code for our callback function. The observer will call this function each time elements scroll in or out of view.

When you first render the page, it calls the callback with a list of all the elements on the page. As elements scroll in and out of view, it will call the callback with these elements.

Since we want to keep track of the visibility of all the heading elements, we'll store these values in a useRef hook. You can learn more in my post about storing values with useRef.

const useIntersectionObserver = () => {
  const headingElementsRef = useRef({});

  useEffect(() => {
    const callback = (headings) => {
      headingElementsRef.current = headings.reduce((map, headingElement) => {
        map[headingElement.target.id] = headingElement;
        return map;
      }, headingElementsRef.current);
    }

    const observer = new IntersectionObserver(callback, {
      rootMargin: "0px 0px -40% 0px"
    });

    const headingElements = Array.from(document.querySelectorAll("h2, h3"));

    headingElements.forEach((element) => observer.observe(element));

    return () => observer.disconnect();
  }, []);
};
Enter fullscreen mode Exit fullscreen mode

Calculate the index of the active heading

Each heading element in our headings list has a isIntersecting (or “is visible”) value. It’s possible to have more than one visible heading on the page, so we’ll need to create a list of all visible headings.

We’ll also create a getIndexFromId function. This will let us determine the position of a heading given its ID.

const useIntersectionObserver = () => {
  const headingElementsRef = useRef({});
  useEffect(() => {
    const callback = (headings) => {
      headingElementsRef.current = headings.reduce((map, headingElement) => {
        map[headingElement.target.id] = headingElement;
        return map;
      }, headingElementsRef.current);

      const visibleHeadings = [];
      Object.keys(headingElementsRef.current).forEach((key) => {
        const headingElement = headingElementsRef.current[key];
        if (headingElement.isIntersecting) visibleHeadings.push(headingElement);
      });

      const getIndexFromId = (id) =>
        headingElements.findIndex((heading) => heading.id === id);
    }

    const observer = new IntersectionObserver(callback, {
      rootMargin: "0px 0px -40% 0px"
    });

    const headingElements = Array.from(document.querySelectorAll("h2, h3"));

    headingElements.forEach((element) => observer.observe(element));

    return () => observer.disconnect();
  }, []);
};
Enter fullscreen mode Exit fullscreen mode

Finally, we'll choose the visible heading that is closer to the top of the page. We pass in a function called setActiveId that we'll call once we have found the value.

If there are no visible headings, we'll do nothing, and keep the last visible heading as our “active” heading.

const useIntersectionObserver = (setActiveId) => {
  const headingElementsRef = useRef({});
  useEffect(() => {
    const callback = (headings) => {
      headingElementsRef.current = headings.reduce((map, headingElement) => {
        map[headingElement.target.id] = headingElement;
        return map;
      }, headingElementsRef.current);

      const visibleHeadings = [];
      Object.keys(headingElementsRef.current).forEach((key) => {
        const headingElement = headingElementsRef.current[key];
        if (headingElement.isIntersecting) visibleHeadings.push(headingElement);
      });

      const getIndexFromId = (id) =>
        headingElements.findIndex((heading) => heading.id === id);

      if (visibleHeadings.length === 1) {
        setActiveId(visibleHeadings[0].target.id);
      } else if (visibleHeadings.length > 1) {
        const sortedVisibleHeadings = visibleHeadings.sort(
          (a, b) => getIndexFromId(a.target.id) > getIndexFromId(b.target.id)
        );
        setActiveId(sortedVisibleHeadings[0].target.id);
      }
    };

    const observer = new IntersectionObserver(callback, {
      rootMargin: "0px 0px -40% 0px"
    });

    const headingElements = Array.from(document.querySelectorAll("h2, h3"));

    headingElements.forEach((element) => observer.observe(element));

    return () => observer.disconnect();
  }, [setActiveId]);
};
Enter fullscreen mode Exit fullscreen mode

Highlight the currently active heading

We'll create an activeId state variable to store the currently "active" heading. Then we can pass that information into our Headings component:

const TableOfContents = () => {
  const [activeId, setActiveId] = useState();
  const { nestedHeadings } = useHeadingsData();
  useIntersectionObserver(setActiveId);

  return (
    <nav aria-label="Table of contents">
      <Headings headings={nestedHeadings} activeId={activeId} />
    </nav>
  );
};
Enter fullscreen mode Exit fullscreen mode

And then add an active class to the currently active heading:

const Headings = ({ headings, activeId }) => (
  <ul>
    {headings.map((heading) => (
      <li key={heading.id} className={heading.id === activeId ? "active" : ""}>
        <a
          href={`#${heading.id}`}
          onClick={(e) => {
            e.preventDefault();
            document.querySelector(`#${heading.id}`).scrollIntoView({
              behavior: "smooth"
            });
          }}
        >
          {heading.title}
        </a>
        {heading.items.length > 0 && (
          <ul>
            {heading.items.map((child) => (
              <li key={child.id} className={child.id === activeId ? "active" : ""}>
                <a
                  href={`#${child.id}`}
                  onClick={(e) => {
                    e.preventDefault();
                    document.querySelector(`#${child.id}`).scrollIntoView({
                      behavior: "smooth"
                    });
                  }}
                >
                  {child.title}
                </a>
              </li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
);
Enter fullscreen mode Exit fullscreen mode

Finally, you’ll need some CSS to go along with your active class name:

a {
  color: grey;
  text-decoration: none;
}

li.active > a {
  color: white;
}

li > a:hover {
  color: white;
}
Enter fullscreen mode Exit fullscreen mode

Conclusion

And you're done! 🎉 You'll now have a dynamically generated table of contents that will live alongside the contents of your posts.

Looking for the full code? Check out this tutorial’s Codepen.

PS: Creating a table of contents with Gatsby

If you’re using Gatsby, the methods we’re using above won’t work with server-side rendering (SSR). This means for a Gatsby blog your table of contents will be empty when the page first loads, before they render in.

Gatsby lets you grab the table of contents via GraphQL for both Markdown and MDX. This way you can render the table of contents on the initial server-side render.

Gatsby + Markdown

With Markdown, you can add tableOfContents to your page's GraphQL query:

query($slug: String!) {
    markdownRemark(id: { eq: $id }) {
      tableOfContents
    }
}
Enter fullscreen mode Exit fullscreen mode

This will return you an HTML table of contents which you can directly render on the page:

<ul>
  <li><a href="/hello-world/#initial-header">Initial header</a></li>
  <li>
    <p><a href="/hello-world/#second-header">Second header</a></p>
    <ul>
      <li><a href="/hello-world/#third-header">Third header</a></li>
    </ul>
  </li>
</ul>
Enter fullscreen mode Exit fullscreen mode

Gatsby + MDX

Similarly with MDX you can add tableOfContents to your GraphQL query:

query($slug: String!) {
    mdx(slug: { eq: $slug }) {
        tableOfContents
    }
}
Enter fullscreen mode Exit fullscreen mode

This returns a list of top-level headings. Any child headings will live inside of the items array. This data follows a similar structure to nestedHeadings so it should be straightforward to re-use in your code.

[
    {
        url: '#initial-heading',
        title: 'Initial heading', 
        items: [],
    }
];
Enter fullscreen mode Exit fullscreen mode
Image
Penyiapan Saat sebelum Taruhan Judi Online
Image
Framed Art of Dolomites Italy by Culterra

html
Image
Kubernetes homelab - Learning by doing, Part 3: Networking

learning, kubernetes
Image
The People Who Are Closest To Asbestos Attorney Uncover Big Secrets
Image
Meble, które zmieniają przestrzeń: Trendy i Inspiracje
Image
beberapa jenis macam slots online
Image
10 Myths Your Boss Has About Asbestos Lawyer
Image
Lost the Spark? Try These Salt Lake City Date Ideas to Bring It Back

travel, slc
Image
teknik membuka situs slots online yang terkena internet positif
Image
🚀 Why You Shouldn’t Start with Microservices: A Guide for New Projects
Image
The Billy Butcher Coat: A Must-Have for Every Wardrobe

billybutchercoat, fashioncoat, billybutchertrenchcoat, theboyscoat
Image
Getting Tired Of Asbestos Exposure Lawsuit? 10 Inspirational Sources That Will Rekindle Your Love
Image
Preventing SQL Injection (SQLi) in Symfony: Best Practices with Examples

cybersecurity, sql, sqlserver, symfony
Image
Building a High-Performance Full-Text Search Engine in Go

go, programming, systemdesign, tutorial
Image
service dan spesifikasi yang terus ada pada agen slots online dapat dipercaya
Image
bonus menarik dalam permainan slots online
Image
The Evolution of Communication: Video Conferencing

communication, video, videoconferencing, software
Image
Watch Out: How Asbestos Exposure Attorney Is Taking Over And What We Can Do About It
Image
5 Filter Coffee Machine Tips You Must Know About For 2024
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Terabox Video Player