Saltar al contenido principal Saltar a la navegación de la documentación
¡Hay una versión más nueva de Bootstrap!
Ver en GitHub

Carousel

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

On this page

Cómo funciona

El carrusel es una presentación para recorrer una serie de contenidos, construido con transformaciones CSS 3D y un poco de JavaScript. Funciona con una serie de imágenes, texto o markup personalizado. También incluye soporte para controles anterior/siguiente e indicadores.

En los navegadores donde se admite la Page Visibility API, el carrusel evitará el desplazamiento cuando la página web no sea 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 los carruseles generalmente no cumplen con los estándares de accesibilidad.

Ejemplo

Los carruseles no normalizan automáticamente las dimensiones de las diapositivas. Por lo tanto, es posible que necesites usar utilidades adicionales o estilos personalizados para dimensionar adecuadamente el contenido. Aunque los carruseles admiten controles anterior/siguiente e indicadores, no son obligatorios. Añádelos y personalízalos como consideres oportuno.

La clase .active debe añadirse a una de las diapositivas de lo contrario el carrusel no será visible. Además, asegúrate de establecer un id único en el .carousel para los controles opcionales, especialmente si estás usando múltiples 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 diapositivas

Aquí hay un carrusel con solo diapositivas. Ten en cuenta la presencia de .d-block y .w-100 en las imágenes del carrusel para evitar la alineación 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

Añadiendo 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">Previous</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">Next</span>
  </button>
</div>

Con indicadores

También puedes añadir 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">Previous</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">Next</span>
  </button>
</div>

Con leyendas

Añade leyendas a tus diapositivas fácilmente con el elemento .carousel-caption dentro de cualquier .carousel-item. Pueden ocultarse fácilmente en viewports más pequeños, como se muestra a continuación, con utilidades de display opcionales. Las ocultamos inicialmente con .d-none y las volvemos a mostrar en dispositivos medianos 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>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</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>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</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>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</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">Previous</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">Next</span>
  </button>
</div>

Transición suave

Añade .carousel-fade a tu carrusel para animar las diapositivas con una transición de fundido en lugar de un desplazamiento.

<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">Previous</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">Next</span>
  </button>
</div>

Añade data-bs-interval="" a un .carousel-item para cambiar la cantidad de tiempo de retraso entre el ciclo automático hacia el 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">Previous</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">Next</span>
  </button>
</div>

Desactivar el deslizamiento táctil

Los carruseles admiten el deslizamiento izquierda/derecha en dispositivos con pantalla táctil para moverse entre las diapositivas. Esto se puede desactivar usando el atributo data-bs-touch. El ejemplo a continuación 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">Previous</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">Next</span>
  </button>
</div>

Variante oscura

Añade .carousel-dark al .carousel para obtener controles, indicadores y leyendas más oscuros. Los controles se han invertido de su relleno blanco predeterminado con la propiedad CSS filter. Las leyendas 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>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</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>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</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>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</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">Previous</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">Next</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 con estilos personalizados si estás usando el CSS compilado. Si se aplican múltiples transiciones, asegúrate de que la transición transform esté definida primero (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 data

Usa atributos data para controlar fácilmente la posición del carrusel. data-bs-slide acepta las palabras clave prev o next, que alteran la posición de la diapositiva relativa a su posición actual. Alternativamente, usa data-bs-slide-to para pasar un índice de diapositiva sin procesar al carrusel data-bs-slide-to="2", que desplaza la posición de la diapositiva a un índice particular comenzando con 0.

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

A través de JavaScript

Llama al carrusel manualmente con:

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

Opciones

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

Nombre Tipo Predeterminado 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 ciclará automáticamente.
keyboard boolean true Si el carrusel debe reaccionar a los eventos del teclado.
pause string | boolean 'hover'

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

En dispositivos con pantalla táctil, cuando se establece en 'hover', el ciclo se pausará al touchend (una vez que el usuario termine de interactuar con el carrusel) durante dos intervalos, antes de reanudarse automáticamente. Ten en cuenta que esto se añade al comportamiento del mouse anterior.
ride string | boolean false Reproduce automáticamente el carrusel después de que el usuario recorra manualmente el primer elemento. Si se establece en 'carousel', reproduce automáticamente el carrusel al cargar.
wrap boolean true Si el carrusel debe ciclar continuamente o tener paradas bruscas.
touch boolean true Si el carrusel debe admitir interacciones de deslizamiento izquierda/derecha en dispositivos con pantalla táctil.

Métodos

Métodos asíncronos y transiciones

Todos los métodos de la API son asíncronos e inician una transición. Vuelven al llamador tan pronto como se inicia la transición pero antes de que termine. Además, una llamada a un método en un componente en transición será ignorada.

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

Puedes crear una instancia de carrusel con el constructor del carrusel, por ejemplo, para inicializar con opciones adicionales y comenzar a recorrer los 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 Detiene el carrusel de recorrer los elementos.
prev Recorre hasta el elemento anterior. Vuelve al llamador antes de que se haya mostrado el elemento anterior (ej., antes de que ocurra el evento slid.bs.carousel).
next Recorre hasta el siguiente elemento. Vuelve al llamador antes de que se haya mostrado el siguiente elemento (ej., antes de que ocurra el evento slid.bs.carousel).
nextWhenVisible No recorre el carrusel al siguiente cuando la página no es visible o el carrusel o su padre no es visible. Vuelve al llamador antes de que se haya mostrado el elemento objetivo
to Recorre el carrusel a una diapositiva particular (basado en 0, similar a un array). Vuelve al llamador antes de que se haya mostrado el elemento objetivo (ej., 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 estuviera inicializada. Puedes usarlo así: bootstrap.Carousel.getOrCreateInstance(element)

Eventos

La clase carousel 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 el carrusel se está desplazando (ya sea "left" o "right").
  • relatedTarget: El elemento DOM que se está deslizando para colocarse como el elemento activo.
  • from: El índice del elemento actual
  • to: El índice del siguiente elemento

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

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

myCarousel.addEventListener('slide.bs.carousel', function () {
  // do something...
})
Traducción mantenida por Esdocu. Visita esdocu.com para ver más documentaciones traducidas.