Scrollspy

Mark the link to the section being read in a navigation, as the page or a box scrolls.

Overview

<Scrollspy> wraps a navigation whose links point to sections of the same page, such as a table of contents, and marks the link to the section being read. It observes the sections with an IntersectionObserver, in the viewport or in an element that scrolls, and follows chassis-css's scrollspy: the link gets .active, and the links it is nested under do too.

It renders no element of its own. The links it marks are Links and the components built on it: NavLink and NavItem in a Nav, an interactive ListItem in a List, and a MenuItem in a Menu. A link takes part when its href points to an element's id on the current page, whether the href is on the component or, under asChild, on the element it renders. A disabled link takes no part.

The active section is the last one, in document order, whose top has scrolled past a line near the bottom of the scrolling area. rootMargin sets that line: by default a quarter of the area's height above its bottom edge. Before any section has reached it, no link is marked. Once the area is scrolled to its end the last section is the active one, wherever its top is: a short last section never reaches the line.

Basic usage

Wrap the navigation, and give root the element that scrolls, as a ref. Leave root out when the page itself scrolls. The box below is focusable, so it scrolls from the keyboard too.

This is some placeholder content for the scrollspy example. As the box scrolls, the link to the section being read is marked. It is repeated in every section, to give the box enough to scroll.

import { useRef } from 'react'
import {
  Container,
  Menu,
  MenuDivider,
  MenuItem,
  MenuList,
  MenuToggle,
  Navbar,
  NavbarBrand,
  NavbarNav,
  NavItem,
  NavLink,
  Scrollspy
} from '@chassis-ui/react'

const text =
  'This is some placeholder content for the scrollspy example. As the box scrolls, the link to ' +
  'the section being read is marked. It is repeated in every section, to give the box enough ' +
  'to scroll.'

const sections = ['First', 'Second', 'Third', 'Fourth', 'Fifth']

export const Example = () => {
  const box = useRef<HTMLDivElement>(null)
  return (
    <>
      <Navbar expand className="bg-evident px-md mb-md rounded-sm" aria-label="Scrollspy example">
        <Container fluid>
          <NavbarBrand href="#">Navbar</NavbarBrand>
          <Scrollspy root={box} rootMargin="0px 0px -40%" smoothScroll>
            <NavbarNav>
              <NavItem href="#navbar-first">First</NavItem>
              <NavItem href="#navbar-second">Second</NavItem>
              <Menu component="li" className="nav-item">
                <MenuToggle component={NavLink}>More</MenuToggle>
                <MenuList>
                  <MenuItem href="#navbar-third">Third</MenuItem>
                  <MenuItem href="#navbar-fourth">Fourth</MenuItem>
                  <MenuDivider />
                  <MenuItem href="#navbar-fifth">Fifth</MenuItem>
                </MenuList>
              </Menu>
            </NavbarNav>
          </Scrollspy>
        </Container>
      </Navbar>
      <div
        ref={box}
        role="region"
        aria-label="Sections"
        tabIndex={0}
        className="bg-evident p-md rounded-sm"
        style={{ height: 200, overflowY: 'auto', position: 'relative' }}
      >
        {sections.map((title) => (
          <div key={title}>
            <h4 id={`navbar-${title.toLowerCase()}`}>{title} heading</h4>
            <p>{text}</p>
          </div>
        ))}
      </div>
    </>
  )
}

With smoothScroll, a click on a link scrolls to its section smoothly instead of jumping, and the page's address doesn't change. The section lands where a jump would put it, below the scrolling element's scroll-padding-top and its own scroll-margin-top, so set those for a sticky header. A reader who asks for reduced motion gets the jump.

A link just before a nested Nav is marked while one of the nested links is. So is the toggle of a menu while one of its items is, as in the navbar above. Those links look active; only the link to the section itself is the current one for assistive technology.