Defina o gráfico uma vez em um <symbol> SVG e, em seguida, faça referência ao ID dele com <use> dentro de cada SVG visível. Defina um tamanho próprio para cada instância e deixe o CSS organizar o restante da página. Estrutura do documento SVG.

Este tutorial é para quem edita uma página HTML em um Mac e quer exibir o mesmo pequeno gráfico ao lado de vários rótulos de texto. O exemplo completo usa blocos fictícios, HTML comum e CSS. Não precisa de framework, JavaScript, arte baixada nem etapa de compilação.

Como um símbolo produz vários gráficos visíveis?

Um <symbol> é um modelo gráfico. Ele não é exibido por conta própria; uma referência <use> cria uma instância visível. Coloque a definição uma vez no documento e, em seguida, adicione um pequeno elemento SVG onde o gráfico deve aparecer. A MDN documenta ambos os elementos como amplamente disponíveis. MDN: symbol.

A distinção importante é entre evitar repetir caminhos escritos no código e evitar o trabalho de renderização do navegador. Seu HTML contém uma definição de caminho, mas o navegador ainda cria uma instância renderizada para cada <use>. A MDN descreve isso como uma clonagem em um DOM não exposto. A reutilização facilita a manutenção do código-fonte; isso não significa que vários gráficos visíveis se tornem um único objeto renderizado. MDN: use.

Em uma página com rótulos e ícones, mantenha os rótulos em HTML e dê a cada ícone seu próprio elemento SVG. O WHATWG reconhece o SVG como conteúdo incorporado, de frase e de fluxo no HTML, o que permite posicionar esses elementos entre o conteúdo comum da página. Padrão HTML: SVG.

Crie uma página completa com uma definição e três instâncias

Em um editor de texto simples no Mac, crie um arquivo chamado svg-reuse.html. Cole o documento completo abaixo, salve-o e abra-o no navegador do computador. Mantenha a extensão .html e salve como texto simples, não como um documento de texto formatado.

