> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

# Ícones SVG no Mermaid: registre sua própria arte

> Empacote sua arte SVG em um conjunto Iconify, registre-o no Mermaid e teste ícones ausentes, formas recortadas e rótulos com um exemplo funcional de diagrama.

Source: https://perfectvector.com/pt-BR/blog/mermaid-custom-svg-icons

Language: pt-BR
Author: Irene Kim
Published: 2026-09-25T08:00:00+09:00

Para usar seu próprio ícone SVG no Mermaid, coloque seu conteúdo de desenho e suas dimensões de coordenadas em um conjunto de ícones Iconify, chame `mermaid.registerIconPacks()` e referencie o nome registrado no diagrama. Um nome de arquivo SVG sozinho não registra um ícone.

Este fluxo atende a uma página ou aplicação em que você controla o JavaScript do Mermaid. Um editor Markdown hospedado pode expor apenas o texto do diagrama, portanto confira suas opções de integração antes de preparar uma coleção inteira de ícones. Comece com um pictograma simples e um conector. Mantenha os rótulos do diagrama no Mermaid para que permaneçam separados da arte.

## Confira onde você pode registrar o pacote

A [API de registro do Mermaid](https://mermaid.ai/open-source/config/icons.html) aceita um conjunto de ícones diretamente ou um carregador que retorne um. O `name` registrado se torna o prefixo usado no diagrama. Neste exemplo, o pacote é `garden` e seu ícone é `leaf`, resultando na referência `garden:leaf`.

O registro pertence ao JavaScript que prepara o renderizador. Colar esse JavaScript em um bloco de código Mermaid não é a mesma operação. Se a plataforma de publicação não permitir configurar seu renderizador, use os conjuntos de ícones compatíveis com ela ou renderize o diagrama em um fluxo que você controla e insira o resultado exportado. Guarde a origem Mermaid junto desse resultado para edições futuras.

Neste passo a passo, use uma página HTML comum servida por HTTP local. Ela carrega um módulo Mermaid 12.0.0 com versão fixada de uma CDN e, portanto, precisa de acesso à rede. Uma aplicação de produção pode empacotar a versão Mermaid escolhida. Teste essa versão e a política de segurança de conteúdo da hospedagem antes de adotar o exemplo.

## Preserve as coordenadas de desenho do SVG

Aqui está a folha original usada em nosso teste. Salve-a como `leaf.svg` se quiser inspecionar a arte separadamente:

```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 24">
  <path fill="#167c72"
    d="M3 19C1 5 14 2 29 3C29 17 17 25 3 19Z"/>
  <path fill="none" stroke="#d7f1ca" stroke-width="1.8"
    d="M5 18L23 7"/>
</svg>
```

O [campo `body` do Iconify](https://iconify.design/docs/types/iconify-icon.html) contém o conteúdo dentro da raiz SVG, sem o elemento externo `<svg>`. O retângulo de coordenadas é informado separadamente como `left`, `top`, `width` e `height`. Para este arquivo, a origem é zero e as dimensões são 32 por 24.

Não copie o tamanho CSS renderizado. Um arquivo exibido com 64 pixels ainda pode ter um `viewBox` de `0 0 32 24`. Seus traçados foram desenhados nesse último sistema de coordenadas. Para uma origem diferente de zero, preserve também os valores correspondentes de `left` e `top`, ou translade deliberadamente a arte para uma área de desenho com origem zero antes de empacotá-la.

Um [conjunto Iconify](https://iconify.design/docs/types/iconify-json.html) contém um `prefix` e um objeto `icons`. Cada chave de ícone nomeia seu desenho. Dimensões explícitas são úteis aqui: se nem o ícone nem o conjunto as fornecerem, os padrões de largura e altura do Iconify são 16. Isso pode recortar arte desenhada para uma área maior.

Se você estiver preparando uma família de pictogramas, finalize primeiro seu contorno, espaçamento e peso visual. Nosso [guia de preparação de kits de interface SVG](https://perfectvector.com/pt-BR/blog/convert-png-icons-to-svg-for-ui-kit) aborda essas decisões da arte de origem. Empacotar um ícone não melhora sua silhueta.

## Execute um exemplo completo de dois nós

Salve o seguinte como `index.html` em uma pasta nova. Se Python estiver disponível, execute `python3 -m http.server 8000` nessa pasta e abra `http://localhost:8000` no navegador.

```html
<!doctype html>
<meta charset="utf-8">
<title>Custom Mermaid leaf icon</title>
<div id="diagram"></div>

<script type="module">
import mermaid from
  'https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.esm.min.mjs';

const icons = {
  prefix: 'garden',
  icons: {
    leaf: {
      width: 32,
      height: 24,
      body: '<path fill="#167c72" d="M3 19C1 5 14 2 29 3C29 17 17 25 3 19Z"/>' +
        '<path fill="none" stroke="#d7f1ca" stroke-width="1.8" d="M5 18L23 7"/>'
    }
  }
};

mermaid.registerIconPacks([{ name: 'garden', icons }]);
mermaid.initialize({ startOnLoad: false, theme: 'neutral' });

const definition = `architecture-beta
  service source(garden:leaf)[Source]
  service library(database)[Library]
  source:R --> L:library`;

const { svg } = await mermaid.render('garden-diagram', definition);
document.querySelector('#diagram').innerHTML = svg;
</script>
```

Você deve ver a folha ao lado de um símbolo de banco de dados, conectados de Source a Library. A folha vem do pacote registrado; `database` é um dos ícones de arquitetura integrados do Mermaid. A [referência de sintaxe de arquitetura](https://mermaid.ai/open-source/syntax/architecture.html) descreve nomes de ícones entre parênteses, rótulos entre colchetes e os lados dos serviços usados pelas arestas.

O exemplo desativa a renderização automática e faz uma chamada explícita `render()` após o registro. Isso deixa a ordem visível durante o teste. Ao integrá-lo a um site existente, garanta que o registro e a chamada de renderização usem a mesma instância Mermaid.

Este é um desenho pequeno e confiável criado para o exemplo. Para uma grande coleção de ícones, use as ferramentas de importação e limpeza do Iconify em vez de presumir que todo SVG exportado possa ser reduzido a uma string de traçados sem trabalho adicional. Fontes, imagens externas, estilos e definições referenciadas merecem uma inspeção separada.

## Compare registro ausente com dimensões ausentes

Renderizamos três cópias deste diagrama em documentos de navegador separados usando Mermaid 12.0.0. A primeira omitiu o registro. A segunda registrou os dois traçados da folha, mas omitiu suas dimensões. A terceira registrou os mesmos traçados com `width: 32` e `height: 24`.

![Três diagramas Mermaid renderizados no navegador mostrando um ponto de interrogação sem registro de ícone, uma folha recortada com dimensões omitidas e uma folha completa com seu espaço de coordenadas de 32 por 24 preservado.](https://perfectvector.com/blog/mermaid-custom-svg-icons/icon-pack-test.webp)

*A mesma folha original no Mermaid 12.0.0. O registro fornece a arte; as dimensões controlam seus limites de coordenadas. Os rótulos e o conector permanecem elementos nativos do diagrama.*

Na primeira renderização, o Mermaid exibiu um ponto de interrogação onde a folha personalizada deveria aparecer. O traçado da folha estava ausente da saída. Na segunda, a saída continha esse traçado dentro de um SVG com `viewBox="0 0 16 16"`, e a folha estava visivelmente recortada. Na terceira, o ícone usou `viewBox="0 0 32 24"` e a folha completa apareceu.

Essas observações descrevem este exemplo e esta versão. Elas não estabelecem que toda hospedagem informe um ícone indisponível da mesma forma. O exemplo também usa traçados SVG criados manualmente; não é um resultado de conversão do PerfectVector.

| O que você vê                                                              | Primeira verificação                             | Próxima etapa útil                                                                                              |
| -------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Ponto de interrogação ou arte personalizada ausente                        | Registro, nome do pacote e chave do ícone        | Faça `garden`, `leaf` e `garden:leaf` corresponderem; confirme que o registro é executado antes da renderização |
| Apenas parte do desenho                                                    | Coordenadas e dimensões do ícone                 | Compare o viewBox de origem com left, top, width e height do ícone                                              |
| O diagrama inteiro falha                                                   | Versão Mermaid, sintaxe e carregamento do módulo | Comece pelo exemplo mínimo completo e inspecione o erro informado                                               |
| O exemplo local funciona, mas o Markdown hospedado falha                   | Controle da hospedagem sobre seu renderizador    | Confira o mecanismo de registro compatível da hospedagem e sua versão Mermaid fixada                            |
| A arte aparece, mas detalhes minúsculos desaparecem no tamanho do diagrama | Complexidade da origem e tamanho visível         | Simplifique a arte ou use um pictograma mais claro                                                              |

Guarde uma cópia funcional do exemplo mínimo antes de adicionar mais ícones. Mude uma propriedade do pacote por vez; caso contrário, uma correção de nome pode esconder um problema separado de tamanho.

## Traga arte raster para o fluxo quando necessário

Se seu pictograma personalizado existe apenas como PNG ou JPG, o [fluxo de clipart para SVG do PerfectVector](https://perfectvector.com/pt-BR/clipart-to-svg) pode ajudar a recuperar contornos editáveis. Recorte uma cópia para o pictograma, confira o resultado vetorial e inspecione a silhueta, os espaços internos e as formas indesejadas de fundo. Depois abra o SVG em um editor e prepare a versão pequena que pretende usar no diagrama.

Guarde esse original SVG editável. Empacote seu conteúdo de desenho e suas coordenadas apenas depois de ele ficar claro no tamanho pretendido de ícone. Um símbolo geométrico simples pode ser mais rápido de redesenhar; uma fotografia pode ficar mais clara como imagem separada. Se você já tem arte SVG adequada, comece pela etapa de empacotamento.

A vetorização não recupera os nomes de serviços, relacionamentos ou direções dos conectores do diagrama. Mantenha-os na origem Mermaid. Para um editor baseado em canvas com comportamento diferente de formas, veja [formas SVG personalizadas no draw.io](https://perfectvector.com/pt-BR/blog/drawio-custom-svg-shape). Para ícones reutilizáveis em uma página web comum, um [sprite de símbolos SVG](https://perfectvector.com/pt-BR/blog/svg-symbol-sprite) é outro caminho de empacotamento. Para diagramas baseados em DOT, confira a [entrega de imagens SVG de nós Graphviz](https://perfectvector.com/pt-BR/blog/graphviz-svg-node-images) para ver se a arte personalizada acompanha o grafo exportado.

Antes de entregar o diagrama, reabra-o pelo fluxo real de publicação. Confirme que o ícone carrega, que a silhueta completa cabe, que ambos os rótulos são legíveis e que o conector aponta na direção certa. Uma renderização local bem-sucedida é a verificação inicial, seguida de uma verificação no destino.

## Perguntas frequentes

**Posso colocar um nome de arquivo SVG dentro de uma referência de ícone Mermaid?**
No fluxo de pacote de ícones registrado, use um nome de pacote e uma chave de ícone, como garden:leaf. Prepare o desenho SVG como dados de ícone e registre esse pacote no JavaScript do renderizador.

**Por que meu ícone Mermaid personalizado está recortado?**
Compare o viewBox de origem com as propriedades de coordenadas dos dados do ícone. Se as dimensões estiverem ausentes tanto do ícone quanto de seu conjunto, os padrões de largura e altura são 16, o que pode ser pequeno demais para o desenho.

**Isso funciona em todo editor Markdown hospedado?**
Não. A hospedagem precisa suportar a sintaxe do diagrama e oferecer uma forma de registrar o pacote necessário, ou já incluí-lo. Teste o destino real de publicação em vez de presumir que ele compartilhe sua configuração local.

## Fontes

1. [Mermaid — Registro de pacotes de ícones](https://mermaid.ai/open-source/config/icons.html) — Documenta dados diretos de ícones, carregadores e nomes de registro.
2. [Mermaid — Diagramas de arquitetura](https://mermaid.ai/open-source/syntax/architecture.html) — Define ícones de serviço, rótulos nativos, ícones integrados e sintaxe de arestas.
3. [Iconify — IconifyIcon](https://iconify.design/docs/types/iconify-icon.html) — Define conteúdo de desenho sem o invólucro SVG e propriedades de coordenadas.
4. [Iconify — IconifyJSON](https://iconify.design/docs/types/iconify-json.html) — Define a estrutura do pacote e os padrões de dimensões herdados pelos ícones.

***

Tem um pictograma apenas raster para seu diagrama? [Prepare um candidato SVG com o PerfectVector](https://perfectvector.com/pt-BR/clipart-to-svg), inspecione sua silhueta e seus espaços, registre um ícone e verifique seus limites e seu rótulo no renderizador Mermaid final.

## Explore

- [Read the HTML article](https://perfectvector.com/pt-BR/blog/mermaid-custom-svg-icons)
- [Importação SVG no Excalidraw: o que fica editável?](https://perfectvector.com/pt-BR/blog/excalidraw-editable-svg.md)
- [Marcadores SVG: pontas de seta que permanecem alinhadas](https://perfectvector.com/pt-BR/blog/svg-custom-markers.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
