Copiar página como Markdown para IA

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

O componente br-item é o elemento flexível e padronizado do GovBR-DS para construção de linhas navegáveis, selecionáveis ou de exibição em listas, menus contextuais e painéis suspensos.

Para que serve

Padronização de linhas interativas: Garante espaçamento, tipografia, contraste e efeitos de estado (hover, foco visível, seleção e desativação) em conformidade com os tokens do design system.
Polimorfismo semântico: Pode renderizar internamente um botão interativo (<button>), um hiperlink navegável (<a>) ou uma divisão semântica (<div>) dependendo dos atributos fornecidos (href, clickable).
Suporte a seleção visual: Oferece suporte a estados de seleção (selected), marcas de verificação e densidades ajustáveis.

Quando utilizar

Utilize quando:
- Estiver montando linhas de conteúdo em listas (br-list), painéis flutuantes (br-dropdown) ou agrupamentos verticais.
- Cada entrada representar um item de dado ou uma ação com estilo homogêneo.
Evite e prefira outro componente quando:
- O item pertencer especificamente à navegação de abas (use br-tab-item), etapas de fluxo (use br-step-item) ou seleção em formulário (use br-select-option).

Estrutura e Slots

O br-item é um componente estrutural direto:

default: Slot para inserção do conteúdo livre da linha (textos, ícones, badges ou metadados).

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Padrão

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Tela cheia

Carregando preview…

Recolher controles e código

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). 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`

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. Em itens interativos, também é atualizado pelo acionamento.
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).

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.

Dependências

Usado por

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>

Visão Geral​

Para que serve​

Quando utilizar​

Estrutura e Slots​

Exemplo(s)​

Propriedades​

active​

button​

customId​

density​

disabled​

href​

interactive​

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

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

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

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

navigationMode​

selected​

target​

type​

value​

Slots​

Eventos​

Métodos​

activate​

setFocus​

setTabIndex​

CSS Shadow Parts​

Migração de Navegação​

Dependências​

Usado por​

Gráfico​

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

Propriedades e eventos​

Exemplo​