Tag

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-tag é o elemento visual compacto do GovBR-DS utilizado para rotular, categorizar, exibir metadados ou aplicar filtros rápidos na interface.

Para que serve

• Categorização e metadados: Identifica o tipo, categoria ou atributos de um item (ex.: "Educação", "Tecnologia", "Urgente").
• Sinalização de status: Exibe estados operacionais de processos ou documentos através de cores semânticas e ícones (ex.: "Aprovado", "Pendente", "Cancelado").
• Filtros interativos dispensáveis: Suporta botão de fechamento (closable), permitindo remover filtros dinamicamente.
• Tags de seleção: Suporta modo interativo selecionável com integração nativa a formulários (formAssociated).

Quando utilizar

• Utilize quando:
  • Exibir palavras-chave associadas a um conteúdo ou cartão.
  • Exibir status sucinto de registros em tabelas (br-table) ou cabeçalhos.
  • Oferecer filtros aplicados que podem ser removidos com um clique.
• Evite e prefira outro componente quando:
  • O elemento for a ação primária ou um comando executável (prefira br-button).
  • O texto for extenso e exigir explicações detalhadas (prefira br-message).

Estrutura e Slots

O br-tag oferece flexibilidade estrutural:

• default: Slot principal para texto ou conteúdo livre da tag.
• label: Slot para rótulo customizado.
• icon: Slot para inserção de ícone auxiliar (br-icon).
• close-button: Slot para customizar o botão de remoção.
• feedback: Slot para mensagem de validação contextual.

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

ariaDescribedby

Atributo	aria-describedby
Descrição	ID do elemento que fornece descrição adicional da tag. Referencia um elemento na página que contém informações complementares sobre a tag. A descrição é lida após o conteúdo principal, fornecendo contexto extra aos usuários de leitores de tela. Exemplo: aria-describedby="help-status" onde existe Aguardando aprovação
Tipo	string
Valor padrão	null

ariaLabel

Atributo	aria-label
Descrição	Define o rótulo acessível usado por tecnologias assistivas.
Tipo	string
Valor padrão	---

bgColor

Atributo	bg-color
Descrição	A propriedade 'color' permite definir a cor do componente. Aceita valores como 'red', 'blue', entre outros, e é refletida no DOM.
Tipo	string
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'

disabled

Atributo	disabled
Descrição	Desabilita a interação com o componente.
Tipo	boolean
Valor padrão	false

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

Atributo	icon-name
Depreciação	Use o slot icon com um SVG, asset ou elemento de ícone controlado pela aplicação.
Descrição	Identificador legado do ícone exibido ao lado do texto.
Tipo	string
Valor padrão	''

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

Atributo	interaction
Depreciação	Use variant="action".
Descrição	Interação deve ser habilitada.
Tipo	boolean
Valor padrão	false

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

Atributo	interaction-select
Depreciação	Use variant="selectable".
Descrição	Interação de seleção deve ser habilitada.
Tipo	boolean
Valor padrão	false

label

Atributo	label
Descrição	A propriedade 'label' é uma string que representa o texto a ser exibido no componente. Ela é refletida no DOM, permitindo que alterações no valor sejam refletidas no elemento HTML correspondente.
Tipo	string
Valor padrão	''

maxSelections

Atributo	max-selections
Descrição	Quantidade máxima de tags selecionadas no mesmo grupo. Zero significa sem limite. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	number
Valor padrão	0

minSelections

Atributo	min-selections
Descrição	Quantidade mínima de tags selecionadas no mesmo grupo. Deve ser um inteiro não negativo; valores inválidos usam 0.
Tipo	number
Valor padrão	0

multiple

Atributo	multiple
Descrição	A tag permite seleção múltipla.
Tipo	boolean
Valor padrão	false

name

Atributo	name
Descrição	A propriedade 'name' é uma string que representa o nome do grupo da tag para seleção. Ela é refletida no DOM, permitindo que alterações no valor sejam refletidas no elemento HTML correspondente.
Tipo	string
Valor padrão	''

required

Atributo	required
Descrição	Exige uma seleção no grupo quando interaction-select está ativo.
Tipo	boolean
Valor padrão	false

selected

Atributo	selected
Descrição	A tag está selecionada.
Tipo	boolean
Valor padrão	false

shape

Atributo	shape
Descrição	A propriedade 'shape' define o formato do componente.
Tipo	"circle" | "default" | "rounded"
Valor padrão	'default'

size

Atributo	size
Descrição	Define o tamanho personalizado do componente quando o formato for circular (circle), arredondado (rounded) ou status. Aceita qualquer valor de tamanho CSS válido (ex: 16px, 1.5rem).
Tipo	string
Valor padrão	''

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

Atributo	status
Depreciação	Use variant="status".
Descrição	Transforma a tag em um indicador de status, com aparência circular. É flexível podendo ser utilizado com label ou apenas a superfície circular (informação é transmitida por meio de cores).
Tipo	boolean
Valor padrão	false

validator Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Atributo	---
Descrição	Regra síncrona ou assíncrona aplicada ao estado, valor e rótulo da tag.
Exemplo de uso	const tag = document.querySelector('br-tag'); tag.validator = ({ selected, label }) => selected ? null : Selecione a tag ${label};
Tipo	(value: TagValidationValue) => string | Promise<string>
Valor padrão	---

