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 componente br-icon é o elemento oficial do GovBR-DS para renderização dinâmica e padronizada de ícones vetoriais. Ele suporta a família tipográfica Font Awesome e ícones utilitários do governo, garantindo contraste, escalabilidade e acessibilidade visual.

Para que serve

Comunicação visual imediata: Fornece apoio gráfico rápido para ações em botões, links, cartões, menus e alertas contextuais.
Acessibilidade nativa: Gerencia automaticamente a visibilidade para leitores de tela: ícones decorativos recebem aria-hidden="true", enquanto ícones informativos recebem nome acessível via aria-label.
Flexibilidade dimensional e cromática: Permite personalizar tamanho, cor através de tokens CSS do GovBR-DS, rotação e efeitos de espelhamento.

Quando utilizar

Utilize quando:
- For necessário reforçar o significado de um texto ou ação com uma representação gráfica familiar.
- Criar controles compactos com ícone acompanhado de descrição acessível.
Evite e prefira outro componente quando:
- For necessária uma imagem fotográfica ou ilustração visual ampla com detalhes cromáticos complexos (prefira tags HTML <img> ou SVG ilustrativo).

Estrutura e Slots

O br-icon renderiza um elemento vetorial direto com base no atributo name informado ou através de classes utilitárias.

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

Exemplo(s)

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Tela cheia

Carregando preview…

Expandir controles e código

Propriedades

cssClasses

Atributo	`css-classes`
Descrição	Permite adicionar classes CSS adicionais ao ícone. Use esta propriedade para aplicar estilos personalizados ao ícone, além dos estilos padrão.
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()`

flip

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

focusable

Atributo	`focusable`
Descrição	Torna o ícone focável. Quando informada, tem precedência sobre `isFocusable`.
Tipo	`boolean`
Valor padrão	---

height

Atributo	`height`
Descrição	Define 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.
Tipo	`string`
Valor padrão	`'16'`

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

Atributo	`icon-name`
Depreciação	Use `src` com um asset controlado pela aplicação, `svg` ou o slot padrão.
Descrição	Identificador 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.
Tipo	`string`
Valor padrão	---

inline

Atributo	`inline`
Descrição	Renderiza o ícone inline. Quando informada, tem precedência sobre `isInline`.
Tipo	`boolean`
Valor padrão	---

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

Atributo	`is-focusable`
Depreciação	Use `focusable`.
Descrição	Determina se o ícone pode receber foco. Se definido como verdadeiro, o ícone pode ser navegado usando Tab. O valor padrão é `false`.
Tipo	`boolean`
Valor padrão	`false`

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

Atributo	`is-inline`
Depreciação	Use `inline`.
Descrição	Exibe o rótulo e o controle na mesma linha.
Tipo	`boolean`
Valor padrão	`false`

label

Atributo	`label`
Descrição	Texto alternativo para ícones informativos. Sem label, o ícone é decorativo.
Tipo	`string`
Valor padrão	---

lazy

Atributo	`lazy`
Descrição	Controla 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.
Tipo	`boolean`
Valor padrão	---

rotate

Atributo	`rotate`
Descrição	Define 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

Atributo	`source`
Descrição	Define 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

Atributo	`src`
Descrição	URL 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`.
Tipo	`string`
Valor padrão	---

svg

Atributo	`svg`
Descrição	Conteú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>';`
Tipo	`string`
Valor padrão	---

width

Atributo	`width`
Descrição	Define 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.
Tipo	`string`
Valor padrão	`'16'`

Slots

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

CSS Shadow Parts

Nome	Descriçã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.

Iconify: compatibilidade legada e migração

O componente br-icon mantém suporte à biblioteca Iconify por compatibilidade, por meio da propriedade iconName e do atributo HTML correspondente icon-name.

Essa API está depreciada. Para novos desenvolvimentos, o ícone deve pertencer à aplicação consumidora: use src para um asset local/URL controlado, svg para SVG inline ou o slot para conteúdo já disponível no projeto.

O módulo iconify-icon é carregado sob demanda somente quando o fallback Iconify é necessário. Os ícones padrão dos componentes são resolvidos pelo registro SVG local, permanecem disponíveis offline e não carregam essa dependência adicional. Para novos exemplos, use src, svg ou o slot; iconName/icon-name deve ser reservado para integrações legadas ou para um ícone explicitamente fornecido pelo consumidor.

Essa prioridade reduz acoplamento a terceiros, evita requisições inesperadas à rede/CDN, facilita CSP e uso offline, e torna a versão do asset reproduzível junto com a aplicação.

Por que Iconify deixou de ser a opção prioritária

Ao avaliar o uso do Iconify no br-icon, é importante considerar os seguintes prós e contras:

