Ir para o conteúdo principal
WBC - GovBR-DS
Copiar página como Markdown para IA

Icon

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-icon exibe um ícone com tamanho e alinhamento padronizados. O ícone vem da sua aplicação, de uma destas formas:

<!-- Arquivo ou URL -->
<br-icon src="/icones/busca.svg"></br-icon>

<!-- SVG no próprio código -->
<br-icon svg='<svg viewBox="0 0 24 24"><path d="…" fill="currentColor"/></svg>'></br-icon>

<!-- Outra biblioteca, como Font Awesome -->
<br-icon><i class="fas fa-search"></i></br-icon>

Sem label, o ícone é decorativo e ignorado por leitores de tela. Quando o ícone transmite informação sozinho, descreva-o em label:

<br-icon src="/icones/alerta.svg" label="Atenção"></br-icon>

O tamanho padrão é 16 × 16 px; ajuste com width e height, em qualquer unidade CSS. Use rotate e flip para girar ou espelhar.

Se mais de uma forma for informada, vale nesta ordem: conteúdo, svg, src e, por último, icon-name (depreciado). Para fixar uma delas, use source.

Quando evitar​

  • Fotos e ilustrações: use <img>.

Consulte as diretrizes de design do GovBR.

Exemplo(s)​

Desktop (100%)
Tablet - 768px
iPhone (iOS) - 390x844
Android - 360x800
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
Expandir controles e código

Propriedades​

cssClasses​

Atributocss-classes
DescriçãoPermite adicionar classes CSS adicionais ao ícone.
Use esta propriedade para aplicar estilos personalizados ao ícone, além dos estilos padrão.
Tipostring
Valor padrão---

customId​

Atributocustom-id
DescriçãoIdentificador único do componente.
Quando omitido, um valor é gerado automaticamente.

> Padrão: valor único gerado por generateUniqueId().
Tipostring
Valor padrãogenerateUniqueId()

flip​

Atributoflip
DescriçãoDefine o tipo de espelhamento do ícone.
Aceita horizontal ou vertical; valores inválidos são ignorados.
Tipo"horizontal" | "vertical"
Valor padrão---

focusable​

Atributofocusable
DescriçãoTorna o ícone focável. Quando informada, tem precedência sobre isFocusable.
Tipoboolean
Valor padrão---

height​

Atributoheight
DescriçãoDefine a altura do ícone. Pode ser especificada em qualquer unidade CSS válida, como pixels (px), ems (em), rems (rem), etc.
O valor padrão é '16'. O tamanho pode ser sobrescrito independentemente da largura.
Tipostring
Valor padrão'16'

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

Atributoicon-name
DepreciaçãoUse src com um asset controlado pela aplicação, svg ou o slot padrão.
DescriçãoIdentificador legado do ícone. Identificadores que pertencem ao registro local são
renderizados como SVG empacotado; nomes desconhecidos continuam disponíveis via Iconify
somente para compatibilidade.
Tipostring
Valor padrão---

inline​

Atributoinline
DescriçãoRenderiza o ícone inline. Quando informada, tem precedência sobre isInline.
Tipoboolean
Valor padrão---

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

Atributois-focusable
DepreciaçãoUse focusable.
DescriçãoDetermina se o ícone pode receber foco.
Se definido como verdadeiro, o ícone pode ser navegado usando Tab.
O valor padrão é false.
Tipoboolean
Valor padrãofalse

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

Atributois-inline
DepreciaçãoUse inline.
DescriçãoExibe o rótulo e o controle na mesma linha.
Tipoboolean
Valor padrãofalse

label​

Atributolabel
DescriçãoTexto alternativo para ícones informativos. Sem label, o ícone é decorativo.
Tipostring
Valor padrão---

lazy​

Atributolazy
DescriçãoControla o comportamento de carregamento do ícone.

Comportamento:
- Padrão (propriedade não definida): carregamento imediato aplicando noobserver para evitar problemas de layout shift
- lazy={true}: ativa o carregamento tardio nativo para imagens em src e o observer do Iconify no fallback legado
- lazy={false}: carregamento imediato

Nota: O padrão foi alterado para carregamento imediato para resolver problemas de deslocamento de layout
que ocorriam quando ícones eram carregados depois do conteúdo inicial.

SVG inline e conteúdo em slot não precisam de carregamento tardio, pois já estão disponíveis no DOM.
Tipoboolean
Valor padrão---

rotate​

