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

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Formatar código

Resetar código para o estado inicial

Copiar para a área de transferência

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).
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	A propriedade 'iconName' define um nome Iconify para o í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.
Tipo	number
Valor padrão	0

minSelections

Atributo	min-selections
Descrição	Quantidade mínima de tags selecionadas no mesmo grupo.
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

Atributo	---
Descrição	Regra síncrona ou assíncrona aplicada ao estado e valor da tag.
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. Quando informada, tem precedência sobre os modos booleanos legados.
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	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

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.

Dependências

Usado por

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

Depende de

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

Gráfico

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 selecionado determinável e foco visível. Use grupo nomeado quando várias tags formarem uma escolha relacionada; não use tags decorativas como controles.

Ofereça ativação por Enter/Espaço, mantenha aria-selected sincronizado e associe ajuda/erro por referências ARIA válidas.

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/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.