Copiar página como Markdown para IA

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 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-wizard ou br-step.
Links para páginas ou rotas distintas: use br-link ou br-header.

Consulte as diretrizes de design do GovBR.

Exemplos

Carregando preview…

Recolher controles e código

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. 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 Font Awesome 5 Free presentes no cache local (ex.: fa-solid:bell). Nomes fora do cache não são carregados remotamente. 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

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>

Visão Geral​

Quando usar​

Quando evitar​

Propriedades​

activeTabId​

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

alignment​

colorMode​

customId​

density​

height​

label​

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

scrollable​

Slots​

Eventos​

Métodos​

getActiveTab​

setActiveTab​

CSS Shadow Parts​

Acessibilidade​

Teclado​

Estrutura​

Ícones​

Movimento​

Dependências​

Subcomponentes​

Depende de​

Gráfico​

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

Propriedades e composição​

Exemplo​