Tab

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-tab é o organizador de navegação por abas do GovBR-DS, desenvolvido para permitir que a pessoa usuária alterne entre diferentes visões ou painéis de conteúdo correlacionados sem sair da mesma página.

Para que serve

• Segmentação de conteúdo em mesmo nível: Agrupa informações que compartilham o mesmo contexto geral (ex.: "Visão Geral", "Especificações", "Histórico", "Anexos").
• Economia de espaço vertical: Evita rolagens excessivas na página mantendo apenas o painel selecionado visível no momento.
• Navegação acessível WAI-ARIA Tablist: Implementa o padrão oficial de abas acessíveis: papéis semânticos tablist, tab e tabpanel, com controle total por setas do teclado e foco cíclico.

Quando utilizar

• Utilize quando:
  • Houver conjuntos equivalentes de informação entre os quais a pessoa usuária pode navegar livremente e em qualquer ordem.
• Evite e prefira outro componente quando:
  • O conteúdo for sequencial com dependência de avanço ou conclusão de etapas anteriores (prefira br-step ou br-wizard).
  • As abas tiverem a função de navegar para rotas e URLs distintas da aplicação (prefira uma barra de links com br-link ou br-header).

Composição e Subcomponentes

Subcomponente	Papel	Regra de uso
br-tab-item	Aba e painel associado. Define simultaneamente o rótulo do botão da aba e o conteúdo do painel correspondente.	Declarado no slot padrão do br-tab.
br-tab	Orquestrador de abas. Constrói a barra de navegação acessível (tablist), controla a aba ativa e gerencia o teclado.	Contêiner raiz obrigatório declarado no template.

Como os subcomponentes se relacionam

O br-tab adota uma arquitetura declarativa prática:

1. A aplicação declara os elementos br-tab-item dentro do slot padrão do br-tab.
2. O componente pai extrai os rótulos e ícones de cada item para renderizar a barra superior de abas (role="tab").
3. O pai controla a visibilidade dos painéis (role="tabpanel"), exibindo exclusivamente o conteúdo da aba selecionada e garantindo a correlação de IDs acessíveis (aria-controls, aria-labelledby).

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ão

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

activeTabId

Atributo	active-tab-id
Descrição	ID do tab atualmente ativo
Tipo	string
Valor padrão	''

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

Atributo	align-items-tab
Depreciação	Use alignment.
Descrição	Define o alinhamento horizontal dos itens da tab na barra de navegação.
Tipo	"center" | "end" | "start"
Valor padrão	'start'

alignment

Atributo	alignment
Descrição	Alinhamento horizontal canônico. Quando informado, tem precedência sobre alignItemsTab; valores inválidos usam start.
Tipo	"center" | "end" | "start"
Valor padrão	---

colorMode

Atributo	color-mode
Descrição	Define se o Tab usará um esquema de cores escuro. Valores inválidos são ignorados.
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()

density

Atributo	density
Descrição	Define a densidade visual do componente. - small: Alta densidade (componente menor, mais compacto e com menos espaçamento). - medium: Densidade intermediária, padrão recomendado para a maioria dos casos. - large: Baixa densidade (componente maior, mais espaçamento e altura). Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

height

Atributo	height
Descrição	Define a altura máxima da área de conteúdo, ativando o scroll interno quando o conteúdo ultrapassa essa altura.
Tipo	string
Valor padrão	---

label

Atributo	label
Descrição	Label de acessibilidade para a navegação das tabs
Tipo	string
Valor padrão	'Abas de Navegação'

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

Atributo	scroll-disabled
Depreciação	Use scrollable.
Descrição	Desabilita o scroll automático da área de conteúdo. Por padrão, o scroll vertical fica apenas na região de conteúdo.
Tipo	boolean
Valor padrão	false

scrollable

Atributo	scrollable
Descrição	Controla o scroll interno. Quando informado, tem precedência sobre scrollDisabled.
Tipo	boolean
Valor padrão	---

Slots

