iconis

Iconis é uma biblioteca de ícones em SVG inline para uso em projetos web.

• Sem webfont: evita o efeito de “texto virando ícone” causado por atraso de carregamento de fontes ou bundles pesados.
• Leve e previsível: os ícones são simples strings SVG, sem runtime, sem observers e sem dependências extras.
• Tree-shaking friendly: cada ícone é exportado individualmente, permitindo que bundlers modernos incluam apenas os ícones realmente utilizados.
• Excelente para projetos legados ou sensíveis à performance: não depende de loaders, fontes externas ou inicialização assíncrona — ideal para aplicações antigas ou ambientes com restrições de bundle.
• Controle total de estilo: ícones com fill="currentColor" permitem controle de cor via CSS ou Tailwind.
• Exports tipados e documentados com TSDoc: autocomplete e tooltips claros diretamente no editor, facilitando a implementação.

Instalação

npm install @iconis/icons

Uso

A biblioteca suporta dois estilos de import, pensados para atender projetos modernos e projetos legados.

✅ Projetos modernos (Angular 16+, Angular17+, Vite, etc)

Recomendado para projetos novos ou projetos que utilizam:

• Typescript recente
• Com suporte a subpath exports (moduleResolution: "bundler")

import { starRegular } from '@iconis/icons/outlined';
import { cakeRegular } from '@iconis/icons/filled';

⚠️ Projetos legados (Angular 14- / typescript antigo)

Em projetos mais antigos (como Angular 14), o TypeScript não resolve corretamente subpath exports sem ajustes adicionais de configuração.

Nesses casos, utilize o import via namespace, que é totalmente compatível:

import { outlined, filled } from '@iconis/icons';

const stariIconOutline = outlined.starRegular;
const starIconFilled = filled.starRegular;

Esse formato funciona sem necessidade de alterar o tsconfig do projeto.

ℹ️ Sobre o tsconfig e moduleResolution: "bundler"

É possível habilitar o import moderno (@iconis/icons/outlined) em projetos mais antigos ajustando o tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

Atenção: Essa mudança afeta a resolução de módulos do projeto inteiro. É recomendada apenas para projetos novos ou bem controlados. Em projetos legados grandes, o uso do import via namespace costuma ser mais seguro.

Exemplo de uso no Angular

Angular 17+ (com inject moderno)

import { Component, inject } from '@angular/core';
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
import { cakeRegular } from '@iconis/icons/outlined';

@Component({
  selector: 'app-exemplo',
  standalone: true,
  template: `<span class="w-6 h-6 text-slate-600" [innerHTML]="icone"></span>`,
})
export class ExemploComponent {
  private readonly sanitizer = inject(DomSanitizer);

  protected readonly icone: SafeHtml =
    this.sanitizer.bypassSecurityTrustHtml(cakeRegular);
}

Angular versões anteriores (injeção via constructor)

import { Component } from '@angular/core';
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
import { outlined } from '@iconis/icons';

@Component({
  selector: 'app-exemplo',
  template: `<span class="w-6 h-6 text-slate-600" [innerHTML]="icone"></span>`,
})
export class ExemploComponent {
  public readonly icone: SafeHtml;

  constructor(private readonly sanitizer: DomSanitizer) {
    this.icone = this.sanitizer.bypassSecurityTrustHtml(outlined.cakeRegular);
  }
}

Nota: Por ser SVG inline (string), de modo geral basta importar o icone, atrelar a uma variavel (para ser usado no template html) e Sanitizar para aplicar no innerHTML.

Uso em projetos Javascript puro (HTML + JS)

O Iconis não depende de Angular ou TypeScript.
Como os ícones são apenas strings SVG, eles podem ser usados em qualquer projeto JavaScript simples.

Exemplo básico (HTML + JS)

<div id="icone"></div>

<script type="module">
  import { outlined } from '@iconis/icons';

  const container = document.getElementById('icone');
  container.innerHTML = outlined.starRegular;
</script>

Observações importantes

• Em projetos simples, innerHTML pode ser usado diretamente.
• Em aplicações maiores ou com conteúdo dinâmico, sanitize o HTML antes de inserir para evitar riscos de segurança.
• O uso de type="module" é necessário para imports ES modernos.

Exemplo com controle de cor via CSS

<style>
  .icon {
    width: 24px;
    height: 24px;
    color: #0f172a; /* slate-900 */
  }
</style>

<div id="icone" class="icon"></div>

<script type="module">
  import { outlined } from '@iconis/icons';

  document.getElementById('icone').innerHTML = outlined.starRegular;
</script>

Como os ícones utilizam fill="currentColor", a cor é herdada automaticamente via CSS.

Changelog

Veja o histórico de mudanças entre versões em CHANGELOG.md

Licença

MIT © Iconis