Item

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)

Propriedades

active

Atributo	active
Descrição	Estado ativo canônico. Quando informado, tem precedência sobre isActive.
Tipo	boolean
Valor padrão	---

button

Atributo	button
Descrição	Renderiza o item como botão. Quando informado, tem precedência sobre isButton.
Tipo	boolean
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

href

Atributo	href
Descrição	URL ou caminho para o qual o usuário será direcionado ao clicar no item. Quando definido, o item será renderizado como um link.
Tipo	string
Valor padrão	---

interactive

Atributo	interactive
Descrição	Torna toda a superfície interativa. Quando informado, tem precedência sobre isInteractive.
Tipo	boolean
Valor padrão	---

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

Atributo	is-active
Depreciação	Use active.
Descrição	Indica se o item está no estado ativo. Se definido como verdadeiro, o item será exibido como ativo.
Tipo	boolean
Valor padrão	false

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

Atributo	is-button
Depreciação	Use button.
Descrição	Quando definido como true, o item será tratado como um botão.
Tipo	boolean
Valor padrão	false

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

Atributo	is-interactive
Depreciação	Use interactive.
Descrição	Marca o item como interativo, permitindo que toda a superfície do item seja clicável.
Tipo	boolean
Valor padrão	false

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

Atributo	is-selected
Depreciação	Use selected.
Descrição	Indica se o item está no estado selecionado. Se definido como verdadeiro, o item será exibido como selecionado.
Tipo	boolean
Valor padrão	false

navigationMode

Atributo	navigation-mode
Descrição	Controla como o componente integra a navegação mantendo href real no elemento navegável. - native (padrão): preserva o comportamento do navegador, conforme HTML/W3C. - event: emite brNavigate; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir. Cliques com modificadores, botão do meio ou target diferente de _self permanecem nativos.
Tipo	"event" | "native"
Valor padrão	'native'

selected

Atributo	selected
Descrição	Estado selecionado canônico. Quando informado, tem precedência sobre isSelected.
Tipo	boolean
Valor padrão	---

target

Atributo	target
Descrição	Define o alvo do link quando href está presente. Pode ser: - _blank para abrir em uma nova aba, - _self para abrir na mesma aba, - _parent para abrir na aba pai, - _top para abrir na aba superior.
Tipo	"_blank" | "_parent" | "_self" | "_top"
Valor padrão	---

type

Atributo	type
Descrição	Tipo do botão, aplicável apenas se isButton for true. Pode ser: - 'submit' para enviar um formulário, - 'reset' para redefinir um formulário, - 'button' para um botão padrão.
Tipo	"button" | "reset" | "submit"
Valor padrão	---

value

Atributo	value
Descrição	Define um valor associado ao br-item quando renderizado como um botão, utilizado em contextos de formulário.
Tipo	string
Valor padrão	---

Slots

Nome	Descrição
"default"	Área de conteúdo, podendo conter qualquer componente, exceto botões primários e componentes relacionados à navegação (como carrosséis, paginações, abas, menus, etc.).
"end"	Área de recursos complementares, podendo conter componentes interativos, metadados e informações adicionais.
"start"	Área de recursos visuais, podendo conter elementos como ícones, avatares e mídias.

Eventos

Evento	Descrição	Depreciação	Propagação
brDidClick Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.		Use brItemClick.	true
brDidSelect Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.		Use brItemSelect.	true
brItemClick	Evento canônico emitido quando o item com comportamento de botão é acionado.	---	true
brItemSelect	Evento canônico emitido quando a seleção muda.	---	true
brNavigate	Evento cancelável emitido em navigation-mode="event" para cliques primários sem modificadores em links _self. Chame event.preventDefault() no listener para impedir a navegação nativa e entregar event.detail.href ao roteador da SPA.	---	true

Métodos

activate

Descrição	Ativa o item programaticamente, simulando um clique na superfície. Utilizado pelo br-list para tratar Enter e Espaço via teclado, e internamente pelo próprio item quando standalone (fora de br-list).
Assinatura	activate() => Promise<void>
Parâmetros	---

setFocus

Descrição	Define o foco no elemento interno do componente. Este método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto.
Assinatura	setFocus() => Promise<void>
Parâmetros	---

setTabIndex

Descrição	Define o tabIndex do elemento interno. Utilizado pelo br-list para implementar o padrão roving tabindex, garantindo que apenas um item por vez seja alcançável via Tab.
Assinatura	setTabIndex(value: number) => Promise<void>
Parâmetros	value:

CSS Shadow Parts

Nome	Descrição
"item"	Elemento principal do item (botão, link ou div).

Dependências

Usado por

• br-breadcrumb
• br-footer-category
• br-footer-item
• br-header-function
• br-header-link
• br-notification-item
• br-pagination
• br-select-option
• br-skiplink-item
• br-upload

Gráfico

Migração de <br-item> (1.x → 2.x)

O item mantém os estados de seleção e os links, mas a API atual separa melhor interação, navegação e composição.

Propriedades e eventos

API 1.x	API 2.x	Ação na migração
—	navigationMode	Configure quando o item participa da navegação da aplicação.
active, selected, disabled, href	mesmos nomes	Mantenha as propriedades canônicas.
hover, open, title	—	Remova; modele o comportamento com composição e estados atuais.
isActive, isSelected, isInteractive, isButton	active, selected, interactive, button	Não use aliases legados no código novo.
eventos de toggle da 1.x	brItemClick / brItemSelect	Atualize os listeners para os eventos atuais.

Exemplo

1.x:

<br-item title="Documentação" href="/docs" active></br-item>

2.x:

<br-item href="/docs" active>Documentação</br-item>

Migração de Navegação

Antes, br-item aceitava is-spa-link-behavior quando era renderizado como link.

Agora, use navigation-mode="event" junto com href.

<!-- Antes -->
<br-item href="/servicos" is-spa-link-behavior>Servicos</br-item>

<!-- Agora -->
<br-item href="/servicos" navigation-mode="event">Servicos</br-item>

O evento emitido é brNavigate. Cancele o evento para entregar a navegação ao roteador da SPA. Sem cancelamento, a navegação nativa continua.