Ir para o conteúdo principal Pular para a navegação de documentos
Check
in English

Carrossel

Um componente de apresentação de slides para percorrer elementos — imagens ou slides de texto — como um carrossel.

Nesta página

Como funciona

O carrossel é uma apresentação de slides para percorrer uma série de conteúdo, construída com transformações CSS 3D e um pouco de JavaScript. Ele funciona com uma série de imagens, texto ou marcação personalizada. Também inclui suporte para controles e indicadores anteriores/próximos.

Nos navegadores em que a API de visibilidade da página é compatível, o carrossel evitará o deslizamento quando a página da Web não estiver visível para o usuário (como quando a guia do navegador estiver inativa, a janela do navegador estiver minimizada etc.).

O efeito de animação deste componente depende da prefers-reduced-motionconsulta de mídia. Consulte a seção de movimento reduzido de nossa documentação de acessibilidade .

Esteja ciente de que os carrosséis aninhados não são suportados e os carrosséis geralmente não são compatíveis com os padrões de acessibilidade.

Exemplo

Os carrosséis não normalizam automaticamente as dimensões do slide. Como tal, pode ser necessário usar utilitários adicionais ou estilos personalizados para dimensionar o conteúdo adequadamente. Embora os carrosséis suportem controles e indicadores anteriores/seguintes, eles não são explicitamente necessários. Adicione e personalize como achar melhor.

A .activeclasse precisa ser adicionada a um dos slides , caso contrário o carrossel não ficará visível. Certifique-se também de definir um exclusivo idpara .carouselcontroles opcionais, especialmente se estiver usando vários carrosséis em uma única página. Os elementos de controle e indicador devem ter um data-bs-targetatributo (ou hrefpara links) que corresponda ao iddo .carouselelemento.

Somente slides

Aqui está um carrossel apenas com slides. Observe a presença de .d-blocke .w-100nas imagens do carrossel para evitar o alinhamento da imagem padrão do navegador.

html 
<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>

Com controles

Adicionando os controles anterior e seguinte. Recomendamos o uso <button>de elementos, mas você também pode usar <a>elementos com role="button".

html 
<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>

Com indicadores

Você também pode adicionar os indicadores ao carrossel, juntamente com os controles.

html 
<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="true">
  <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>

Com legendas

Adicione legendas aos seus slides facilmente com o .carousel-captionelemento em qualquer arquivo .carousel-item. Eles podem ser facilmente ocultados em viewports menores, conforme mostrado abaixo, com utilitários de exibição opcionais . Nós os ocultamos inicialmente com .d-nonee os trazemos de volta em dispositivos de tamanho médio com .d-md-block.

html 
<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="false">
  <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>

Crossfade

Adicione .carousel-fadeao seu carrossel para animar slides com uma transição de fade em vez de um slide. Dependendo do conteúdo do seu carrossel (por exemplo, slides somente texto), você pode querer adicionar .bg-bodyou algum CSS personalizado ao .carousel-items para um crossfading adequado.

html 
<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>

Adicione data-bs-interval=""a a .carousel-itempara alterar o tempo de atraso entre o ciclo automático para o próximo item.

html 
<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>

Desabilitar a passagem de toque

Os carrosséis suportam deslizar para a esquerda/direita em dispositivos com tela sensível ao toque para mover-se entre os slides. Isso pode ser desabilitado usando o data-bs-touchatributo. O exemplo abaixo também não inclui o data-bs-rideatributo para que ele não seja reproduzido automaticamente.

html 
<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 escura

Adicione .carousel-darkao .carouselpara controles, indicadores e legendas mais escuros. Os controles foram invertidos de seu preenchimento branco padrão com a filterpropriedade CSS. As legendas e os controles têm variáveis ​​Sass adicionais que personalizam os arquivos colore background-color.

html 
<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>

Transição personalizada

A duração da transição .carousel-itempode ser alterada com a $carousel-transition-durationvariável Sass antes de compilar ou estilos personalizados se você estiver usando o CSS compilado. Se várias transições forem aplicadas, certifique-se de que a transição de transformação seja definida primeiro (por exemplo transition: transform 2s ease, opacity .5s ease-out, ).

Sass

Variáveis

Variáveis ​​para todos os carrosséis:

