Scrollspy

Actualiza automáticamente los componentes de navegación o grupo de lista de Bootstrap según la posición de desplazamiento para indicar qué enlace está actualmente activo en el viewport.

On this page

Cómo funciona

Scrollspy alterna la clase .active en los elementos anchor (<a>) cuando el elemento con el id referenciado por el href del anchor se desplaza a la vista. Scrollspy funciona mejor junto con un componente nav de Bootstrap o un grupo de lista, pero también funcionará con cualquier elemento anchor en la página actual. Así es como funciona.

Para empezar, scrollspy requiere dos cosas: una navegación, grupo de lista o un conjunto simple de enlaces, más un contenedor desplazable. El contenedor desplazable puede ser el <body> o un elemento personalizado con una height establecida y overflow-y: scroll.
En el contenedor desplazable, añade data-bs-spy="scroll" y data-bs-target="#navId" donde navId es el id único de la navegación asociada. Si no hay ningún elemento enfocable dentro del elemento, asegúrate de incluir también un tabindex="0" para garantizar el acceso por teclado.
A medida que te desplazas por el contenedor “espiado”, se añade y elimina una clase .active de los enlaces anchor dentro de la navegación asociada. Los enlaces deben tener objetivos id resolubles, de lo contrario se ignoran. Por ejemplo, un <a href="#home">home</a> debe corresponder con algo en el DOM como <div id="home"></div>
Los elementos objetivo que no sean visibles serán ignorados. Consulta la sección Elementos no visibles a continuación.

Ejemplos

Desplázate por el área debajo del navbar y observa cómo cambia la clase active. Abre el menú dropdown y observa cómo los elementos del dropdown también se resaltan.

Primer encabezado

Este es un contenido de marcador de posición para la página de scrollspy. Ten en cuenta que a medida que desplazas la página hacia abajo, el enlace de navegación correspondiente se resalta. Se repite a lo largo del ejemplo del componente. Seguimos añadiendo más texto de ejemplo aquí para enfatizar el desplazamiento y el resaltado.

Segundo encabezado

Tercer encabezado

Cuarto encabezado

Quinto encabezado

<nav id="navbar-example2" class="navbar bg-body-tertiary px-3 mb-3">
  <a class="navbar-brand" href="#">Navbar</a>
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading1">First</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading2">Second</a>
    </li>
    <li class="nav-item dropdown">
      <a class="nav-link dropdown-toggle" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">Dropdown</a>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#scrollspyHeading3">Third</a></li>
        <li><a class="dropdown-item" href="#scrollspyHeading4">Fourth</a></li>
        <li><hr class="dropdown-divider"></li>
        <li><a class="dropdown-item" href="#scrollspyHeading5">Fifth</a></li>
      </ul>
    </li>
  </ul>
</nav>
<div data-bs-spy="scroll" data-bs-target="#navbar-example2" data-bs-root-margin="0px 0px -40%" data-bs-smooth-scroll="true" class="scrollspy-example bg-body-tertiary p-3 rounded-2" tabindex="0">
  <h4 id="scrollspyHeading1">First heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading2">Second heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading3">Third heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading4">Fourth heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading5">Fifth heading</h4>
  <p>...</p>
</div>

Nav anidado

Scrollspy también funciona con .navs anidados. Si un .nav anidado está .active, sus padres también estarán .active. Desplaza el área junto al navbar y observa cómo cambia la clase activa.

Elemento 1

Ten en cuenta que el plugin de JavaScript intenta elegir el elemento correcto entre todos los que puedan ser visibles. Múltiples objetivos de scrollspy visibles al mismo tiempo pueden causar algunos problemas.

Elemento 1-1

Elemento 1-2

Elemento 2

Elemento 3

Elemento 3-1

Elemento 3-2

