Ver en GitHub

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 tiene algunos requisitos para funcionar correctamente:

Debe usarse en un componente nav de Bootstrap o en un grupo de lista.
Scrollspy requiere position: relative; en el elemento que estás espiando, usualmente el <body>.
Los anclajes (<a>) son obligatorios y deben apuntar a un elemento con ese id.

Cuando se implementa correctamente, tu nav o grupo de lista se actualizará en consecuencia, moviendo la clase .active de un elemento al siguiente según sus objetivos asociados.

Contenedores desplazables y acceso por teclado

Si estás creando un contenedor desplazable (distinto al <body>), asegúrate de tener un height establecido y overflow-y: scroll; aplicado—junto con un tabindex="0" para garantizar el acceso por teclado.

Desplaza el área debajo del navbar y observa cómo cambia la clase activa. Los elementos del dropdown también se resaltarán.

Primer encabezado

Este es algún 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, el enlace de navegación correspondiente se resalta. 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 navbar-light bg-light px-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-offset="0" class="scrollspy-example" 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>

Ejemplo con 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

Elemento 1-1

Elemento 1-2

Elemento 2

Elemento 3

Elemento 3-1

Elemento 3-2

<nav id="navbar-example3" class="navbar navbar-light bg-light flex-column align-items-stretch p-3">
  <a class="navbar-brand" href="#">Navbar</a>
  <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 data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-offset="0" tabindex="0">
  <h4 id="item-1">Item 1</h4>
  <p>...</p>
  <h5 id="item-1-1">Item 1-1</h5>
  <p>...</p>
  <h5 id="item-1-2">Item 1-2</h5>
  <p>...</p>
  <h4 id="item-2">Item 2</h4>
  <p>...</p>
  <h4 id="item-3">Item 3</h4>
  <p>...</p>
  <h5 id="item-3-1">Item 3-1</h5>
  <p>...</p>
  <h5 id="item-3-2">Item 3-2</h5>
  <p>...</p>
</div>

Ejemplo con list-group

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 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 data-bs-spy="scroll" data-bs-target="#list-example" data-bs-offset="0" 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>

Uso

A través de atributos data

Para agregar fácilmente el comportamiento scrollspy a la navegación de tu barra superior, agrega data-bs-spy="scroll" al elemento que quieres espiar (lo más típico sería el <body>). Luego agrega el atributo data-bs-target con el ID o clase del elemento padre de cualquier componente .nav de Bootstrap.

body {
  position: relative;
}

<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

Después de agregar position: relative; en tu CSS, llama al scrollspy vía JavaScript:

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

Se requieren destinos de ID resolubles

Los enlaces del navbar deben tener destinos de id resolubles. Por ejemplo, un <a href="#home">home</a> debe corresponder a algo en el DOM como <div id="home"></div>.

Elementos destino no visibles ignorados

Los elementos destino que no sean visibles serán ignorados y sus elementos de navegación correspondientes nunca se resaltarán.

Métodos

refresh

Cuando uses scrollspy junto con la adición o eliminación de elementos del DOM, necesitarás llamar al método refresh así:

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

dispose

Destruye el scrollspy de un elemento. (Elimina los datos almacenados en el elemento del DOM)

getInstance

Método estático que te permite obtener la instancia de scrollspy asociada a un elemento del DOM

var scrollSpyContentEl = document.getElementById('content')
var scrollSpy = bootstrap.ScrollSpy.getInstance(scrollSpyContentEl) // Returns a Bootstrap scrollspy instance

getOrCreateInstance

Método estático que te permite obtener la instancia de scrollspy asociada a un elemento del DOM, o crear una nueva en caso de que no haya sido inicializada

var scrollSpyContentEl = document.getElementById('content')
var scrollSpy = bootstrap.ScrollSpy.getOrCreateInstance(scrollSpyContentEl) // Returns a Bootstrap scrollspy instance

Opciones

Las opciones se pueden pasar vía atributos data o JavaScript. Para los atributos data, agrega el nombre de la opción a data-bs-, como en data-bs-offset="".

Nombre	Tipo	Predeterminado	Descripción
`offset`	number	`10`	Píxeles de desplazamiento desde la parte superior al calcular la posición del scroll.
`method`	string	`auto`	Encuentra en qué sección se encuentra el elemento espiado. `auto` elegirá el mejor método para obtener las coordenadas de desplazamiento. `offset` usará el método `Element.getBoundingClientRect()` para obtener las coordenadas de desplazamiento. `position` usará las propiedades `HTMLElement.offsetTop` y `HTMLElement.offsetLeft` para obtener las coordenadas de desplazamiento.
`target`	string \| objeto jQuery \| elemento del DOM		Especifica el elemento al que aplicar el plugin Scrollspy.

Eventos

Tipo de evento	Descripción
`activate.bs.scrollspy`	Este evento se dispara en el elemento de desplazamiento cada vez que un nuevo elemento se activa mediante el scrollspy.

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

Scrollspy

Cómo funciona

Contenedores desplazables y acceso por teclado

Ejemplo en navbar

Primer encabezado

Segundo encabezado

Tercer encabezado

Cuarto encabezado

Quinto encabezado

Ejemplo con nav anidado

Elemento 1

Elemento 1-1

Elemento 1-2

Elemento 2

Elemento 3

Elemento 3-1

Elemento 3-2

Ejemplo con list-group

Elemento 1

Elemento 2

Elemento 3

Elemento 4

Uso

A través de atributos data

A través de JavaScript

Se requieren destinos de ID resolubles

Elementos destino no visibles ignorados

Métodos

refresh

dispose

getInstance

getOrCreateInstance

Opciones

Eventos