Scrollspy

Actualiza automáticamente la navegación o los componentes del grupo de listas de Bootstrap en función de la posición de desplazamiento para indicar qué enlace está actualmente activo en la ventana gráfica (viewport).

En esta página

Cómo funciona

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

Para comenzar, scrollspy requiere dos cosas: una navegación, un grupo de listas o un conjunto simple de enlaces, además de un contenedor desplazable. El contenedor desplazable puede ser el <body> o un elemento personalizado con una altura (height) establecida y overflow-y: scroll.
En el contenedor desplazable, agrega data-bs-spy="scroll" and 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 agrega y elimina una clase .active de los enlaces dentro de la navegación asociada. Los enlaces deben tener objetivos de id resolubles; de lo contrario, se ignoran. Por ejemplo, un <a href="#home">home</a> debe corresponder a algo en el DOM como <div id="home"></div>
Los elementos de destino que no sean visibles se ignorarán. Consulta la sección Elementos no visibles a continuación.

Ejemplos

Barra de navegación

Desplázate por el área debajo de la barra de navegación y observa cómo cambia la clase activa. Abre el menú desplegable y observa cómo se resaltan también los elementos del menú desplegable.

Primer encabezado

Este es un contenido de marcador de posición para la página de scrollspy. Ten en cuenta que a medida que te desplazas hacia abajo en la página, se resalta el enlace de navegación correspondiente. Se repite a lo largo del ejemplo del componente. Seguimos agregando 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">Primero</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading2">Segundo</a>
    </li>
    <li class="nav-item dropdown">
      <a class="nav-link dropdown-toggle" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">Desplegable</a>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#scrollspyHeading3">Tercero</a></li>
        <li><a class="dropdown-item" href="#scrollspyHeading4">Cuarto</a></li>
        <li><hr class="dropdown-divider"></li>
        <li><a class="dropdown-item" href="#scrollspyHeading5">Quinto</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">Primer encabezado</h4>
  <p>...</p>
  <h4 id="scrollspyHeading2">Segundo encabezado</h4>
  <p>...</p>
  <h4 id="scrollspyHeading3">Tercer encabezado</h4>
  <p>...</p>
  <h4 id="scrollspyHeading4">Cuarto encabezado</h4>
  <p>...</p>
  <h4 id="scrollspyHeading5">Quinto encabezado</h4>
  <p>...</p>
</div>

Navegación anidada

Scrollspy también funciona con .nav anidados. Si un .nav anidado está .active, sus padres también estarán .active. Desplázate por el área junto a la barra de navegación y observa cómo cambia la clase activa.

Elemento 1

Ten en cuenta que el plugin de JavaScript intenta elegir el elemento correcto de entre todos los que puedan estar 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">Elemento 1</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-1-1">Elemento 1-1</a>
          <a class="nav-link ms-3 my-1" href="#item-1-2">Elemento 1-2</a>
        </nav>
        <a class="nav-link" href="#item-2">Elemento 2</a>
        <a class="nav-link" href="#item-3">Elemento 3</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-3-1">Elemento 3-1</a>
          <a class="nav-link ms-3 my-1" href="#item-3-2">Elemento 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>Elemento 1</h4>
        <p>...</p>
      </div>
      <div id="item-1-1">
        <h5>Elemento 1-1</h5>
        <p>...</p>
      </div>
      <div id="item-1-2">
        <h5>Elemento 1-2</h5>
        <p>...</p>
      </div>
      <div id="item-2">
        <h4>Elemento 2</h4>
        <p>...</p>
      </div>
      <div id="item-3">
        <h4>Elemento 3</h4>
        <p>...</p>
      </div>
      <div id="item-3-1">
        <h5>Elemento 3-1</h5>
        <p>...</p>
      </div>
      <div id="item-3-2">
        <h5>Elemento 3-2</h5>
        <p>...</p>
      </div>
    </div>
  </div>
</div>

Grupo de lista