<div class="row">
  <div class="col-4">
    <nav id="navbar-example3" class="h-100 flex-column align-items-stretch pe-4 border-end">
      <nav class="nav nav-pills flex-column">
        <a class="nav-link" href="#item-1">Item 1</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-1-1">Item 1-1</a>
          <a class="nav-link ms-3 my-1" href="#item-1-2">Item 1-2</a>
        </nav>
        <a class="nav-link" href="#item-2">Item 2</a>
        <a class="nav-link" href="#item-3">Item 3</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-3-1">Item 3-1</a>
          <a class="nav-link ms-3 my-1" href="#item-3-2">Item 3-2</a>
        </nav>
      </nav>
    </nav>
  </div>

  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-smooth-scroll="true" class="scrollspy-example-2" tabindex="0">
      <div id="item-1">
        <h4>Item 1</h4>
        <p>...</p>
      </div>
      <div id="item-1-1">
        <h5>Item 1-1</h5>
        <p>...</p>
      </div>
      <div id="item-1-2">
        <h5>Item 1-2</h5>
        <p>...</p>
      </div>
      <div id="item-2">
        <h4>Item 2</h4>
        <p>...</p>
      </div>
      <div id="item-3">
        <h4>Item 3</h4>
        <p>...</p>
      </div>
      <div id="item-3-1">
        <h5>Item 3-1</h5>
        <p>...</p>
      </div>
      <div id="item-3-2">
        <h5>Item 3-2</h5>
        <p>...</p>
      </div>
    </div>
  </div>
</div>

Grupo de lista

Scrollspy también funciona con .list-groups. Desplaza el área junto al grupo de lista y observa cómo cambia la clase activa.

Elemento 1 Elemento 2 Elemento 3 Elemento 4

Elemento 1

Elemento 2

Elemento 3

Elemento 4

<div class="row">
  <div class="col-4">
    <div id="list-example" class="list-group">
      <a class="list-group-item list-group-item-action" href="#list-item-1">Item 1</a>
      <a class="list-group-item list-group-item-action" href="#list-item-2">Item 2</a>
      <a class="list-group-item list-group-item-action" href="#list-item-3">Item 3</a>
      <a class="list-group-item list-group-item-action" href="#list-item-4">Item 4</a>
    </div>
  </div>
  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#list-example" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0">
      <h4 id="list-item-1">Item 1</h4>
      <p>...</p>
      <h4 id="list-item-2">Item 2</h4>
      <p>...</p>
      <h4 id="list-item-3">Item 3</h4>
      <p>...</p>
      <h4 id="list-item-4">Item 4</h4>
      <p>...</p>
    </div>
  </div>
</div>

Anclas simples

Scrollspy no se limita a componentes nav y grupos de lista, por lo que funcionará en cualquier elemento anchor <a> en el documento actual. Desplázate por el área y observa cómo cambia la clase .active.

Elemento 1 Elemento 2 Elemento 3 Elemento 4 Elemento 5

Elemento 1

Elemento 2

Elemento 3

Elemento 4

Elemento 5

<div class="row">
  <div class="col-4">
    <div id="simple-list-example" class="d-flex flex-column gap-2 simple-list-example-scrollspy text-center">
      <a class="p-1 rounded" href="#simple-list-item-1">Item 1</a>
      <a class="p-1 rounded" href="#simple-list-item-2">Item 2</a>
      <a class="p-1 rounded" href="#simple-list-item-3">Item 3</a>
      <a class="p-1 rounded" href="#simple-list-item-4">Item 4</a>
      <a class="p-1 rounded" href="#simple-list-item-5">Item 5</a>
    </div>
  </div>
  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#simple-list-example" data-bs-offset="0" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0">
      <h4 id="simple-list-item-1">Item 1</h4>
      <p>...</p>
      <h4 id="simple-list-item-2">Item 2</h4>
      <p>...</p>
      <h4 id="simple-list-item-3">Item 3</h4>
      <p>...</p>
      <h4 id="simple-list-item-4">Item 4</h4>
      <p>...</p>
      <h4 id="simple-list-item-5">Item 5</h4>
      <p>...</p>
    </div>
  </div>
</div>

Elementos no visibles

Los elementos objetivo que no sean visibles serán ignorados y sus elementos de navegación correspondientes no recibirán una clase .active. Las instancias de scrollspy inicializadas en un contenedor no visible ignorarán todos los elementos objetivo. Usa el método refresh para comprobar los elementos observables una vez que el contenedor sea visible.