value

Atributo	value
Descrição	Valor submetido quando a tag selecionável está ativa.
Tipo	string
Valor padrão	''

variant

Atributo	variant
Descrição	Variante funcional canônica. Aceita default, status, action ou selectable. Valores inválidos são ignorados; nesse caso, os aliases booleanos legados continuam disponíveis para manter a compatibilidade.
Tipo	"action" | "default" | "selectable" | "status"
Valor padrão	---

Slots

Nome	Descrição
"close-button"	Botão de fechar customizado. Quando utilizado, o botão padrão é substituído.
"default"	Slot para inserir o conteúdo da tag, como rótulo ou ícone.
"feedback"	Mensagem de validação, normalmente um br-message.
"icon"	Ícone customizado da tag. Quando utilizado, a prop icon é ignorada.
"label"	Rótulo customizado da tag. Quando utilizado, a prop label é ignorada.

Eventos

Evento	Descrição	Depreciação	Propagação
brTagValidationChange Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Emitido ao iniciar e concluir a validação customizada.	---	true
radioSelected Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	Evento emitido quando a tag é selecionada.	Use input/change e leia event.target.selected.	true

Métodos

checkValidity

Descrição	Retorna se a tag selecionável atende às constraints configuradas.
Assinatura	checkValidity() => Promise<boolean>
Parâmetros	---

getValidationState

Descrição	Retorna um snapshot serializável da Constraint Validation API.
Assinatura	getValidationState() => Promise<FormValidationState>
Parâmetros	---

reportValidity

Descrição	Valida e solicita ao navegador a apresentação do erro atual.
Assinatura	reportValidity() => Promise<boolean>
Parâmetros	---

setCustomValidity

Descrição	Define ou limpa uma mensagem de validade customizada.
Assinatura	setCustomValidity(message: string) => Promise<void>
Parâmetros	message:

validate Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Descrição	Executa o validator da tag e retorna se o valor atual é válido.
Assinatura	validate() => Promise<boolean>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"feedback"	Contêiner da mensagem de validação.
"input"	Elemento input da tag de seleção.
"label"	Rótulo da tag de seleção.
"tag"	Elemento principal da tag.

Validação

Para o contrato geral e a matriz de componentes, consulte o guia de formulários. Esta seção documenta o contrato específico do br-tag.

Com interaction-select, use required para exigir seleção e min-selections/max-selections no grupo quando aplicável. Leia selected, name e value no target do evento.

Regras de domínio devem ser sincronizadas por setCustomValidity() e consultadas por getValidationState().

Em interaction-select, a mensagem é renderizada como br-message quando não existe feedback. Use o slot feedback para fornecer o conteúdo e manter a referência ARIA.

Para regras de domínio, use validator por property binding. Ele recebe { selected, value, label }, permitindo validar o item sem depender do texto renderizado. A validação também pode ser acionada por await tag.validate() e emite brTagValidationChange.

Acessibilidade

Tags selecionáveis precisam de nome textual, estado marcado determinável e foco visível. Use um grupo nomeado quando várias tags formarem uma escolha relacionada; tags apenas informativas não devem ser tratadas como controles.

No modo selecionável, o componente usa um input do tipo checkbox ou radio e mantém selected e aria-checked sincronizados. Enter ou Espaço ativa a opção. Associe instruções e erros por referências ARIA válidas e não dependa apenas de cor para comunicar o estado.

Eventos nativos

Elemento HTML de referência

Somente a tag selecionável possui referência nativa: checkbox em modo múltiplo e radio em modo exclusivo. Tags informativas/removíveis não são controles de formulário equivalentes.

Como ouvir os eventos

const tag = document.querySelector('br-tag[interaction-select]');
tag.addEventListener('change', () => console.log(tag.selected));

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
change	seleção é confirmada	Sim	Sim	Não	Sim	Depois de input.
input	seleção muda	Sim	Sim	Não	Sim	Apenas no modo selecionável.
click, teclado e foco	tag selecionável é ativada	conforme o tipo	Sim	conforme o tipo	Sim	Semântica depende do modo.

Eventos não aplicáveis ou não suportados

Tags não selecionáveis não emitem input/change. Eventos de edição textual não se aplicam. Escrita externa e reset são silenciosos.

Eventos customizados

radioSelected é alias legado. A remoção possui evento próprio porque não equivale a mudança de valor de um input.

Valor, frameworks e acessibilidade

Leia selected e value no host. FormData existe apenas no modo associado a formulário. Wrappers usam os modelos documentados. O papel, estado e teclado devem corresponder ao modo checkbox/radio.

Evidência de teste

src/shared/contracts/platform-contract.e2e.tsx cobre API comum de formulário; _tests/tag.e2e.tsx cobre seleção e teclado em Chromium. Flags e FormData por modo permanecem pendentes.

Atributos nativos

br-tag participa de formulário somente no modo selecionável. Nesse modo, o host FACE usa name, value, selected, required, disabled, form e autofocus, além dos limites de seleção do componente.

Tags apenas informativas ou removíveis não são inputs. form e autofocus seguem a plataforma, sem props dedicadas.

Dependências

Usado por

• br-avatar
• br-notification-item
• br-skiplink-item

Depende de

• br-icon
• br-button
• br-message

Gráfico