Carousel

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O br-carousel mostra uma sequência de slides, um por vez, com botões de anterior e próximo e indicadores de posição.

Coloque cada slide em um br-carousel-page e dê um nome ao carrossel com aria-label.

<br-carousel aria-label="Destaques">
  <br-carousel-page>
    <img src="/imagens/campanha.jpg" alt="Campanha de vacinação" />
  </br-carousel-page>
  <br-carousel-page>
    <p>Atualize seu cadastro até 30 de junho.</p>
  </br-carousel-page>
</br-carousel>

Para ouvir a troca de slide, use brCarouselPageChange; detail.activePage começa em 1.

Quando usar

• Imagens ou avisos com a mesma importância, em espaço limitado.

Quando evitar

• Informação essencial para a tarefa: mostre tudo de uma vez, por exemplo em uma grade de br-card.
• Etapas de um formulário: use br-wizard ou br-step.

Consulte as diretrizes de design do GovBR.

Exemplo(s)

Exemplos

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Propriedades

ariaLabel

Atributo	aria-label
Descrição	Rótulo acessível do carrossel. Não deve conter a palavra "carrossel" (W3C APG). Atribuído ao aria-label do container raiz.
Tipo	string
Valor padrão	---

autoPlay Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	auto-play
Depreciação	Use autoplay.
Descrição	Habilita reprodução automática. Pausa em hover e foco (W3C). Ativa o loop circular automaticamente. Não recomendado em dispositivos móveis.
Tipo	boolean
Valor padrão	false

autoplay

Atributo	autoplay
Descrição	Habilita reprodução automática. Quando informada, tem precedência sobre autoPlay.
Tipo	boolean
Valor padrão	---

circular

Atributo	circular
Descrição	Habilita navegação circular. Quando informada, tem precedência sobre isCircular.
Tipo	boolean
Valor padrão	---

colorMode

Atributo	color-mode
Descrição	Aplica esquema de cores escuro ao componente.
Tipo	"dark"
Valor padrão	---

customId

Atributo	custom-id
Descrição	Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId().
Tipo	string
Valor padrão	generateUniqueId()

direction

Atributo	direction
Descrição	Direção de navegação automática do carrossel. - left: retrocede (vai para o slide anterior). - right: avança (vai para o próximo slide). Só tem efeito quando autoPlay=true.
Tipo	"left" | "right"
Valor padrão	'right'

height

Atributo	height
Descrição	Altura do carrossel. Aceita qualquer valor CSS válido para height (ex.: 400px, 50vh).
Tipo	string
Valor padrão	---

imageFit

Atributo	image-fit
Descrição	Ajuste aplicado a imagens filhas diretas de br-carousel-page.
Tipo	"contain" | "cover" | "fill" | "none" | "scale-down"
Valor padrão	'cover'

indicatorPosition

Atributo	indicator-position
Descrição	Posição do indicador de páginas em relação ao palco. Ignorada quando indicatorType="none". - outside: indicador fica abaixo do palco. - inside: indicador fica sobreposto ao conteúdo.
Tipo	"inside" | "outside"
Valor padrão	'outside'

indicatorType

Atributo	indicator-type
Descrição	Define o tipo de indicador de páginas renderizado. - simple: dots usando br-step em modo controller. - textual: texto "X/N" com aria-live. - none: sem indicador.
Tipo	"none" | "simple" | "textual"
Valor padrão	'simple'

interval

Atributo	interval
Descrição	Intervalo em milissegundos entre cada avanço automático. Deve ser um inteiro maior que 0; valores inválidos usam 5000. Só tem efeito quando autoPlay=true.
Tipo	number
Valor padrão	5000

isCircular Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-circular
Depreciação	Use circular.
Descrição	Habilita a navegação circular entre os slides. Quando true, os botões "Anterior" e "Próximo" permanecem sempre habilitados: avançar a partir do último slide retorna ao primeiro, e retroceder a partir do primeiro leva ao último. Se autoPlay estiver ativado, o comportamento circular será aplicado automaticamente, independentemente deste valor.
Tipo	boolean
Valor padrão	false

maxWidth

Atributo	max-width
Descrição	Largura máxima do carrossel. Quando definido, o componente é centralizado horizontalmente. Aceita qualquer valor CSS válido para max-width (ex.: 800px, 64rem).
Tipo	string
Valor padrão	---

minHeight

