Skip to main content Skip to docs navigation
En GitHub

Carousel

Un componente de presentación de diapositivas para recorrer elementos (imágenes o diapositivas de texto) como un carrusel.

En esta página

El carrusel es una presentación de diapositivas para recorrer una serie de contenido, creado con transformaciones CSS 3D y un poco de JavaScript. Funciona con una serie de imágenes, texto o marcas personalizadas. También incluye soporte para controles e indicadores anteriores/siguientes.

En los navegadores donde la API de visibilidad de página es compatible, el carrusel evitará el deslizamiento cuando la página web no esté visible para el usuario (como cuando la pestaña del navegador está inactiva, la ventana del navegador está minimizada, etc.).

El efecto de animación de este componente depende de la media query prefers-reduced-motion. Consulta la sección de movimiento reducido de nuestra documentación de accesibilidad.

Ten en cuenta que los carruseles anidados no son compatibles y, por lo general, los carruseles no cumplen con los estándares de accesibilidad.

Ejemplo

Los carruseles no normalizan automáticamente las dimensiones de las diapositivas. Como tal, es posible que debas usar utilidades adicionales o estilos personalizados para dimensionar el contenido de manera adecuada. Si bien los carruseles admiten controles e indicadores anteriores/siguientes, no se requieren explícitamente. Agrega y personaliza como mejor te parezca.

La clase .active debe agregarse a una de las diapositivas, de lo contrario, el carrusel no será visible. También asegúrate de configurar un id único en el .carrusel para controles opcionales, especialmente si estás utilizando varios carruseles en una sola página. Los elementos de control e indicadores deben tener un atributo data-bs-target (o href para enlaces) que coincida con el id del elemento .carousel.

Solo slides

Aquí hay un carrusel solo con diapositivas. Ten en cuenta la presencia de .d-block y .w-100 en las imágenes del carrusel para evitar la alineación de imágenes predeterminada del navegador. 

<div id="carouselExampleSlidesOnly" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
</div>

Con controles

Agreguemos los controles anterior y siguiente. Recomendamos usar elementos <button>, pero también puedes usar elementos <a> con role="button".

<div id="carouselExampleControls" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControls" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Anterior</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControls" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Siguiente</span>
  </button>
</div>

Con indicadores

También puedes agregar los indicadores al carrusel, junto con los controles.

<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Anterior</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Siguiente</span>
  </button>
</div>

Con subtítulos

Agrega subtítulos a tus diapositivas fácilmente con el elemento .carousel-caption dentro de cualquier .carousel-item. Se pueden ocultar fácilmente en viewports más pequeños, como se muestra a continuación, con las utilidades de visualización opcionales. Los ocultamos inicialmente con .d-none y los recuperamos en dispositivos de tamaño mediano con .d-md-block. 

<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Etiqueta de la primera diapositiva</h5>
        <p>Algún contenido placeholder representativo para la primera diapositiva.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Etiqueta de la segunda diapositiva</h5>
        <p>Algún contenido placeholder representativo para la segunda diapositiva.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Etiqueta de la tercera diapositiva</h5>
        <p>Algún contenido placeholder representativo para la tercera diapositiva.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Anterior</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Siguiente</span>
  </button>
</div>

Transición de fundido

Agrega .carousel-fade a tu carrusel para animar las diapositivas con una transición de fundido en lugar de una diapositiva. Dependiendo del contenido de tu carrusel (por ejemplo, diapositivas de solo texto), es posible que desees agregar .bg-body o algún CSS personalizado a los .carousel-items para un fundido cruzado adecuado. 

<div id="carouselExampleFade" class="carousel slide carousel-fade" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Anterior</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Siguiente</span>
  </button>
</div>

Agrega data-bs-interval="" a .carousel-item para cambiar la cantidad de tiempo de retraso entre el ciclo automático al siguiente elemento.

<div id="carouselExampleInterval" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Anterior</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Siguiente</span>
  </button>
</div>

Desactivar deslizamiento táctil