O exemplo define dois blocos diagonais usando um único <path>. Três referências exibem a mesma geometria em tamanhos e cores diferentes. Cada referência usa href="#demo-tiles"; href sem o prefixo é a forma atual, enquanto xlink:href está obsoleto. MDN: atributos de use.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Reusable tile symbol</title>
  <style>
    body {
      margin: 2rem;
      font-family: system-ui, sans-serif;
      color: #263445;
    }
    .symbol-bank {
      position: absolute;
      width: 0;
      height: 0;
      overflow: hidden;
    }
    .samples {
      display: flex;
      flex-wrap: wrap;
      gap: 1.5rem;
    }
    .sample {
      display: flex;
      align-items: center;
      gap: 0.75rem;
      padding: 1rem;
      border: 1px solid #cbd5df;
    }
    .icon {
      display: block;
      width: 24px;
      height: 24px;
      flex: none;
    }
    .icon-large { width: 48px; height: 48px; }
    .icon-medium { width: 32px; height: 32px; }
    .blue { color: #2457a7; }
    .purple { color: #7140a0; }
  </style>
</head>
<body>
  <svg class="symbol-bank" width="0" height="0" aria-hidden="true">
    <symbol id="demo-tiles" viewBox="0 0 24 24"
            preserveAspectRatio="xMidYMid meet">
      <path fill="currentColor"
            d="M4 4H10V10H4Z M14 14H20V20H14Z"></path>
    </symbol>
  </svg>

  <main>
    <h1>Tile samples</h1>
    <div class="samples">
      <div class="sample">
        <svg class="icon" width="24" height="24"
             viewBox="0 0 24 24" aria-hidden="true">
          <use href="#demo-tiles" width="24" height="24"></use>
        </svg>
        <span>Small tiles</span>
      </div>

      <div class="sample blue">
        <svg class="icon icon-large" width="48" height="48"
             viewBox="0 0 24 24" aria-hidden="true">
          <use href="#demo-tiles" width="24" height="24"></use>
        </svg>
        <span>Large tiles</span>
      </div>

      <div class="sample purple">
        <svg class="icon icon-medium" width="32" height="32"
             viewBox="0 0 24 24" aria-hidden="true">
          <use href="#demo-tiles" width="24" height="24"></use>
        </svg>
        <span>Medium tiles</span>
      </div>
    </div>
  </main>
</body>
</html>

O resultado esperado são três amostras com bordas contendo os mesmos blocos diagonais. A primeira usa a cor do texto do corpo, a segunda é azul e a terceira, roxa. As caixas SVG medem 24, 48 e 32 pixels CSS de lado. Reduza a largura da janela do navegador para verificar como as amostras se reorganizam em linhas.

As formas visíveis são decorativas neste caso, pois os rótulos adjacentes fornecem o conteúdo. Por isso, os elementos SVG usam aria-hidden="true". Isso os remove da árvore de acessibilidade sem ocultá-los visualmente. Use esse tratamento para gráficos decorativos; não o aplique a uma imagem que contenha informações ausentes do texto. MDN: aria-hidden.

Quais configurações controlam o layout da página e o layout SVG?

Há três tarefas distintas: organizar os componentes HTML, dimensionar cada caixa SVG e mapear o desenho para essa caixa. Alterar a configuração de uma tarefa pode deixar as outras duas inalteradas.

Tarefa Configuração no exemplo O que alterar
Organizar as amostras na página .samples usa flexbox e permite quebra de linha Altere o espaçamento ou a quebra de linha aqui
Alinhar cada gráfico ao rótulo .sample usa flexbox e align-items: center Altere aqui o alinhamento do componente
Definir o tamanho da caixa SVG exibida .icon e suas classes de tamanho Altere aqui a largura e a altura em CSS
Definir as coordenadas do desenho viewBox="0 0 24 24" Altere isso quando os limites das coordenadas da arte mudarem
Dimensionar internamente o símbolo referenciado <use> tem largura e altura de 24 Mantenha esses valores compatíveis com a área de coordenadas interna deste exemplo
Ajustar proporcionalmente o desenho preserveAspectRatio="xMidYMid meet" Altere isso somente se quiser um comportamento de ajuste diferente

O Flexbox organiza os filhos diretos de um contêiner flexível. Assim, o contêiner externo organiza as amostras, e cada contêiner interno organiza um SVG ao lado de um rótulo. O Flexbox funciona em uma dimensão por vez; o espaço das linhas quebradas é distribuído de forma independente. Para um design que exige linhas e colunas coordenadas, o CSS Grid é a alternativa relevante para o layout da página. MDN: conceitos básicos do flexbox.

Dentro do SVG, <use> tem um modelo de layout diferente. Seus valores x e y deslocam os gráficos no sistema de coordenadas SVG. Eles não definem o espaçamento entre componentes HTML. A largura e a altura podem dimensionar a área de visualização de um símbolo referenciado; não são um controle geral de escala para um caminho ou grupo referenciado diretamente. W3C: Layout de gráficos reutilizados.

Por que a instância maior ainda usa dimensões internas de 24?

O viewBox do SVG externo descreve uma área de coordenadas de 24 por 24. A caixa CSS pode medir 48 por 48 pixels, enquanto as coordenadas internas permanecem inalteradas. O <use> preenche essa área interna de 24 por 24, e o SVG externo a mapeia para a caixa maior exibida. A MDN define viewBox como quatro números: x mínimo, y mínimo, largura e altura. MDN: viewBox.

Para um cálculo ilustrativo com esta arte exata, uma caixa de 48 pixels mapeia 24 unidades de coordenadas a uma escala de 48 / 24 = 2. A geometria dos blocos abrange as coordenadas de 4 a 20, então a extensão total pintada fica com (20 - 4) × 2 = 32 pixels. O espaço restante vem das margens intencionais dentro do desenho.

Isso explica por que aumentar a largura CSS de um ícone não necessariamente faz com que sua forma pintada ocupe toda essa largura. Verifique os limites da geometria dentro do viewBox antes de ajustar as margens da página para compensar.

O que acontece em uma caixa SVG retangular?

Com xMidYMid meet, o desenho é escalado uniformemente, permanece centralizado e cabe inteiro na área de visualização disponível. Portanto, um desenho quadrado em um retângulo largo deixa espaço nas laterais. none permite distorção; slice preserva as proporções, mas deixa parte do viewBox ultrapassar a área de visualização. Use meet quando o gráfico completo precisar permanecer visível. MDN: preserveAspectRatio.

Como cada instância pode ter sua própria cor?

O caminho usa fill="currentColor". Essa palavra-chave assume o valor de color do elemento, permitindo que o mesmo desenho acompanhe a cor do texto ao redor. No exemplo, alterar a regra .blue ou .purple muda tanto o rótulo quanto seus blocos. MDN: palavra-chave currentColor.

Isso funciona por meio da herança em cada instância. O modelo de reutilização do SVG aplica ao conteúdo gerado estilos herdados do elemento <use> hospedeiro. Uma cor fixa declarada diretamente no caminho de origem tem precedência sobre um preenchimento herdado fornecido por um elemento pai. Mantenha a geometria compartilhada sem cores fixas quando precisar de cores diferentes por instância. W3C: Escopo e herança de estilos.

Evite depender de um seletor como .blue path para alcançar um caminho gerado por meio do elemento visível. O conteúdo gerado pertence à árvore shadow de reutilização, por isso as relações entre ancestrais diferem das do HTML aninhado comum. Defina color no elemento ou contêiner e mantenha currentColor na geometria de origem. W3C: Escopo e herança de estilos.

O que verificar quando um símbolo reutilizado parece incorreto?

Comece pela referência e vá para fora. Esta sequência distingue um gráfico ausente de um gráfico dimensionado ou posicionado incorretamente, para que cada ajuste resolva um mecanismo específico.

  1. Verifique o destino. Confirme que href="#demo-tiles" corresponde ao id="demo-tiles" da definição. Mantenha esse ID único na árvore do documento. W3C: atributo id.
  2. Verifique as dimensões do elemento visível. Mantenha a classe .symbol-bank com tamanho zero somente no contêiner da definição. Cada instância visível precisa de uma caixa diferente de zero, como mostra .icon.
  3. Verifique os limites das coordenadas. Confirme que a arte cabe no viewBox declarado. Espaço vazio inesperado pode resultar de coordenadas de desenho não utilizadas. MDN: viewBox.
  4. Verifique o tipo do elemento referenciado. Se você substituiu o símbolo por uma referência direta a um caminho, alterar a largura e a altura de <use> não o dimensionará da mesma forma. Para este padrão, restaure o símbolo e seu viewBox. MDN: use.
  5. Verifique as declarações de cor. Procure cores fixas na origem antes de adicionar mais seletores para as instâncias.
  6. Verifique o contêiner da página. Se o gráfico for renderizado corretamente, mas estiver longe demais do rótulo, ajuste o espaçamento ou o alinhamento CSS do componente. MDN: conceitos básicos do flexbox.

Ao integrar o exemplo a uma página existente, insira o banco de símbolos uma vez, combine o CSS e copie apenas o elemento SVG visível para os outros componentes. O pequeno documento passou por verificações estruturais de elementos balanceados, IDs únicos e três referências apontando para uma definição de caminho; essas verificações não confirmam a renderização no navegador. Abra a página nos navegadores para Mac que pretende suportar e inspecione o tamanho, o espaçamento e a cor resultantes.

Para alterar o desenho compartilhado, edite sua única definição de caminho. Para alterar uma instância, edite o tamanho do elemento ou a cor herdada. Manter essas responsabilidades separadas oferece arte reutilizável e controle previsível sobre onde cada instância aparece.

Fontes