Tab
Visão Geral
O br-tab organiza diferentes visões ou painéis de conteúdo na mesma página através de abas navegáveis.
Declare os itens usando br-tab-item no slot padrão. O componente gera automaticamente os botões da barra de navegação e controla a exibição do painel correspondente.
<br-tab>
<br-tab-item label="Dados Cadastrais">
<p>Conteúdo da primeira aba.</p>
</br-tab-item>
<br-tab-item label="Documentos">
<p>Conteúdo da segunda aba.</p>
</br-tab-item>
</br-tab>
Quando usar
- Alternar entre conjuntos equivalentes de informação sem sair da página e sem ordem fixa de leitura.
Quando evitar
- Processos com etapas sequenciais que dependem de preenchimento prévio: use
br-wizardoubr-step. - Links para páginas ou rotas distintas: use
br-linkoubr-header.
Consulte as diretrizes de design do GovBR.
Exemplo(s)
Propriedades
activeTabId
| Atributo | active-tab-id |
|---|---|
| Descrição | ID do tab atualmente ativo |
| Tipo | string |
| Valor padrão | '' |
alignItemsTab
| 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. 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
| 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.Taba 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
Depende de
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>