Los carruseles admiten deslizar hacia la izquierda o hacia la derecha en dispositivos con pantalla táctil para moverse entre diapositivas. Esto se puede deshabilitar usando el atributo data-bs-touch. El siguiente ejemplo tampoco incluye el atributo data-bs-ride y tiene data-bs-interval="false", por lo que no se reproduce automáticamente. 

<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="false" data-bs-interval="false">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Anterior</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Siguiente</span>
  </button>
</div>

Variante dark

Agrega .carousel-dark a .carousel para obtener controles, indicadores y subtítulos más oscuros. Los controles se han invertido de su relleno blanco predeterminado con la propiedad CSS filter. Los subtítulos y los controles tienen variables Sass adicionales que personalizan el color y el background-color. 

<div id="carouselExampleDark" class="carousel carousel-dark slide" data-bs-ride="carousel">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Etiqueta de la primera diapositiva</h5>
        <p>Algún contenido placeholder representativo para la primera diapositiva.</p>
      </div>
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Etiqueta de la segunda diapositiva</h5>
        <p>Algún contenido placeholder representativo para la segunda diapositiva.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Etiqueta de la tercera diapositiva</h5>
        <p>Algún contenido placeholder representativo para la tercera diapositiva.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Anterior</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Siguiente</span>
  </button>
</div>

Transición personalizada

La duración de la transición de .carousel-item se puede cambiar con la variable Sass $carousel-transition-duration antes de compilar o estilos personalizados si estás utilizando el CSS compilado. Si se aplican varias transiciones, asegúrate de definir primero la transición de transformación (p. ej., transition: transform 2s ease, opacity .5s ease-out).

Sass

Variables

$carousel-control-color:             $white;
$carousel-control-width:             15%;
$carousel-control-opacity:           .5;
$carousel-control-hover-opacity:     .9;
$carousel-control-transition:        opacity .15s ease;

$carousel-indicator-width:           30px;
$carousel-indicator-height:          3px;
$carousel-indicator-hit-area-height: 10px;
$carousel-indicator-spacer:          3px;
$carousel-indicator-opacity:         .5;
$carousel-indicator-active-bg:       $white;
$carousel-indicator-active-opacity:  1;
$carousel-indicator-transition:      opacity .6s ease;

$carousel-caption-width:             70%;
$carousel-caption-color:             $white;
$carousel-caption-padding-y:         1.25rem;
$carousel-caption-spacer:            1.25rem;

$carousel-control-icon-width:        2rem;

$carousel-control-prev-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z'/></svg>");
$carousel-control-next-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z'/></svg>");

$carousel-transition-duration:       .6s;
$carousel-transition:                transform $carousel-transition-duration ease-in-out; // Define transform transition first if using multiple transitions (e.g., `transform 2s ease, opacity .5s ease-out`)

$carousel-dark-indicator-active-bg:  $black;
$carousel-dark-caption-color:        $black;
$carousel-dark-control-icon-filter:  invert(1) grayscale(100);

Uso

A través de atributos de datos

Utiliza atributos de datos para controlar fácilmente la posición del carrusel. data-bs-slide acepta las palabras clave prev o next, que altera la posición de la diapositiva en relación con su posición actual. Alternativamente, usa data-bs-slide-to para pasar un índice de diapositiva al carrusel data-bs-slide-to="2", que cambia la posición de la diapositiva a un índice particular que comienza con 0.

El atributo data-bs-ride="carousel" se utiliza para marcar un carrusel como animado a partir de la carga de la página. Si no usas data-bs-ride="carousel" para inicializar tu carrusel, debes inicializarlo tú mismo. No se puede usar en combinación con la inicialización explícita de JavaScript (redundante e innecesaria) del mismo carrusel.

A través de JavaScript

Llama al carousel manualmente con:

var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel)

Opciones

Las opciones se pueden pasar a través de atributos de datos o JavaScript. Para los atributos de datos, agrega el nombre de la opción a data-bs-, como en data-bs-interval="".