Nome	Descrição
"default"	Slot para inserir os itens das abas (br-tab-item)
"icon-{id}"	Ícone da aba cujo br-tab-item tem o id informado (ex.: <i slot="icon-avisos" class="fas fa-bell" aria-hidden="true"></i>). Forma preferida para ícones por classe CSS, como Font Awesome: o elemento fica em light DOM e recebe os estilos globais da página. Tem precedência sobre a prop icon do item.

Eventos

Evento	Descrição	Depreciação	Propagação
brTabChange	Evento disparado quando um tab é ativado.	---	true

Métodos

getActiveTab

Descrição	Retorna o identificador da aba ativa atual.
Assinatura	getActiveTab() => Promise<string | undefined>
Parâmetros	---

setActiveTab

Descrição	Ativa programaticamente uma aba a partir do seu identificador.
Assinatura	setActiveTab(tabId: string) => Promise<void>
Parâmetros	tabId: Identificador da aba (tab-item-id).

CSS Shadow Parts

Nome	Descrição
"button"	Botão individual de cada aba.
"container"	Contêiner principal que envolve toda a estrutura do componente (navegação e conteúdo). Expõe o elemento para customizações de fundo, bordas e espaçamentos globais.
"content"	Área de conteúdo das abas.
"indicator"	Indicador visual da aba ativa.
"nav"	Área de navegação (tablist) onde os botões das abas estão localizados. Permite customizar o alinhamento, espaçamento e plano de fundo da barra de abas.

Acessibilidade

O br-tab implementa o padrão APG de abas. A barra é um role="tablist" com nome acessível vindo de label. Cada botão é role="tab" com aria-selected, aria-setsize/aria-posinset e roving tabindex (tabindex="0" só na aba ativa, -1 nas demais). O painel exibido é o role="tabpanel" correlacionado por aria-labelledby/aria-controls com a aba, e é focável.

Teclado

• ArrowRight/ArrowLeft (e as verticais quando o layout for vertical) movem o foco entre as abas e ativam a aba focada.
• Tab a partir da barra leva ao painel da aba ativa.
• Apenas o painel da aba selecionada é renderizado/visível.

Estrutura

Cada br-tab-item fornece rótulo, ícone opcional e um contador opcional (que entra no nome acessível da aba, ex.: "Mensagens (3)"). Mantenha rótulos curtos e distintos.

Ícones

Ícones por classe CSS (ex.: Font Awesome) entram pelo slot icon-{id} do br-tab, onde {id} é o id do br-tab-item. O elemento fica em light DOM e recebe os estilos globais da página. Marque-o como decorativo, com aria-hidden="true": o nome da aba vem do label.

<br-tab>
  <i slot="icon-avisos" class="fas fa-bell" aria-hidden="true"></i>
  <br-tab-item id="avisos" label="Avisos">Conteúdo</br-tab-item>
</br-tab>

A prop icon do br-tab-item aceita identificadores Iconify (ex.: fa6-solid:bell). Classes CSS nessa prop não são exibidas no Shadow DOM e geram aviso no console.

Movimento

O indicador da aba ativa e a transição de conteúdo respeitam prefers-reduced-motion: reduce.

Dependências

Subcomponentes

• br-tab-item

Depende de

• br-icon
• br-divider

Gráfico

Migração de <br-tab> para a composição atual (1.x → 2.x)

A 1.x registrava br-tab e br-tab-item como elementos Vue. Na 2.x, use a composição atual com br-tab como contêiner e br-tab-item para cada aba.

Propriedades e composição

API 1.x	API 2.x	Ação na migração
—	activeTabId, alignment, scrollable	Use para controlar a aba ativa e o comportamento do conjunto.
counter	conteúdo/propriedade do br-tab-item	Mova para o item da aba.
density	density	Mantenha.
inverted	colorMode	Renomeie.
label	label	Mantenha no item correspondente.

Exemplo

1.x:

<br-tab :tabs="tabs" inverted></br-tab>

2.x:

<br-tab active-tab-id="inicio" color-mode="inverted">
  <br-tab-item id="inicio" label="Início">Conteúdo</br-tab-item>
  <br-tab-item id="ajuda" label="Ajuda">Conteúdo</br-tab-item>
</br-tab>