Icon
Visão Geral
O componente br-icon fornece uma maneira flexível e dinâmica de incorporar ícones nas aplicações.
Ele aceita arquivos de imagem da aplicação por URL, SVG inline e conteúdo via slot.
Nomes Iconify por iconName continuam disponíveis somente para compatibilidade legada.
Com opções para especificar a altura e largura, adicionar classes CSS personalizadas, e definir como o ícone
deve ser rotacionado ou espelhado, o br-icon oferece aos desenvolvedores as ferramentas necessárias para
integrar ícones de forma consistente com o estilo e design de suas aplicações, melhorando a experiência do usuário
e a clareza das interfaces.
Exemplo(s)
Imagem ou URL (src)
SVG inline (svg)
Slot padrão
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 renderizados pelo br-icon continuam disponíveis
offline como SVG nativo e não carregam essa dependência adicional.
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 propriedadenoobserverno<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,lazycontinua 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:
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ê.
<!-- Modo Iconify -->
<br-icon icon-name="fa6-solid:magnifying-glass"></br-icon>
<!-- Recomendado: asset local controlado pela aplicação -->
<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="fa-solid fa-magnifying-glass" 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). - Iconify legado (propriedade
iconName; atributoicon-nameem HTML).
Para desativar a priorização automática e impor uma origem fixa, especifique:
source="slot", source="svg", source="image" ou source="iconify".
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. |
| 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
| Atributo | icon-name |
|---|---|
| Depreciação | Use src, svg ou o slot padrão. |
| Descrição | |
| 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
| Atributo | is-focusable |
|---|---|
| Depreciação | Use focusable. |
| Descrição | |
| Tipo | boolean |
| Valor padrão | false |
isInline
| Atributo | is-inline |
|---|---|
| Depreciação | Use inline. |
| Descrição | |
| 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 imediatoNota: 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. |
| 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. |
| 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. |
| 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' |
Migração de <br-icon-base> para <br-icon> (1.x → 2.x)
Na branch 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>
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. |
Dependências
Usado por
- br-avatar
- br-breadcrumb
- br-carousel
- br-collapse
- br-cookiebar
- br-cookiebar-group
- br-cookiebar-link
- br-cookiebar-note-group
- br-date-picker
- br-datetime-input
- br-dropdown
- br-footer-social
- br-header
- br-header-function
- br-header-list
- br-input
- br-menu
- br-menu-header
- br-menu-item
- br-menu-link
- br-menu-social
- br-message
- br-modal
- br-notification-header
- br-pagination
- br-select-input
- br-sign-in
- br-step-item
- br-tab
- br-tag
- br-time-picker
- br-tooltip
- br-upload