Atributo	min-height
Descrição	Altura mínima do palco do carrossel. Aceita qualquer valor CSS válido para min-height (ex.: 400px, 50vh).
Tipo	string
Valor padrão	---

mobileNav

Atributo	mobile-nav
Descrição	Exibe botões de navegação em dispositivos móveis. Por padrão os botões são ocultados no breakpoint sm.
Tipo	boolean
Valor padrão	false

navPosition

Atributo	nav-position
Descrição	Posição dos botões de navegação (prev/next) em relação ao palco. - outside: botões ficam nas laterais externas ao palco. - inside: botões ficam sobrepostos dentro do palco, ocupando toda a altura.
Tipo	"inside" | "outside"
Valor padrão	'outside'

Slots

Nome	Descrição
"default"	Slot para os slides do carrossel. Aceita exclusivamente elementos br-carousel-page.

Eventos

Evento	Descrição	Depreciação	Propagação
brCarouselAutoplayPause	Evento emitido quando a reprodução automática é pausada.	---	true
brCarouselAutoplayStart	Evento emitido quando a reprodução automática começa.	---	true
brCarouselPageChange	Evento emitido quando o slide ativo muda.	---	true
brDidAutoPlayPause	Emitido quando a reprodução automática é pausada.	---	true
brDidAutoPlayStart	Emitido quando a reprodução automática é iniciada ou retomada.	---	true
brDidPageChange	Emitido quando o slide ativo muda. Disparado por clique nos botões de navegação, clique no indicador de step, gesto swipe (apenas em mobile, breakpoint < 576px) ou avanço automático. activePage é 1-based: o primeiro slide emite 1, o segundo 2, e assim por diante.	---	true

Métodos

getActivePage

Descrição	Retorna o número do slide atualmente ativo (1 = primeiro slide, 2 = segundo, …).
Assinatura	getActivePage() => Promise<number>
Parâmetros	---

getIsPlaying

Descrição	Retorna true se a reprodução automática está ativa no momento.
Assinatura	getIsPlaying() => Promise<boolean>
Parâmetros	---

goToPage

Descrição	Navega para o slide de número index (1 = primeiro slide, 2 = segundo, …). Valores fora do intervalo válido são ignorados.
Assinatura	goToPage(index: number) => Promise<void>
Parâmetros	index:

nextPage

Descrição	Avança para o próximo slide. Respeita a prop isCircular (ou ativo automaticamente com autoPlay).
Assinatura	nextPage() => Promise<void>
Parâmetros	---

pause

Descrição	Pausa a reprodução automática programaticamente.
Assinatura	pause() => Promise<void>
Parâmetros	---

play

Descrição	Inicia ou retoma a reprodução automática programaticamente.
Assinatura	play() => Promise<void>
Parâmetros	---

previousPage

Descrição	Retorna ao slide anterior. Respeita a prop isCircular (ou ativo automaticamente com autoPlay).
Assinatura	previousPage() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"container"	Elemento raiz do carrossel. Recebe role="region" e aria-roledescription="carousel".
"indicator"	Wrapper do indicador de páginas. - Quando indicatorType="simple": renderiza br-step em mode="tablist". - Quando indicatorType="textual": renderiza um span[aria-live] com "X/N".
"nav-next"	Wrapper do botão de navegação para o próximo slide.
"nav-prev"	Wrapper do botão de navegação para o slide anterior.
"play-button"	Wrapper do botão de play/pause. Presente apenas quando autoPlay=true.
"stage"	Área do palco que contém os slides. Recebe aria-live e aria-atomic.

Acessibilidade

Dê um nome ao carrossel com aria-label. Cada slide é anunciado como "slide", e a troca de slide é anunciada para leitores de tela, exceto durante a rotação automática.

Teclado

• Nos indicadores, as setas, Home e End trocam o slide.
• Os botões de anterior e próximo têm rótulos próprios.

Rotação automática

• Prefira deixar autoplay desligado. Não coloque informação essencial apenas em slides que trocam sozinhos.
• Com autoplay, o carrossel exibe um botão de pausar e para de girar quando recebe foco ou o mouse passa sobre ele.
• Com indicator-type="textual", o progresso aparece como texto ("2/5").

A transição e a rotação automática respeitam a preferência do sistema por menos movimento.

Dependências

Subcomponentes

• br-carousel-page

Depende de

• br-button
• br-icon
• br-step
• br-step-item

Gráfico