document.querySelectorAll('#nav-tab>[data-bs-toggle="tab"]').forEach(el => {
  el.addEventListener('shown.bs.tab', () => {
    const target = el.getAttribute('data-bs-target')
    const scrollElem = document.querySelector(`${target} [data-bs-spy="scroll"]`)
    bootstrap.ScrollSpy.getOrCreateInstance(scrollElem).refresh()
  })
})

Uso

Vía atributos data

Para añadir fácilmente el comportamiento de scrollspy a tu navegación de barra superior, añade data-bs-spy="scroll" al elemento que quieres espiar (normalmente sería el <body>). Luego añade el atributo data-bs-target con el id o nombre de clase del elemento padre de cualquier componente .nav de Bootstrap.

<body data-bs-spy="scroll" data-bs-target="#navbar-example">
  ...
  <div id="navbar-example">
    <ul class="nav nav-tabs" role="tablist">
      ...
    </ul>
  </div>
  ...
</body>

Vía JavaScript

const scrollSpy = new bootstrap.ScrollSpy(document.body, {
  target: '#navbar-example'
})

Opciones

Como las opciones se pueden pasar vía atributos data o JavaScript, puedes añadir un nombre de opción a data-bs-, como en data-bs-animation="{value}". Asegúrate de cambiar el tipo de capitalización del nombre de la opción de “camelCase” a “kebab-case” al pasar las opciones vía atributos data. Por ejemplo, usa data-bs-custom-class="beautifier" en lugar de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos los componentes soportan un atributo data reservado experimental data-bs-config que puede albergar una configuración simple del componente como una cadena JSON. Cuando un elemento tiene los atributos data-bs-config='{"delay":0, "title":123}' y data-bs-title="456", el valor final de title será 456 y los atributos data separados sobrescribirán los valores dados en data-bs-config. Además, los atributos data existentes pueden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

El objeto de configuración final es el resultado de combinar data-bs-config, data-bs-, y el objeto js, donde el último par clave-valor dado sobrescribe a los demás.

Nombre	Tipo	Predeterminado	Descripción
`rootMargin`	string	`0px 0px -25%`	Unidades válidas de rootMargin del Intersection Observer, al calcular la posición de scroll.
`smoothScroll`	boolean	`false`	Activa el desplazamiento suave cuando un usuario hace clic en un enlace que hace referencia a los observables de ScrollSpy.
`target`	string, elemento DOM	`null`	Especifica el elemento al que aplicar el plugin Scrollspy.
`threshold`	array	`[0.1, 0.5, 1]`	Entrada válida de threshold del `IntersectionObserver`, al calcular la posición de scroll.

Deprecated Options

Hasta la v5.1.3 usábamos las opciones offset y method, que ahora están obsoletas y han sido reemplazadas por rootMargin. Para mantener la compatibilidad con versiones anteriores, continuaremos analizando un offset dado a rootMargin, pero esta función se eliminará en v6.

Métodos

Método	Descripción
`dispose`	Destruye el scrollspy de un elemento. (Elimina los datos almacenados en el elemento del DOM)
`getInstance`	Método estático para obtener la instancia de scrollspy asociada con un elemento del DOM.
`getOrCreateInstance`	Método estático para obtener la instancia de scrollspy asociada con un elemento del DOM, o crear una nueva en caso de que no estuviera inicializada.
`refresh`	Al añadir o eliminar elementos en el DOM, tendrás que llamar al método refresh.

Aquí hay un ejemplo usando el método refresh:

const dataSpyList = document.querySelectorAll('[data-bs-spy="scroll"]')
dataSpyList.forEach(dataSpyEl => {
  bootstrap.ScrollSpy.getInstance(dataSpyEl).refresh()
})

Eventos

Evento	Descripción
`activate.bs.scrollspy`	Este evento se dispara en el elemento de scroll cada vez que un anchor es activado por el scrollspy.

const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
  // do something...
})