$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`)

Variáveis ​​para o carrossel escuro :

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

Uso

Por atributos de dados

Use atributos de dados para controlar facilmente a posição do carrossel. data-bs-slideaceita as palavras-chave prevou next, que altera a posição do slide em relação à sua posição atual. Como alternativa, use data-bs-slide-topara passar um índice de slide bruto para o carrossel data-bs-slide-to="2", que muda a posição do slide para um índice específico começando com 0.

O data-bs-ride="carousel"atributo é usado para marcar um carrossel como animado a partir do carregamento da página. Se você não usa data-bs-ride="carousel"para inicializar seu carrossel, você mesmo deve inicializá-lo. Ele não pode ser usado em combinação com a inicialização JavaScript explícita (redundante e desnecessária) do mesmo carrossel.

Por JavaScript

Chame o carrossel manualmente com:

const carousel = new bootstrap.Carousel('#myCarousel')

Opções

Como as opções podem ser passadas por meio de atributos de dados ou JavaScript, você pode anexar um nome de opção a data-bs-, como em data-bs-animation="{value}". Certifique-se de alterar o tipo de caso do nome da opção de “ camelCase ” para “ kebab-case ” ao passar as opções por meio de atributos de dados. Por exemplo, use data-bs-custom-class="beautifier"em vez de data-bs-customClass="beautifier".

A partir do Bootstrap 5.2.0, todos os componentes oferecem suporte a um atributo experimental de dados reservados data-bs-configque pode abrigar a configuração simples do componente como uma string JSON. Quando um elemento tem atributos data-bs-config='{"delay":0, "title":123}'e data-bs-title="456", o valor final titleserá 456e os atributos de dados separados substituirão os valores fornecidos em data-bs-config. Além disso, os atributos de dados existentes podem hospedar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Nome Modelo Predefinição Descrição
interval número 5000 A quantidade de tempo de atraso entre o ciclo automático de um item.
keyboard boleano true Se o carrossel deve reagir a eventos de teclado.
pause string, booleano "hover" Se definido como "hover", pausa o ciclo do carrossel ligado mouseentere retoma o ciclo do carrossel ligado mouseleave. Se definido como false, passar o mouse sobre o carrossel não o pausará. Em dispositivos habilitados para toque, quando definido como "hover", o ciclismo fará uma pausa touchend(quando o usuário terminar de interagir com o carrossel) por dois intervalos, antes de retomar automaticamente. Isso é um acréscimo ao comportamento do mouse.
ride string, booleano false Se definido como true, reproduz automaticamente o carrossel depois que o usuário alternar manualmente o primeiro item. Se definido como "carousel", reproduz automaticamente o carrossel ao carregar.
touch boleano true Se o carrossel deve suportar interações de deslizamento para a esquerda/direita em dispositivos com tela sensível ao toque.
wrap boleano true Se o carrossel deve circular continuamente ou ter paradas bruscas.

Métodos

Métodos e transições assíncronas

Todos os métodos de API são assíncronos e iniciam uma transição . Eles retornam ao chamador assim que a transição é iniciada, mas antes que ela termine . Além disso, uma chamada de método em um componente de transição será ignorada .

Consulte nossa documentação JavaScript para obter mais informações .

Você pode criar uma instância de carrossel com o construtor de carrossel, por exemplo, para inicializar com opções adicionais e começar a percorrer os itens:

const myCarouselElement = document.querySelector('#myCarousel')
const carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000,
  wrap: false
})
Método Descrição
cycle Percorre os itens do carrossel da esquerda para a direita.
dispose Destrói o carrossel de um elemento. (Remove os dados armazenados no elemento DOM)
getInstance Método estático que permite obter a instância do carrossel associada a um elemento DOM, você pode usá-lo assim: bootstrap.Carousel.getInstance(element).
getOrCreateInstance Método estático que retorna uma instância de carrossel associada a um elemento DOM ou cria uma nova caso não tenha sido inicializada. Você pode usar assim: bootstrap.Carousel.getOrCreateInstance(element).
next Alterna para o próximo item. Retorna ao chamador antes que o próximo item seja mostrado (por exemplo, antes que o slid.bs.carouselevento ocorra).
nextWhenVisible Não mude o carrossel para o próximo quando a página não estiver visível ou o carrossel ou seu pai não estiver visível. Retorna ao chamador antes que o item de destino seja mostrado .
pause Interrompe o carrossel de percorrer os itens.
prev Volta ao item anterior. Retorna ao chamador antes que o item anterior tenha sido mostrado (por exemplo, antes que o slid.bs.carouselevento ocorra).
to Alterna o carrossel para um quadro específico (baseado em 0, semelhante a uma matriz). Retorna ao chamador antes que o item de destino seja mostrado (por exemplo, antes que o slid.bs.carouselevento ocorra).

Eventos

A classe carrossel do Bootstrap expõe dois eventos para conectar-se à funcionalidade do carrossel. Ambos os eventos têm as seguintes propriedades adicionais:

  • direction: A direção na qual o carrossel está deslizando (ou "left"ou "right").
  • relatedTarget: o elemento DOM que está sendo posicionado como o item ativo.
  • from: O índice do item atual
  • to: O índice do próximo item

Todos os eventos de carrossel são disparados no próprio carrossel (ou seja, no <div class="carousel">).

Tipo de evento Descrição
slid.bs.carousel Acionado quando o carrossel conclui sua transição de slides.
slide.bs.carousel Dispara imediatamente quando o slidemétodo de instância é invocado. 
const myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', event => {
  // do something...
})