[Bug] TOC active section highlight breaks after navigating between pages
- Dominant language
- TypeScript
- Stars
- 716
- Forks
- 1.2k
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 35
Description
### Describe the bug you found in AsyncAPI Docs.
## 🐛 Docs TOC active section highlight breaks after navigating between pages
### Why do we need this improvement?
Currently, the **“On this page” (Table of Contents)** highlighting works correctly when a docs page is loaded for the first time. However, after navigating to another docs page using client-side navigation and then returning (or moving to the next page), the **active section highlighting stops working completely**.
Observed behavior:
- On initial page load, the current section is highlighted correctly (purple).
- After navigating to another docs page, no TOC item is highlighted.
- Navigating back to the previous page does not restore the highlight.
- Page reload fixes the issue temporarily.
This negatively impacts usability and makes it harder for users to understand their current position within long documentation pages.
---
### How will this change help?
Fixing this issue will:
- Ensure the TOC correctly highlights the active section across docs navigation.
- Improve readability and navigation consistency in the documentation.
- Align expected behavior when moving between docs pages using client-side routing.
---
### Root cause (technical context)
The TOC relies on `react-scrollspy`, which attaches scroll listeners and caches DOM references on mount.
Since the Docs layout persists across client-side route changes, the TOC component is not remounted when navigating between docs pages, leaving `react-scrollspy` in a stale state.
---
### 🎥 Problem Video
The following video demonstrates the issue:
- TOC highlight works on first load
- Highlight disappears after navigating to another docs page
- Highlight does not recover when navigating back
https://github.com/user-attachments/assets/15a3e501-3cde-49d1-9a0b-985493bfa7de
---
### ✅ Solved Video
The following video demonstrates the expected / fixed behavior:
- TOC highlight updates correctly after navigation
- Highlight persists when navigating between docs pages
- Behavior remains consistent without a full page reload
https://github.com/user-attachments/assets/0c75c9ff-566f-4244-9ad8-366e99d677dc
---
### How could it be implemented/designed?
A possible fix is to **force the TOC component to reinitialize on route change**, for example:
- Remounting the TOC component when the route changes (e.g., by keying it to `router.asPath`), or
- Explicitly resetting the Scrollspy lifecycle when navigating between docs pages.
---
### Alternatives
If forcing a remount is not preferred:
- The TOC logic could explicitly reattach Scrollspy listeners on route change.
- Scrollspy observers could be cleaned up and reinitialized when the content changes.
---
### Attach any resources that can help us understand the issue.
### Code of Conduct
- I agree to follow this project's Code of Conduct
### Are you willing to work on this issue ?
Yes, I am willing to submit a PR for this issue.
Contributor guide
Research direction
Locate the Docs TOC component and its react-scrollspy usage, then inspect how the persistent Docs layout handles client-side route changes. Reproduce navigation between documentation pages and verify that the active section highlight is restored without a full reload.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- nextjs, react, typescript
- Domain
- documentation, frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100