Carousel
Visão Geral
Design System
Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.
Exemplos
Carregando exemplo
Formatar código
Copiar código
Resetar exemplo
Abrir no StackBlitz
Alternar fundo do preview
Carregando exemplo
Formatar código
Copiar código
Resetar exemplo
Abrir no StackBlitz
Alternar fundo do preview
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
| Atributo | auto-play |
| 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 |
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 Helpers.generateUniqueId(). > Uso compartilhado: mantenha esta descrição idêntica em todos os componentes que usam customId. |
| Tipo | string |
| Valor padrão | Helpers.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' |
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. Só tem efeito quando autoPlay=true. |
| Tipo | number |
| Valor padrão | 5000 |
isCircular
| Atributo | is-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 |
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 | Propagação |
|---|---|---|
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
| Assinatura | getActivePage() => Promise<number> |
| Descrição | Retorna o número do slide atualmente ativo (1 = primeiro slide, 2 = segundo, …). |
| Parâmetros | --- |
getIsPlaying
| Assinatura | getIsPlaying() => Promise<boolean> |
| Descrição | Retorna true se a reprodução automática está ativa no momento. |
| Parâmetros | --- |
goToPage
| Assinatura | goToPage(index: number) => Promise<void> |
| Descrição | Navega para o slide de número index (1 = primeiro slide, 2 = segundo, …).Valores fora do intervalo válido são ignorados. |
| Parâmetros | index: |
nextPage
| Assinatura | nextPage() => Promise<void> |
| Descrição | Avança para o próximo slide. Respeita a prop isCircular (ou ativo automaticamente com autoPlay). |
| Parâmetros | --- |
pause
| Assinatura | pause() => Promise<void> |
| Descrição | Pausa a reprodução automática programaticamente. |
| Parâmetros | --- |
play
| Assinatura | play() => Promise<void> |
| Descrição | Inicia ou retoma a reprodução automática programaticamente. |
| Parâmetros | --- |
previousPage
| Assinatura | previousPage() => Promise<void> |
| Descrição | Retorna ao slide anterior. Respeita a prop isCircular (ou ativo automaticamente com autoPlay). |
| 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. |