Ícones no Angular

Instalação

npm install glyphfox glyphfox-angular

O glyphfox-angular é publicado no formato de pacote do Angular, gerado com ng-packagr, e usa o glyphfox para os dados dos ícones e o motor de renderização. A peer dependency dele é @angular/core 17 ou mais recente, porque os inputs dependem de transformações de input como booleanAttribute.

Registre ícones com provideGlyphFox

O gf-icon busca os ícones pelo nome, então registre os que os seus templates usam. Cada ícone é um export nomeado de dados do glyphfox: home é iconHome, arrow-right é iconArrowRight.

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { iconCheck, iconFile, iconHome, iconMenu, iconSave, iconSearch, iconX } from 'glyphfox';
import { provideGlyphFox } from 'glyphfox-angular';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideGlyphFox({
      icons: [iconHome, iconSearch, iconFile, iconMenu, iconX, iconSave, iconCheck],
      defaults: { weight: 1.75 },
    }),
  ],
};

defaults vale para todo gf-icon abaixo desse injector, e um input no elemento tem prioridade sobre o padrão. Várias chamadas de provideGlyphFox no mesmo injector se somam: todos os ícones delas são registrados e os padrões são mesclados em ordem. provideGlyphFoxIcons(icons) é a forma curta quando você só registra ícones.

Para deixar todos os ícones disponíveis por nome, passe o objeto completo: import { icons } from 'glyphfox' e provideGlyphFox({ icons }). Isso coloca os dados de todos os 419 ícones no bundle que carrega o provider, cerca de 105 KB minificados e 25 KB com gzip, então reserve essa opção para protótipos e ferramentas internas. Dois exports nomeados de dados custam bem menos de 1 KB.

Use o gf-icon

import { Component, signal } from '@angular/core';
import { GlyphFoxIcon } from 'glyphfox-angular';

@Component({
  selector: 'app-toolbar',
  standalone: true, // the default from Angular 19
  imports: [GlyphFoxIcon],
  template: `
    <a href="/" aria-label="Home"><gf-icon name="home" /></a>
    <gf-icon name="search" size="20" />
    <gf-icon name="file+check@tr" variant="duotone" secondaryColor="#ff7a1a" />
    <button type="button" aria-label="Menu" [attr.aria-expanded]="open()" (click)="open.set(!open())">
      <gf-icon name="menu" morphTo="x" trigger="state" [active]="open()" />
    </button>
  `,
})
export class Toolbar {
  readonly open = signal(false);
}

Os inputs usam os nomes de props em camelCase: secondaryColor, modifierCorner, flipX. Strings estáticas funcionam em todos os inputs, inclusive nos numéricos (size="20" vira o número 20), e os inputs booleanos aceitam o atributo sem valor, então <gf-icon name="arrow-right" mirrorRtl /> espelha a seta em layouts da direita para a esquerda.

class e style vão para o host gf-icon, uma caixa inline flex em volta do svg. Os traços usam currentColor, então o color do CSS no host ou em qualquer elemento pai dá cor ao ícone, e o input color define a cor diretamente.

Modificadores, estilos e fusão

name aceita a sintaxe de nomes completa. file+check adiciona um selo, @tl, @tr, @bl ou @br escolhe o canto dele, e heart/solid escolhe um estilo. Os selos são desenhados pelo motor, então só o ícone base precisa ser registrado. Para uma fusão, passe as partes para [icons] e escolha um layout.

<gf-icon name="cloud+sync@tr" />
<gf-icon name="heart/solid" color="#e5484d" />
<gf-icon [icons]="['cloud', 'lock']" layout="overlap" [gap]="1" />
<gf-icon [icons]="['user', 'shield']" layout="badge" />
<gf-icon [icons]="['file', 'image', 'music', 'video']" layout="grid" />

Uma fusão é resolvida por nome como qualquer outro ícone, então todas as partes precisam estar registradas. O resultado segue weight, variant e os outros inputs e, onde as partes se sobrepõem, a de trás é recortada em volta da da frente. Os layouts são overlap, side, stack, grid, orbit, badge e inside.

Dados de ícone em vez de nomes

O input icon recebe dados de ícone diretamente e ignora o registro, o que combina com ícones escolhidos no código a partir de um mapa fixo.

import { Component, computed, input } from '@angular/core';
import { iconFile, iconFileCode, iconFileImage, iconFileText } from 'glyphfox';
import { GlyphFoxIcon } from 'glyphfox-angular';

const byType = { code: iconFileCode, image: iconFileImage, text: iconFileText };
type FileType = keyof typeof byType;

@Component({
  selector: 'app-file-row',
  standalone: true,
  imports: [GlyphFoxIcon],
  template: `<gf-icon [icon]="icon()" size="18" /> {{ name() }}`,
})
export class FileRow {
  readonly name = input.required<string>();
  readonly type = input<FileType | null>(null);
  readonly icon = computed(() => {
    const type = this.type();
    return type ? byType[type] : iconFile;
  });
}

Ícones em rotas lazy