Aspecto	Vantagens	Riscos e Desvantagens
Catálogo	Catálogo amplo de coleções e nomes de ícones padronizados (Font Awesome, Material Design Icons, etc.).	Aumenta o acoplamento do componente a uma biblioteca de terceiros específica (`iconify-icon`).
Customização	Compatibilidade nativa com atributos de rotação (`rotate`), espelhamento (`flip`) e alinhamento (`is-inline`).	O carregamento assíncrono dos SVGs sob demanda pode causar variações no tempo de renderização e pequenas oscilações de layout (Cumulative Layout Shift).
Prototipação	API simples para prototipação e uso rápido: basta declarar a propriedade `iconName` ou o atributo `icon-name`.	Pode gerar falhas visuais ou ícones não renderizados se a rede falhar, se a coleção for alterada ou se o cache for limpo.
Segurança & Rede	Pode ser configurado para usar coleções registradas localmente.	Pode depender de requisições de rede para a CDN pública (`https://api.iconify.design`), exigindo atenção à CSP e configuração adicional para uso offline.

⚡ Integração com `iconify-icon` e a propriedade `lazy`

Internamente, a renderização do Iconify utiliza o componente web oficial <iconify-icon>.

Otimização de Renderização (`noobserver`)

Por padrão, o componente <iconify-icon> utiliza um IntersectionObserver interno para adiar o carregamento e renderização do ícone até que ele entre no viewport (comportamento lazy-load).

No br-icon, para mitigar problemas de oscilações visuais de layout, o comportamento padrão foi alterado para carregamento imediato. A propriedade lazy controla isso da seguinte forma:

Padrão / lazy={false}: O componente insere a propriedade noobserver no <iconify-icon>, desabilitando o observer e renderizando o ícone imediatamente.
lazy={true}: Ativa o observer nativo do Iconify, realizando o carregamento preguiçoso do ícone. Recomendado apenas para páginas com muitos ícones posicionados fora da tela inicial.

[!WARNING] Com src, lazy={true} usa o carregamento nativo do navegador (loading="lazy") para o <img>. SVG inline (svg) e conteúdo em slot já estão disponíveis no DOM e não possuem carregamento externo para adiar. No fallback Iconify, lazy continua controlando o observer do Iconify.

🔒 Soluções de Uso Offline e CSP (Content Security Policy)

Se o seu projeto é executado em ambientes restritos (intranets governamentais sem internet) ou com CSP rígido que bloqueia conexões externas, existem estratégias para permitir o funcionamento offline dos ícones:

1. Pré-registro de Ícones pelo Usuário (`addIcon` / `addCollection`)

Você pode importar as APIs do iconify-icon no ponto de entrada/bootstrap da sua aplicação (ex: index.js) e registrar os ícones necessários em memória:

import { addIcon, addCollection } from 'iconify-icon';

// Registrar um ícone individual: https://iconify.design/docs/iconify-icon/add-icon.html

addIcon('fa6-solid:search', {
  body: '<path fill="currentColor" d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0s208 93.1 208 208zM208 352a144 144 0 1 0 0-288 144 144 0 1 0 0 288z"/>',
  width: 512,
  height: 512,
});

// Registrar uma coleção completa: https://iconify.design/docs/iconify-icon/add-collection.html
addCollection({
  prefix: 'custom',
  icons: {
    home: {
      body: '<path d="M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z" fill="currentColor"/>',
    },
  },
  width: 24,
  height: 24,
});

2. Direcionar para uma API auto-hospedada (`addAPIProvider`)

Se sua organização hospeda uma instância própria da API do Iconify:

import { addAPIProvider } from 'iconify-icon';

addAPIProvider('', {
  resources: ['https://iconify.sua-organizacao.gov.br'],
});

Para mais detalhes, consulte a documentação do addAPIProvider.

[!NOTE] Se optar por buscar os ícones via rede da CDN padrão, sua política de segurança (CSP) deve conter a seguinte permissão: Content-Security-Policy: connect-src 'self' https://api.iconify.design;

🚀 Guia de Migração para as APIs Recomendadas

Para remover a dependência de CDNs externas e garantir o máximo desempenho dos ícones, migre os seus componentes conforme os exemplos abaixo. Os exemplos de componentes e do site usam estas formas nativas por padrão:

Opção A: Caminho por arquivo local ou URL (`src`)

Use quando os arquivos SVG residem na sua pasta de assets ou sob uma URL pública controlada por você.

<!-- Font Awesome 5 via slot -->
<br-icon>
  <i class="fas fa-search" aria-hidden="true"></i>
</br-icon>

<!-- Recomendado para assets próprios -->
<br-icon src="/assets/icons/magnifying-glass.svg"></br-icon>

Opção B: SVG Inline (`svg`)

Use para injetar a string estruturada do SVG diretamente no DOM Shadow do componente, evitando qualquer requisição HTTP externa para o ícone.

<!-- Recomendado (Nativo via svg) -->
<br-icon
  svg='<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z" fill="currentColor"/></svg>'