Scrollspy también funciona con .list-group. Desplázate por 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">Elemento 1</a>
      <a class="list-group-item list-group-item-action" href="#list-item-2">Elemento 2</a>
      <a class="list-group-item list-group-item-action" href="#list-item-3">Elemento 3</a>
      <a class="list-group-item list-group-item-action" href="#list-item-4">Elemento 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">Elemento 1</h4>
      <p>...</p>
      <h4 id="list-item-2">Elemento 2</h4>
      <p>...</p>
      <h4 id="list-item-3">Elemento 3</h4>
      <p>...</p>
      <h4 id="list-item-4">Elemento 4</h4>
      <p>...</p>
    </div>
  </div>
</div>

Enlaces simples

Scrollspy no se limita a componentes de navegación y grupos de listas, por lo que funcionará en cualquier elemento de enlace <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">Elemento 1</a>
      <a class="p-1 rounded" href="#simple-list-item-2">Elemento 2</a>
      <a class="p-1 rounded" href="#simple-list-item-3">Elemento 3</a>
      <a class="p-1 rounded" href="#simple-list-item-4">Elemento 4</a>
      <a class="p-1 rounded" href="#simple-list-item-5">Elemento 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">Elemento 1</h4>
      <p>...</p>
      <h4 id="simple-list-item-2">Elemento 2</h4>
      <p>...</p>
      <h4 id="simple-list-item-3">Elemento 3</h4>
      <p>...</p>
      <h4 id="simple-list-item-4">Elemento 4</h4>
      <p>...</p>
      <h4 id="simple-list-item-5">Elemento 5</h4>
      <p>...</p>
    </div>
  </div>
</div>

Elementos no visibles

Los elementos de destino que no sean visibles se ignorarán 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 de destino. Utiliza el método refresh para verificar los elementos observables una vez que el contenedor se vuelva 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

A través de atributos de datos

Para agregar fácilmente el comportamiento de scrollspy a tu navegación de la barra superior, agrega data-bs-spy="scroll" al elemento que deseas espiar (lo más habitual es que sea el <body>). Luego agrega el atributo data-bs-target con el id o nombre de clase del elemento principal 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>

A través de JavaScript

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

Opciones

Como las opciones se pueden pasar a través de atributos de datos 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 mayúsculas y minúsculas del nombre de la opción de “camelCase” a “kebab-case” al pasar las opciones a través de atributos de datos. 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 admiten un atributo de datos 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 de datos separados anularán los valores proporcionados en data-bs-config. Además, los atributos de datos existentes pueden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

El objeto de configuración final es el resultado fusionado de data-bs-config, data-bs- y el js object (objeto js) donde el último par clave-valor proporcionado anula a los demás.

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

Opciones obsoletas

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

Métodos

Método	Descripción
`dispose`	Destruye el scrollspy de un elemento. (Elimina los datos almacenados en el elemento DOM)
`getInstance`	Static método para obtener la instancia de scrollspy asociada con un elemento DOM.
`getOrCreateInstance`	Static método para obtener la instancia de scrollspy asociada con un elemento DOM, o para crear una nueva en caso de que no haya sido inicializada.
`refresh`	Al agregar o quitar elementos en el DOM, deberás llamar al método refresh.

Aquí tienes 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 desplazamiento cada vez que el scrollspy activa un ancla.

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

Scrollspy

¿Te gustó esta traducción?

Cómo funciona

Ejemplos

Barra de navegación

Primer encabezado

Segundo encabezado

Tercer encabezado

Cuarto encabezado

Quinto encabezado

Navegación anidada

Elemento 1

Elemento 1-1

Elemento 1-2

Elemento 2

Elemento 3

Elemento 3-1

Elemento 3-2

Grupo de lista

Elemento 1

Elemento 2

Elemento 3

Elemento 4

Enlaces simples

Elemento 1

Elemento 2

Elemento 3

Elemento 4

Elemento 5

Elementos no visibles

Uso

A través de atributos de datos

A través de JavaScript

Opciones

Métodos

Eventos