Nombre Tipo Por defecto Descripción
interval number 5000 La cantidad de tiempo de retraso entre el ciclo automático de un elemento. Si es false, el carrusel no realizará un ciclo automáticamente.
keyboard boolean true Si el carrusel debe reaccionar a los eventos del teclado.
pause string | boolean 'hover'

Si se establece en 'hover', detiene el ciclo del carrusel en mouseenter y reanuda el ciclo del carrusel en mouseleave. Si se establece en false, pasar el cursor sobre el carrusel no lo pausará.

En dispositivos táctiles, cuando se establece en 'hover', el ciclo se detendrá en touchend durante dos intervalos (una vez que el usuario termine de interactuar con el carrusel), antes reanudarse automáticamente. Ten en cuenta que esto se suma al comportamiento del mouse anterior.

ride string | boolean false Reproduce automáticamente el carrusel después de que el usuario cicla manualmente el primer elemento. Si se establece en 'carousel', se reproduce automáticamente el carrusel al cargar.
wrap boolean true Si el carrusel debe circular continuamente o tener paradas bruscas.
touch boolean true Si el carrusel debe admitir interacciones de deslizamiento hacia la izquierda/derecha en dispositivos con pantalla táctil.

Métodos

Transiciones y métodos asíncronos

Todos los métodos de la API son asincrónicos e inician una transition. Regresan al lugar donde se realizó la llamada tan pronto como se inicia la transición, pero antes de que finalice. Además, se ignorará una llamada de método en un componente en medio de una transición.

Consulte nuestra documentación de JavaScript para obtener más información.

Puedes crear una instancia de carrusel con el constructor de carrusel, por ejemplo, para inicializar con opciones adicionales y comenzar a recorrer elementos:

var myCarousel = document.querySelector('#myCarousel')
var carousel = new bootstrap.Carousel(myCarousel, {
  interval: 2000,
  wrap: false
})
Método Descripción
cycle Recorre los elementos del carrusel de izquierda a derecha.
pause Evita que el carrusel recorra los elementos.
prev Cicla al elemento anterior. Vuelve al punto de la llamada antes de que se haya mostrado el elemento anterior (por ejemplo, antes de que ocurra el evento slid.bs.carousel).
next Cicla al siguiente elemento. Regresa al punto de la llamada antes de que se muestre el siguiente elemento (por ejemplo, antes de que ocurra el evento slid.bs.carousel).
nextWhenVisible No cambia el carrusel al siguiente cuando la página no esté visible o el carrusel o su elemento padre no estén visibles. Vuelve al punto de la llamada antes de que se haya mostrado el elemento de destino
to Cicla el carrusel a un frame particular (iniciando en 0, similar a una matriz). Regresa al punto de la llamada antes de que se haya mostrado el elemento de destino (por ejemplo, antes de que ocurra el evento slid.bs.carousel).
dispose Destruye el carrusel de un elemento. (Elimina los datos almacenados en el elemento DOM)
getInstance Método estático que te permite obtener la instancia de carrusel asociada a un elemento DOM, puedes usarlo así: bootstrap.Carousel.getInstance(element)
getOrCreateInstance Método estático que devuelve una instancia de carrusel asociada a un elemento DOM o crea una nueva en caso de que no se haya inicializado. Puedes usarlo así: bootstrap.Carousel.getOrCreateInstance(element)

Eventos

La clase de carrusel de Bootstrap expone dos eventos para conectarse a la funcionalidad del carrusel. Ambos eventos tienen las siguientes propiedades adicionales:

  • direction: La dirección en la que se desliza el carrusel (ya sea "left" o "right").
  • relatedTarget: el elemento DOM que se desliza en su lugar como el elemento activo.
  • from: el índice del elemento actual
  • to: el índice del siguiente elemento

Todos los eventos del carrusel se activan en el propio carrusel (es decir, en <div class="carousel">).

Tipo de evento Descripción
slide.bs.carousel Se activa inmediatamente cuando se invoca el método de instancia slide.
slid.bs.carousel Se activa cuando el carrusel ha completado su transición de diapositivas. 
var myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', function () {
  // hacer algo...
})