Reading index with a progress bar

A pattern built for guides and documentation: it shows how much is left, highlights the current section and offers a quick way back to the top of the content.

Code in the Snippet Library All components

Chapter 1

Context

In a long guide the reader needs to know where they are without losing the thread. A side index helps with orientation and reduces the need to keep scrolling back to the top.

The progress bar doesn't replace the headings, but it adds immediate feedback about how far the end is.

Chapter 2

Setup

The markup separates index, content and progress bar. The JavaScript reads the available sections and keeps the active link and the scroll percentage in sync.

On real pages you can hook it to the whole document or to a scrollable container, as in this demo.

Chapter 3

Checks

The component has to stay readable, must not cover content and should work even without complex animations. The index links use plain anchors and remain understandable.

The back-to-top button is useful when the content is very long or when the index becomes sticky on the final page.

Chapter 4

Next steps

You can add subsections, counters, a completed state, or integration with the Codedge guide layout. The base stays small and easy to maintain.

The point isn't to decorate the scroll: it's to orient the reader.

When to use it

For long guides, documentation, detailed changelogs and tutorial pages with many sections.

What it solves

It makes position, progress and a quick way back visible, without relying on a plain fixed button.

How to adapt it

Use it with the whole document or with a scrollable container. You can make the index sticky on desktop.

Improving the UX of long guides and articles with a reading index and progress bar

When people read long articles, technical documentation or detailed guides, they can easily lose their bearings or underestimate the effort needed to finish. An interactive reading index (a table of contents, or TOC) paired with a visual scroll progress bar noticeably improves the user experience, encouraging readers to finish and offering quick anchor points for jumping between sections.

This component uses a split layout: a side panel acting as the index and a main container for the text. Using JavaScript and the Intersection Observer API (or by watching the scroll event), the script detects which section is on screen and applies a state class (such as is-active) to the matching link in the index. At the same time, the horizontal progress bar at the top fills according to how far the text has been scrolled inside the container.

From an accessibility standpoint, the side index sits inside an <aside> tag with a descriptive aria-label="Guide index", letting screen readers identify it as a quick navigation area. The index links point to the internal anchors of the section headings through unique IDs. There is also an accessible "Back to top" button, which quickly returns the view to the start of the document — ideal for avoiding long manual scrolling, especially on mobile.

Quick FAQ about the reading index

How is the progress bar percentage calculated?

JavaScript calculates the ratio between the distance already scrolled (scrollTop) and the total scrollable distance (scrollHeight - clientHeight) of the scroll container, converting it into a percentage that dynamically updates the progress bar's inline width.

Is Intersection Observer better than the scroll event for detecting the active section?

Yes. Intersection Observer performs far better because it doesn't hammer the main thread with constant calculations on every single scrolled pixel. The script only fires when the defined sections enter or leave the viewport at the configured thresholds.

How does the 'Back to top' button work for accessibility?

The button scrolls smoothly to the top via JavaScript and — importantly — restores logical focus to the start of the document or to the main container, so keyboard and screen reader users can pick up navigation immediately.