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 componente br-carousel é o contêiner de apresentação rotativa e sequencial de conteúdos do GovBR-DS, desenvolvido para exibir múltiplos slides em um espaço delimitado onde apenas um item (ou grupo ativo) fica em foco por vez.

Para que serve

• Apresentação rotativa de destaque: Ideal para galerias visuais, banners informativos, campanhas institucionais e passos ilustrativos.
• Navegação assistida: Fornece controles de avanço e retrocesso (setas), barra de indicadores de página/slides (bolinhas de paginação) e suporte a gestos de toque (swipe) em dispositivos móveis.
• Reprodução automática controlável: Suporta transição automática temporizada com botão obrigatório de pausa/reprodução para conformidade com diretrizes de acessibilidade (WCAG).

Quando utilizar

• Utilize quando:
  • Houver um conjunto de imagens, avisos ou destaques que compartilham o mesmo nível de relevância visual.
  • O espaço vertical da página for restrito e comportar a rotação sequencial de conteúdos.
• Evite e prefira outro componente quando:
  • Todas as informações forem cruciais para a tarefa do usuário e precisarem ficar simultaneamente visíveis (prefira uma grade com br-card).
  • O fluxo representar preenchimento obrigatório de formulário por etapas (prefira br-wizard ou br-step).

Composição e Subcomponentes

O ecossistema do Carousel é composto por:

Subcomponente	Papel	Regra de uso
br-carousel-page	Slide individual. Encapsula o conteúdo visual ou textual de cada página do carrossel.	Declarado dentro do slot padrão do br-carousel.
br-carousel	Orquestrador principal. Gerencia a rotação, temporizador, botões de paginação, navegação por teclado e gestos.	Contêiner raiz obrigatório declarado na página.

Como os subcomponentes se relacionam

O br-carousel projeta internamente os controles de navegação e gerencia os elementos br-carousel-page declarados em seu interior:

1. O componente pai monitora os slides filhos, calcula o total de páginas e gera dinamicamente os botões indicadores.
2. Apenas a página correspondente ao índice ativo é exibida e anunciada para leitores de tela com atributos aria-roledescription="slide".

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

PadrãoIndicadores internos

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 canônico emitido quando a reprodução automática é pausada.	---	true
brCarouselAutoplayStart	Evento canônico emitido quando a reprodução automática começa.	---	true
brCarouselPageChange	Evento canônico 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

O contêiner recebe role="region", aria-roledescription="carousel" e o nome acessível vindo de aria-label. Apenas o slide do índice ativo é exibido; cada br-carousel-page usa aria-roledescription="slide". O palco tem aria-live para anunciar a troca de slide — o anúncio é suprimido durante a rotação automática e liberado quando ela pausa.

Teclado

• Os indicadores de página usam roving tabindex: ArrowLeft/ArrowRight (ArrowUp/ArrowDown), Home e End movem o foco e trocam o slide.
• Os botões "anterior"/"próximo" têm rótulo próprio.
• Quando auto-play está ativo, há um botão play/pause; a rotação também pausa ao focar ou passar o mouse sobre o carrossel.

Uso

• Não coloque conteúdo essencial apenas em slides que trocam sozinhos.
• Prefira auto-play desligado; se ligado, o controle de pausa é obrigatório (o componente já o fornece).
• indicator-type="textual" expõe "X/N" com aria-live para quem prefere o progresso em texto.

Movimento

A transição entre slides e a rotação automática respeitam prefers-reduced-motion: reduce.

Dependências

Subcomponentes

• br-carousel-page

Depende de

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

Gráfico