Scrollspy

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

On this page

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.

vue
<template>
  <Navbar
    padding="x-3"
    theme="light"
    background-color="light"
  >
    <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"
        theme="light"
        background-color="light"
        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>
          <b-a
            padding="1"
            rounded
            display="block"
            target="#simple-list-item-1"
          >
            Item 1
          </b-a>
        </list-item>
        <list-item>
          <b-a
            padding="1"
            rounded
            display="block"
            target="#simple-list-item-2"
          >
            Item 2
          </b-a>
        </list-item>
        <list-item>
          <b-a
            padding="1"
            rounded
            display="block"
            target="#simple-list-item-3"
          >
            Item 3
          </b-a>
        </list-item>
        <list-item>
          <b-a
            padding="1"
            rounded
            display="block"
            target="#simple-list-item-4"
          >
            Item 4
          </b-a>
        </list-item>
        <list-item>
          <b-a
            padding="1"
            rounded
            display="block"
            target="#simple-list-item-5"
          >
            Item 5
          </b-a>
        </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: rgba(var(--bd-violet-rgb), 0.15)
}
</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.