Atributorotate
DescriçãoDefine o ângulo de rotação do ícone.
Aceita 90deg, 180deg ou 270deg; valores inválidos são ignorados.
Tipo"180deg" | "270deg" | "90deg"
Valor padrão---

source​

Atributosource
DescriçãoDefine explicitamente a origem do ícone.
Quando auto, o componente prioriza slot, SVG inline e imagem por URL.
Iconify fica apenas como fallback de compatibilidade quando nenhuma fonte própria foi informada.
Aceita auto, iconify, image, svg ou slot; valores inválidos usam auto.
Tipo"auto" | "iconify" | "image" | "slot" | "svg"
Valor padrão'auto'

src​

Atributosrc
DescriçãoURL ou caminho local para um arquivo de imagem que será usado como ícone.
O caminho é resolvido pelo navegador no contexto da aplicação consumidora,
portanto pode ser relativo (./assets/icone.svg), absoluto (/assets/icone.svg)
ou uma URL completa.
Aceita SVG, PNG, WebP e outros formatos suportados pelo elemento img.
Tipostring
Valor padrão---

svg​

Atributosvg
DescriçãoConteúdo SVG inline a ser renderizado como ícone.

Use apenas SVGs confiáveis e sanitizados pela aplicação.
Passe o conteúdo por property binding para evitar serialização no atributo.
Exemplo de uso
const icon = document.querySelector('br-icon');
icon.svg = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 2 22 22H2Z" /></svg>';
Tipostring
Valor padrão---

width​

Atributowidth
DescriçãoDefine a largura do ícone. Pode ser especificada em qualquer unidade CSS válida, como pixels (px), ems (em), rems (rem), etc.
O valor padrão é '16'. A largura pode ser sobrescrita independentemente da altura.
Tipostring
Valor padrão'16'

Slots​

NomeDescrição
Conteúdo customizado do ícone. Pode receber elementos como <i>, <svg> ou componentes de outras bibliotecas.

CSS Shadow Parts​

NomeDescrição
"icon"Elemento interno que representa o ícone renderizado.
"image"Elemento img interno quando src é usado.
"slot"Elemento interno que recebe conteúdo via slot.
"svg"Elemento interno que recebe SVG inline quando svg é usado.

Ícones por nome (icon-name)​

icon-name está depreciado. Ele busca o ícone pelo nome no Iconify, o que pode depender de rede, atrasar o desenho do ícone e exigir liberação na política de segurança (CSP). Prefira src, svg ou o conteúdo do br-icon.

Como migrar​

  1. Baixe o SVG do ícone para os assets da aplicação.
  2. Troque icon-name por src.
<!-- Antes -->
<br-icon icon-name="fa6-solid:magnifying-glass"></br-icon>

<!-- Agora -->
<br-icon src="/icones/busca.svg"></br-icon>

Enquanto usar icon-name​

Os ícones usados pelos próprios componentes já vêm na biblioteca e funcionam sem internet. Outros nomes são buscados em https://api.iconify.design. Sem acesso a esse endereço:

  • Registre os ícones no início da aplicação:

    import { addIcon } from 'iconify-icon';

    addIcon('custom:casa', {
      body: '<path d="M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z" fill="currentColor"/>',
      width: 24,
      height: 24,
    });

  • Ou aponte para uma API do Iconify hospedada pela sua organização com addAPIProvider.

  • Se usar a API pública, libere-a na CSP: connect-src 'self' https://api.iconify.design.

Por padrão, o ícone carrega na hora. Com lazy, só carrega quando entra na tela; use apenas em páginas com muitos ícones fora da área visível.

Dependências​

Usado por​

Gráfico​

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

1.x2.xO que fazer
—labelDescreva ícones que transmitem informação sozinhos.
br-icon-basebr-iconRenomeie o elemento.
classNamecss-classesRenomeie.
iconName + familyNamesrc, svg ou conteúdoUse um arquivo SVG ou coloque o ícone dentro do br-icon.

1.x:

<br-icon-base icon-name="search" family-name="fas"></br-icon-base>

2.x:

<br-icon src="/icones/busca.svg" label="Pesquisar"></br-icon>
Comece aquiComponentesQuickstartsSobre o projetoRepositório GitLabVersõesDiscordGovBR-DSFAQWikiRedefinir cookies
© 2026 Governo Federal · SERPRO. O Padrão Digital de Governo utiliza as licenças CC0 1.0 Universal e MIT.