Carousel
Un componente de presentación para recorrer elementos—imágenes o diapositivas de texto—como un carrusel.
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.
-
Por razones de rendimiento, los carruseles deben inicializarse manualmente usando el método constructor del carrusel. Sin inicialización, algunos de los escuchadores de eventos (específicamente, los eventos necesarios para soporte táctil/deslizamiento) no se registrarán hasta que un usuario active explícitamente un control o indicador.
La única excepción son los carruseles con reproducción automática con el atributo
data-bs-ride="carousel", ya que estos se inicializan automáticamente al cargar la página. Si usas carruseles con reproducción automática con el atributo data, no inicialices explícitamente los mismos carruseles con el método constructor. -
No se soportan carruseles anidados. También debes tener en cuenta que los carruseles en general pueden causar a menudo problemas de usabilidad y accesibilidad.
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.
Ejemplos básicos
Aquí hay un ejemplo básico de un carrusel con tres diapositivas. Ten en cuenta los
controles anterior/siguiente. Recomendamos usar elementos <button>, pero también puedes
usar elementos <a> con role="button".
<div id="carouselExample" class="carousel slide">
<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="#carouselExample" 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="#carouselExample" data-bs-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="visually-hidden">Next</span>
</button>
</div>
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.
Debes añadir la clase .active a una de las diapositivas, de
lo contrario el carrusel no será visible. También asegúrate de establecer un id único en el
.carousel para los controles opcionales, especialmente si usas 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.
Indicadores
Puedes añadir indicadores al carrusel, junto con los controles anterior/siguiente. Los indicadores permiten a los usuarios saltar directamente a una diapositiva en particular.
<div id="carouselExampleIndicators" class="carousel slide">
<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>
Subtítulos
Puedes añadir subtítulos a tus diapositivas 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 utilidades de display opcionales. Los
ocultamos inicialmente con .d-none y los volvemos a mostrar en dispositivos medianos con
.d-md-block.
<div id="carouselExampleCaptions" class="carousel slide">
<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 deslizamiento. Dependiendo del contenido de tu carrusel (p. ej.,
diapositivas solo con texto), puede que quieras añadir .bg-body o algo de CSS personalizado a los
.carousel-item para un fundido cruzado correcto.
<div id="carouselExampleFade" class="carousel slide carousel-fade">
<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>
Carruseles con reproducción automática
Puedes hacer que tus carruseles se reproduzcan automáticamente al cargar la página
estableciendo la opción ride en carousel. Los carruseles con reproducción automática
se pausan automáticamente al pasar el ratón por encima. Este comportamiento se puede controlar con la opción
pause. En los navegadores que soportan la Page
Visibility API, el carrusel dejará de ciclar cuando la página web no sea visible para el usuario (como
cuando la pestaña del navegador está inactiva, o cuando la ventana del navegador está minimizada).
Por razones de accesibilidad, recomendamos evitar el uso de carruseles con reproducción automática. Si tu página incluye un carrusel con reproducción automática, recomendamos proporcionar un botón o control adicional para pausar/detener explícitamente el carrusel.
Ver WCAG 2.2 Criterio de éxito 2.2.2 Pausar, Detener, Ocultar.
<div id="carouselExampleAutoplaying" 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="#carouselExampleAutoplaying" 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="#carouselExampleAutoplaying" data-bs-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="visually-hidden">Next</span>
</button>
</div>
Cuando la opción ride se establece en true, en lugar de
carousel, el carrusel no comenzará a ciclar automáticamente al cargar la página. En su lugar,
solo comenzará después de la primera interacción del usuario.
<div id="carouselExampleRide" class="carousel slide" data-bs-ride="true">
<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="#carouselExampleRide" 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="#carouselExampleRide" data-bs-slide="next">
<span class="carousel-control-next-icon" aria-hidden="true"></span>
<span class="visually-hidden">Next</span>
</button>
</div>
Intervalo individual de
.carousel-item
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>
Carruseles con reproducción automática sin controles
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>
Desactivar deslizamiento táctil
Los carruseles soportan deslizamiento izquierda/derecha en dispositivos táctiles para
moverse entre diapositivas. Esto se puede desactivar estableciendo la opción touch en
false.
<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="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
Obsoleto en v5.3.0Añade .carousel-dark al .carousel para obtener controles,
indicadores y subtítulos más oscuros. Los controles se invierten comparados con su relleno blanco por defecto
con la propiedad CSS filter. Los subtítulos y controles tienen variables Sass adicionales que
personalizan el color y el background-color.
¡Atención! Las variantes oscuras para componentes quedaron obsoletas en
v5.3.0 con la introducción de los modos de color.
En lugar de añadir .carousel-dark, establece data-bs-theme="dark" en el elemento
raíz, un contenedor
padre, o el componente mismo.
<div id="carouselExampleDark" class="carousel carousel-dark slide">
<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 de
transformación esté definida primero (p. ej.
transition: transform 2s ease, opacity .5s ease-out).
CSS
Variables Sass
Variables para todos los carruseles:
$carousel-control-color: $white;
$carousel-control-width: 15%;
$carousel-control-opacity: .5;
$carousel-control-hover-opacity: .9;
$carousel-control-transition: opacity .15s ease;
$carousel-control-icon-filter: null;
$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 0'/></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-.708'/></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`)
Variables para el carrusel oscuro:
$carousel-dark-indicator-active-bg: $black; // Deprecated in v5.3.4
$carousel-dark-caption-color: $black; // Deprecated in v5.3.4
$carousel-dark-control-icon-filter: invert(1) grayscale(100); // Deprecated in v5.3.4
Uso
Vía 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.
Vía JavaScript
Llama al carrusel manualmente con:
const carousel = new bootstrap.Carousel('#myCarousel')
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 |
|---|---|---|---|
interval |
number | 5000 |
La cantidad de tiempo de espera entre ciclos automáticos de un elemento. |
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 en
mouseenter y lo reanuda en mouseleave. Si se establece en
false, pasar el ratón por encima del carrusel no lo pausará. En dispositivos táctiles,
cuando se establece en "hover", el ciclo se pausará en touchend (una vez que
el usuario termine de interactuar con el carrusel) durante dos intervalos, antes de reanudarse
automáticamente. Esto es adicional al comportamiento del ratón. |
ride |
string, boolean | false |
Si se establece en true, reproduce automáticamente el carrusel
después de que el usuario cicla manualmente el primer elemento. Si se establece en
"carousel", reproduce automáticamente el carrusel al cargar. |
touch |
boolean | true |
Si el carrusel debe admitir interacciones de deslizamiento izquierda/derecha en dispositivos con pantalla táctil. |
wrap |
boolean | true |
Si el carrusel debe ciclar continuamente o tener paradas bruscas. |
Métodos
Todos los métodos de la API son asíncronos e inician una transición. Vuelven al llamador tan pronto como la transición comienza, pero antes de que termine. Además, una llamada a un método en un componente en transición será ignorada. Obtén más información en nuestra documentación de JavaScript.
Puedes crear una instancia de carrusel con el constructor del carrusel y pasar opciones
adicionales. Por ejemplo, para inicializar manualmente un carrusel con reproducción automática (asumiendo que
no estás usando el atributo data-bs-ride="carousel" en el markup mismo) con un intervalo
específico y con soporte táctil desactivado, puedes usar:
const myCarouselElement = document.querySelector('#myCarousel')
const carousel = new bootstrap.Carousel(myCarouselElement, {
interval: 2000,
touch: false
})
| Método | Descripción |
|---|---|
cycle |
Comienza a ciclar a través de los elementos del carrusel de izquierda a derecha. |
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). |
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 ciclar el carrusel al siguiente cuando la página, el carrusel, o el contenedor padre del carrusel no sean visibles. Vuelve al llamador antes de que el elemento objetivo haya sido mostrado. |
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). |
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). |
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 actualto: 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 |
|---|---|
slid.bs.carousel |
Se dispara cuando el carrusel ha completado su transición de diapositiva. |
slide.bs.carousel |
Se dispara inmediatamente cuando se invoca el método de instancia
slide. |
const myCarousel = document.getElementById('myCarousel')
myCarousel.addEventListener('slide.bs.carousel', event => {
// do something...
})