provideGlyphFox devolve environment providers, então também funciona nos providers de uma rota. Declarados num arquivo de rotas carregado sob demanda, os ícones de uma feature vão junto com o chunk lazy em vez de ir para o bundle principal.

import { iconHome, iconMenu, iconSearch, iconX } from 'glyphfox';
import type { GlyphFoxConfig } from 'glyphfox-angular';

export const sharedIcons = {
  icons: [iconHome, iconSearch, iconMenu, iconX],
  defaults: { weight: 1.75 },
} satisfies GlyphFoxConfig;

import { Routes } from '@angular/router';

export const routes: Routes = [
  { path: 'billing', loadChildren: () => import('./billing/billing.routes').then((m) => m.BILLING_ROUTES) },
];

import { Routes } from '@angular/router';
import { iconCreditCard, iconReceipt, iconWallet } from 'glyphfox';
import { provideGlyphFox } from 'glyphfox-angular';
import { sharedIcons } from '../icons';
import { BillingPage } from './billing.page';

export const BILLING_ROUTES: Routes = [
  {
    path: '',
    providers: [
      provideGlyphFox({ ...sharedIcons, icons: [...sharedIcons.icons, iconCreditCard, iconReceipt, iconWallet] }),
    ],
    component: BillingPage,
  },
];

Uma rota que chama provideGlyphFox ganha a própria configuração. O Angular não mescla multi providers entre injectors, então os componentes abaixo dessa rota leem só a chamada da rota, incluindo os padrões dela. Fazer spread de um objeto compartilhado, como no exemplo acima, mantém os ícones e os padrões da raiz.

Renderização no servidor e hidratação

O gf-icon escreve o svg por meio do Renderer2, então com o SSR ou a pré-renderização do Angular o ícone já está no HTML, e o navegador redesenha o mesmo markup quando o componente é inicializado. O servidor não tem requestAnimationFrame: lá, um morph vai direto para o valor final, e um morph com o gatilho padrão (mount) só toca quando o app inicia no navegador.

Registre todos os ícones que o servidor renderiza. Um nome não registrado é buscado com um import dinâmico, e essa requisição ainda pode estar pendente quando o servidor serializa a página, o que deixa um ícone vazio no HTML até a hidratação preenchê-lo.

O mesmo carregador explica um detalhe dos builds de produção: a saída lista um chunk pequeno por ícone, porque o builder empacota todos os destinos possíveis desse import dinâmico. Esses chunks só são baixados para nomes que você não registrou.

OnPush, signals e apps zoneless

O gf-icon usa OnPush e desenha o próprio svg sempre que um input muda, nos gatilhos de hover e click e em cada frame de um morph. Ele não depende do zone.js, então funciona em apps zoneless, e signals fazem binding como qualquer outro valor: [active]="saved()".

import { Component, signal } from '@angular/core';
import { GlyphFoxIcon } from 'glyphfox-angular';

@Component({
  selector: 'app-save-button',
  standalone: true,
  imports: [GlyphFoxIcon],
  template: `
    <button type="button" (click)="save()">
      <gf-icon name="save" morphTo="check" trigger="state" [active]="saved()" [duration]="300" />
      {{ saved() ? 'Saved' : 'Save' }}
    </button>
  `,
})
export class SaveButton {
  readonly saved = signal(false);

  save() {
    this.saved.set(true);
    setTimeout(() => this.saved.set(false), 1500);
  }
}

Os presets de estados vivos funcionam do mesmo jeito: <gf-icon name="bell" animate="shake" trigger="state" [active]="hasNews()" /> balança o sino enquanto o signal for verdadeiro, e animate="spin" em loader-circle cria um spinner. As animações são CSS dentro do svg e param com movimento reduzido; o guia de ícones animados lista todos os presets e gatilhos.

Inputs

Cada prop compartilhada é um input com o mesmo nome e o mesmo significado que tem nos outros pacotes do glyphfox.

Além das props compartilhadas, o gf-icon aceita name (qualquer spec), icon (dados de ícone), icons (de 2 a 10 partes de uma fusão), layout e gap.

Armadilhas comuns

provideGlyphFox num componente

Ele devolve environment providers, que pertencem à configuração da aplicação, a um NgModule ou a uma rota. O Angular recusa esses providers nos providers de um componente.

Uma rota lazy perde os padrões da raiz

Os providers da rota substituem a configuração de tudo o que está abaixo dela, porque multi providers não são mesclados entre injectors. Faça spread de um objeto de configuração compartilhado em cada chamada.

aria-label no host

Um aria-label no gf-icon faz o svg interno deixar de ser decorativo (role="img"), mas o rótulo fica no elemento host, que não tem role, então os leitores de tela podem não anunciar nada. Use o input title para um ícone com significado, ou coloque o rótulo no botão pai e mantenha o ícone decorativo.

Uma fusão que nunca aparece

Se uma parte de [icons] não estiver registrada, a fusão inteira espera por ela e fica vazia enquanto isso, inclusive no servidor. Registre todas as partes.

Registrar o conjunto inteiro sem querer

provideGlyphFox({ icons }) com o objeto completo de glyphfox mantém todos os ícones no bundle. Em vez disso, importe os exports nomeados de dados de que você precisa.