Loading...
Skip to main content

Scrollspy

Automatically update Bootstrap navigation or list group components based on scroll position to indicate which link is currently active in the viewport.

How it works

ScrollSpy marks navigation links as active when the section referenced by their href is scrolled into view. It works with Nav and ListGroup, as well as other in-page links.

  • To start, scrollspy requires two things: a navigation, list group, or a simple set of links, plus a scrollable container. The scrollable container can be the <body> or a custom element with a set height and overflow-y: scroll.

  • Use ScrollSpy as the scrollable container and set target="#navId", where navId is the unique id of the associated navigation. The component supplies a focusable tabIndex={0} for keyboard access.

  • As you scroll the container, the active state is added to and removed from links in the associated navigation. Links must point to an existing element id; for example, NavLink with href="#home" requires a matching section with id="home".

  • Target elements that are not visible will be ignored. See the Non-visible elements section below.

  • Target ids are matched with getElementById, so ids containing special or percent-encoded characters (for example #item.1, #section:overview, or #%2Fpath) resolve correctly.

Detection

Scrollspy uses an IntersectionObserver to track sections without scroll-position polling. Detection is deterministic and driven entirely by an activation line near the top of the scroll container.

  • The active section is the deepest one whose top has scrolled past the activation line, like the section you’re currently reading.
  • While scrolling through the gap between two headings, the last activated section stays active until the next one crosses the line.
  • At the very top of the container, before any section crosses the line, the first section stays active.
  • At the very bottom of the container, the last section is activated even if its top never reaches the line (handy for short final sections).

Set where the activation line sits with topMargin (a more user-friendly % or px value from the top of the scroll root, such as 96px to sit below a stickied navbar), or take full control with the raw IntersectionObserver rootMargin string. See Options.

Jump to the debug overlay section to visualize the activation line in action.

Examples

Navbar

Scroll the area below the navbar and watch the active state change. Open the menu and watch its items be highlighted as well.

First heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Second heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Third heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Fourth heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Fifth heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

<>
<Navbar
className="bg-1 px-3 mb-3 rounded-2"
id="navbar-example2"
>
<NavbarBrand href="#">
Navbar
</NavbarBrand>
<Nav variant="pills">
<NavLink href="#scrollspyHeading1">
First
</NavLink>
<NavLink href="#scrollspyHeading2">
Second
</NavLink>
<Menu
label="Menu"
nav
>
<MenuItem href="#scrollspyHeading3">
Third
</MenuItem>
<MenuItem href="#scrollspyHeading4">
Fourth
</MenuItem>
<MenuDivider />
<MenuItem href="#scrollspyHeading5">
Fifth
</MenuItem>
</Menu>
</Nav>
</Navbar>
<ScrollSpy
className="bg-1 p-3 rounded-2 overflow-y-auto"
rootMargin="0px 0px -40%"
smoothScroll
style={{
height: '200px'
}}
tabIndex={0}
target="#navbar-example2"
>
<h4 id="scrollspyHeading1">
First heading
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="scrollspyHeading2">
Second heading
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="scrollspyHeading3">
Third heading
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="scrollspyHeading4">
Fourth heading
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="scrollspyHeading5">
Fifth heading
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
</ScrollSpy>
</>

Nested nav

Scrollspy also works with nested .navs. If a nested .nav is .active, its parents will also be .active. Scroll the area next to the navbar and watch the active class change.

Item 1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.

Item 1-1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.

Item 1-2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.

Item 2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.

Item 3

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.

Item 3-1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.

Item 3-2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.

<Row>
<Col xs={4}>
<nav
className="h-100 flex-column align-items-stretch pe-4 border-end"
id="navbar-example3"
>
<Nav
variant="pills"
vertical
>
<NavLink href="#item-1">
Item 1
</NavLink>
<Nav
variant="pills"
vertical
>
<NavLink
className="ms-3 my-1"
href="#item-1-1"
>
Item 1-1
</NavLink>
<NavLink
className="ms-3 my-1"
href="#item-1-2"
>
Item 1-2
</NavLink>
</Nav>
<NavLink href="#item-2">
Item 2
</NavLink>
<NavLink href="#item-3">
Item 3
</NavLink>
<Nav
variant="pills"
vertical
>
<NavLink
className="ms-3 my-1"
href="#item-3-1"
>
Item 3-1
</NavLink>
<NavLink
className="ms-3 my-1"
href="#item-3-2"
>
Item 3-2
</NavLink>
</Nav>
</Nav>
</nav>
</Col>
<Col xs={8}>
<ScrollSpy
className="overflow-y-auto"
smoothScroll
style={{
height: '350px'
}}
tabIndex={0}
target="#navbar-example3"
>
<div id="item-1">
<h4>
Item 1
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<p>
Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.
</p>
</div>
<div id="item-1-1">
<h5>
Item 1-1
</h5>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<p>
Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.
</p>
</div>
<div id="item-1-2">
<h5>
Item 1-2
</h5>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<p>
Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.
</p>
</div>
<div id="item-2">
<h4>
Item 2
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<p>
Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.
</p>
</div>
<div id="item-3">
<h4>
Item 3
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<p>
Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.
</p>
</div>
<div id="item-3-1">
<h5>
Item 3-1
</h5>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<p>
Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.
</p>
</div>
<div id="item-3-2">
<h5>
Item 3-2
</h5>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<p>
Keep in mind that the JavaScript plugin tries to pick the right element among all that may be visible. Multiple visible scrollspy targets at the same time may cause some issues.
</p>
</div>
</ScrollSpy>
</Col>
</Row>

List group

ScrollSpy also works with ListGroup. Scroll the area next to the list group and watch the active state change.

Item 1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 3

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 4

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

<Row>
<Col xs={4}>
<ListGroup
as="div"
id="list-example"
>
<ListGroupItem
action
href="#list-item-1"
>
Item 1
</ListGroupItem>
<ListGroupItem
action
href="#list-item-2"
>
Item 2
</ListGroupItem>
<ListGroupItem
action
href="#list-item-3"
>
Item 3
</ListGroupItem>
<ListGroupItem
action
href="#list-item-4"
>
Item 4
</ListGroupItem>
</ListGroup>
</Col>
<Col xs={8}>
<ScrollSpy
className="overflow-y-auto"
smoothScroll
style={{
height: '200px'
}}
tabIndex={0}
target="#list-example"
>
<h4 id="list-item-1">
Item 1
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="list-item-2">
Item 2
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="list-item-3">
Item 3
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="list-item-4">
Item 4
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
</ScrollSpy>
</Col>
</Row>

Simple anchors

ScrollSpy is not limited to Nav and ListGroup; it also works with in-page links. Scroll the area and watch the active state change.

Item 1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 3

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 4

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 5

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

<Row>
<Col xs={4}>
<div
className="d-flex flex-column gap-2 simple-list-example-scrollspy text-center"
id="simple-list-example"
>
<a
className="p-1 rounded"
href="#simple-list-item-1"
>
Item 1
</a>
<a
className="p-1 rounded"
href="#simple-list-item-2"
>
Item 2
</a>
<a
className="p-1 rounded"
href="#simple-list-item-3"
>
Item 3
</a>
<a
className="p-1 rounded"
href="#simple-list-item-4"
>
Item 4
</a>
<a
className="p-1 rounded"
href="#simple-list-item-5"
>
Item 5
</a>
</div>
</Col>
<Col xs={8}>
<ScrollSpy
className="overflow-y-auto"
smoothScroll
style={{
height: '200px'
}}
tabIndex={0}
target="#simple-list-example"
>
<h4 id="simple-list-item-1">
Item 1
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="simple-list-item-2">
Item 2
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="simple-list-item-3">
Item 3
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="simple-list-item-4">
Item 4
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
<h4 id="simple-list-item-5">
Item 5
</h4>
<p>
This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It’s repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.
</p>
</ScrollSpy>
</Col>
</Row>

Debug overlay

It can be hard to picture exactly where Scrollspy decides a section is active. Enable the debug prop to draw red guides over the scroll container and illustrate the behavior.

  • The red dashed line near the top is the activation line. A section becomes active as its heading scrolls above this line. In this example it sits at 96px.
  • The red bottom zone lights up when you reach the bottom of the container. This is where the last section stays active even if its heading never reaches the activation line.

Scroll the example and watch the highlighted navigation item change as headings cross the line. Guide positions are computed from the same topMargin/rootMargin detection math the component uses.

First section

Watch the activation line while scrolling this container.

Last section

The bottom zone selects the final section.

<>
<Nav
id="debug-scrollspy-nav"
variant="pills"
>
<NavLink href="#debug-scrollspy-first">
First
</NavLink>
<NavLink href="#debug-scrollspy-last">
Last
</NavLink>
</Nav>
<ScrollSpy
className="overflow-y-auto border rounded p-3"
debug
style={{
height: 240
}}
target="#debug-scrollspy-nav"
topMargin="96px"
>
<section
className="py-5"
id="debug-scrollspy-first"
>
<h4>
First section
</h4>
<p>
Watch the activation line while scrolling this container.
</p>
</section>
<section
className="py-5"
id="debug-scrollspy-last"
>
<h4>
Last section
</h4>
<p>
The bottom zone selects the final section.
</p>
</section>
</ScrollSpy>
</>

Non-visible elements

Target elements that aren’t visible will be ignored and their corresponding nav items won’t receive an .active class. Scrollspy instances initialized in a non-visible wrapper will ignore all target elements. Use the refresh method to check for observable elements once the wrapper becomes visible.

Call the component’s refresh() method after revealing content outside React; changes to its props are observed automatically.

Usage

The component initializes on mount and releases its observers and listeners on unmount. Set scrollRoot="window" to observe page scrolling instead of the component's own scrollable element.

Options

Pass options as React props:

NameTypeDefaultDescription
rootMarginstring or nullnullAdvanced IntersectionObserver root margin. When set, it takes precedence over topMargin, for example 0px 0px -40%.
smoothScrollbooleanfalseSmoothly scroll to a clicked target, then update the URL hash and move focus to it.
targetstring—Selector for the navigation whose links match the observed sections.
thresholdnumber[][0]IntersectionObserver thresholds.
topMarginstring'12%'Position of the activation line from the top of the scroll root. Accepts percentages or pixels.
scrollRoot'self' or 'window''self'Element or viewport scrolling.
debugbooleanfalseDraw the activation line and bottom-zone guides.

Methods

Use the instance method refresh() after adding, removing, or revealing observed DOM content outside React. Children and relevant prop changes refresh the component automatically.

Events

Use onActiveChange(id) to respond when a different section becomes active.

Documentation navigation
On this page
On this page