></br-icon>

Opção C: Injeção por Slot Padrão (Slot)

Perfeito para integrar bibliotecas externas carregadas globalmente (como Font Awesome via tags <i>), ícones de frameworks ou customizações complexas de marcação HTML.

<!-- Recomendado (Nativo via slot) -->
<br-icon>
  <i class="fas fa-search" aria-hidden="true"></i>
</br-icon>

📏 Dimensionamento, Alinhamento e Estilos

Ao utilizar src, svg ou slots sem definir width e height, o br-icon usa os valores padrão de 16px de largura e 16px de altura. As props width e height continuam independentes e podem receber qualquer unidade CSS válida.

Se o conteúdo injetado via slot padrão precisar ser redimensionado internamente de forma isolada, aplique as seguintes variáveis CSS customizadas no elemento injetado:

--br-icon-slotted-width
--br-icon-slotted-height
--br-icon-slotted-font-size

🔀 Ordem Automática de Renderização (`source="auto"`)

Caso mais de um método de inclusão seja configurado simultaneamente, o br-icon decidirá o que exibir baseando-se no valor da propriedade source (que por padrão é 'auto'). No modo 'auto', a ordem de prioridade é:

Slot Padrão (se houver elementos ou texto no slot).
SVG Inline (propriedade svg).
Caminho de imagem/URL da aplicação (propriedade src).
Registro SVG local (nomes padrão e aliases conhecidos informados em iconName/icon-name).
Iconify legado (somente quando o nome não está no registro local).

Para desativar a priorização automática e impor uma origem fixa, especifique: source="slot", source="svg", source="image" ou source="iconify".

Dependências

Usado por

Gráfico

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

Na versão 1.x, o componente era registrado como br-icon-base e recebia o nome do ícone e da família. Na 2.x, o elemento público é br-icon, com fontes de ícone declaradas pela aplicação.

Propriedades

API 1.x	API 2.x	Ação na migração
—	`label`	Informe uma descrição para ícones que não sejam decorativos.
`br-icon-base`	`br-icon`	Atualize o nome do elemento.
`className`	`cssClasses`	Renomeie quando precisar aplicar classes.
`familyName`	—	Remova e configure a fonte no `src`/SVG ou na integração de ícones da aplicação.
`iconName`	`src`, `svg` ou slot	Prefira uma fonte explícita; `iconName` existe como compatibilidade legada.

Exemplo

1.x:

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

2.x:

<br-icon src="/icons/search.svg" label="Pesquisar"></br-icon>

Visão Geral​

Para que serve​

Quando utilizar​

Estrutura e Slots​

Exemplo(s)​

Propriedades​

cssClasses​

customId​

flip​

focusable​

height​

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

inline​

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

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

label​

lazy​

rotate​

source​

src​

svg​

width​

Slots​

CSS Shadow Parts​

Iconify: compatibilidade legada e migração​

Por que Iconify deixou de ser a opção prioritária​

⚡ Integração com iconify-icon e a propriedade lazy​

Otimização de Renderização (noobserver)​

🔒 Soluções de Uso Offline e CSP (Content Security Policy)​

1. Pré-registro de Ícones pelo Usuário (addIcon / addCollection)​

2. Direcionar para uma API auto-hospedada (addAPIProvider)​

🚀 Guia de Migração para as APIs Recomendadas​

Opção A: Caminho por arquivo local ou URL (src)​

Opção B: SVG Inline (svg)​

Opção C: Injeção por Slot Padrão (Slot)​

📏 Dimensionamento, Alinhamento e Estilos​

🔀 Ordem Automática de Renderização (source="auto")​

Dependências​

Usado por​

Gráfico​

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

Propriedades​

Exemplo​

Visão Geral

Para que serve

Quando utilizar

Estrutura e Slots

Exemplo(s)

Propriedades

cssClasses

customId

flip

focusable

height

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

inline

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

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

label

lazy

rotate

source

src

svg

width

Slots

CSS Shadow Parts

Iconify: compatibilidade legada e migração

Por que Iconify deixou de ser a opção prioritária

⚡ Integração com `iconify-icon` e a propriedade `lazy`

Otimização de Renderização (`noobserver`)

🔒 Soluções de Uso Offline e CSP (Content Security Policy)

1. Pré-registro de Ícones pelo Usuário (`addIcon` / `addCollection`)

2. Direcionar para uma API auto-hospedada (`addAPIProvider`)

🚀 Guia de Migração para as APIs Recomendadas

Opção A: Caminho por arquivo local ou URL (`src`)

Opção B: SVG Inline (`svg`)

Opção C: Injeção por Slot Padrão (Slot)

📏 Dimensionamento, Alinhamento e Estilos

🔀 Ordem Automática de Renderização (`source="auto"`)

Dependências

Usado por

Gráfico

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

Propriedades

Exemplo