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

  • It must be used on a Bootstrap nav component or list group .
  • Scrollspy requires position: relative; on the element you're spying on, usually the <body>.
  • Anchors (b-a) are required and must point to an element with that id.

When successfully implemented, your nav or list group will update accordingly, moving the active class from one item to the next based on their associated targets.

Example

Navbar

Scroll the area below the navbar and watch the active class change. The dropdown items will be highlighted as well.

Navbar
vue
<template>
 <Navbar
  padding="x-3"
  background-color="body-tertiary"
 >
  <NavbarBrand>Navbar</NavbarBrand>
  <NavList
   nav="pills"
   spy="#navbar-target2"
  >
   <NavItem>
    <NavLink target="#scrollspyHeading1">
     First
    </NavLink>
   </NavItem>
   <NavItem>
    <NavLink target="#scrollspyHeading2">
     Link
    </NavLink>
   </NavItem>
   <NavItemDropdown>
    <NavItemDropdownToggle>Dropdown</NavItemDropdownToggle>
    <DropdownMenu>
     <DropdownItem target="#scrollspyHeading3">
      Third
     </DropdownItem>
     <DropdownItem target="#scrollspyHeading4">
      Fourth
     </DropdownItem>
     <DropdownItemDivider />
     <DropdownItem target="#scrollspyHeading5">
      Fifth
     </DropdownItem>
    </DropdownMenu>
   </NavItemDropdown>
  </NavList>
 </Navbar>
 <b-div
  id="navbar-target2"
  style="height: 200px; margin-top: 0.5rem; overflow: auto"
 >
  <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>
 </b-div>
</template>

Nested Nav

Scrollspy also works with nested Navs component.

If a nested Nav component is active, its parents will also be active

Scroll the area next to the navbar and watch the active class change.

vue
<template>
 <Row>
  <Col col="4">
   <Navbar
    padding="3"
    background-color="body-tertiary"
    align-items="stretch"
   >
    <Nav
     nav="pills"
     flex-direction="column"
     spy="#navbar-target3"
    >
     <NavLink target="#item-1">
      Item 1
     </NavLink>
     <Nav
      nav="pills"
      flex-direction="column"
      :parent="false"
     >
      <NavLink
       margin="s-3 y-1"
       target="#item-1-1"
      >
       Item 1-1
      </NavLink>
      <NavLink
       margin="s-3 y-1"
       target="#item-1-2"
      >
       Item 1-2
      </NavLink>
     </Nav>
     <NavLink target="#item-2">
      Item 2
     </NavLink>
     <NavLink target="#item-3">
      Item 3
     </NavLink>
     <Nav
      nav="pills"
      flex-direction="column"
      :parent="false"
     >
      <NavLink
       margin="s-3 y-1"
       target="#item-3-1"
      >
       Item 3-1
      </NavLink>
      <NavLink
       margin="s-3 y-1"
       target="#item-3-2"
      >
       Item 3-2
      </NavLink>
     </Nav>
    </Nav>
   </Navbar>
  </Col>
  <Col col="8">
   <b-div
    id="navbar-target3"
    style="height: 350px; margin-top: 0.5rem; overflow: auto"
   >
    <h4 id="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>
    <h5 id="item-1-1">
     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>
    <h5 id="item-1-2">
     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>
    <h4 id="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="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>
    <h5 id="item-3-1">
     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>
    <h5 id="item-3-2">
     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>
   </b-div>
  </Col>
 </Row>
</template>

List group

Scrollspy also works with ListGroupLists component.

Scroll the area next to the list group and watch the active class change.

Item 1 Item 2 Item 3 Item 4

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.

vue
<template>
 <Row>
  <Col col="4">
   <ListGroup spy="#list-example">
    <ListGroupItemAction target="#list-item-1">
     Item 1
    </ListGroupItemAction>
    <ListGroupItemAction target="#list-item-2">
     Item 2
    </ListGroupItemAction>
    <ListGroupItemAction target="#list-item-3">
     Item 3
    </ListGroupItemAction>
    <ListGroupItemAction target="#list-item-4">
     Item 4
    </ListGroupItemAction>
   </ListGroup>
  </Col>
  <Col col="8">
   <b-div
    id="list-example"
    offset="0"
    style="height: 200px; margin-top: 0.5rem; overflow: auto"
   >
    <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>
   </b-div>
  </Col>
 </Row>
</template>

Simple anchors

Scrollspy is not limited to nav components and list groups, so it will work on any <a> anchor elements in the current document. Scroll the area 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.

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.

vue
<template>
 <Row>
  <Col col="4">
   <list
    unstyled
    spy="#simple-list-example"
    flex
    flex-direction="column"
    gap="2"
    text-alignment="center"
    class="simple-list-example-scrollspy"
   >
    <list-item>
     <Anchor
      padding="1"
      rounded
      display="block"
      target="#simple-list-item-1"
     >
      Item 1
     </Anchor>
    </list-item>
    <list-item>
     <Anchor
      padding="1"
      rounded
      display="block"
      target="#simple-list-item-2"
     >
      Item 2
     </Anchor>
    </list-item>
    <list-item>
     <Anchor
      padding="1"
      rounded
      display="block"
      target="#simple-list-item-3"
     >
      Item 3
     </Anchor>
    </list-item>
    <list-item>
     <Anchor
      padding="1"
      rounded
      display="block"
      target="#simple-list-item-4"
     >
      Item 4
     </Anchor>
    </list-item>
    <list-item>
     <Anchor
      padding="1"
      rounded
      display="block"
      target="#simple-list-item-5"
     >
      Item 5
     </Anchor>
    </list-item>
   </list>
  </Col>
  <Col col="8">
   <b-div
    id="simple-list-example"
    style="height: 200px; margin-top: 0.5rem; overflow: auto"
   >
    <b-h4 id="simple-list-item-1">
     Item 1
    </b-h4>
    <b-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.
    </b-p>
    <b-h4 id="simple-list-item-2">
     Item 2
    </b-h4>
    <b-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.
    </b-p>
    <b-h4 id="simple-list-item-3">
     Item 3
    </b-h4>
    <b-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.
    </b-p>
    <b-h4 id="simple-list-item-4">
     Item 4
    </b-h4>
    <b-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.
    </b-p>
    <b-h4 id="simple-list-item-5">
     Item 5
    </b-h4>
    <b-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.
    </b-p>
   </b-div>
  </Col>
 </Row>
</template>

<style>
.simple-list-example-scrollspy .active {
  background-color: var(--bs-blue-100)
}
</style>

Usage

Via data attributes

To easily add scrollspy behavior to your topbar navigation, add spy="scroll" to the element you want to spy on (most typically this would be the <body>).

Then add the target attribute with the ID or class of the parent element of any Bootstrap Nav component.

Resolvable ID targets required

Navbar links must have resolvable id targets.

For example, a <b-a href ="#home">home<b-a> must correspond to something in the DOM like <b-a href ="#home">home<b-a>.

Non-visible target elements ignored

Target elements that are not visible will be ignored and their corresponding nav items will never be highlighted.