SVG symbol and use: reuse artwork without copying paths

Define once, place several instances

Use a symbol to define a reusable piece of SVG artwork and a use element to place an instance of it. Editing the source geometry then changes every instance that references that definition. This is useful for repeated map markers, diagram components or icons that should stay consistent.

A symbol is a template, not an automatically visible shape. Give it a unique id, put the geometry inside it and reference that id from use. A document containing only the definition can be valid while displaying no artwork. This explains a different failure from a path that exists outside the visible canvas.

The MDN symbol reference describes template behaviour.

Start with a complete, self-contained example

The example below defines one location marker in a 24 by 24 coordinate system. Two use elements give it different positions, sizes and colours. The outer viewBox describes the whole drawing; the symbol viewBox describes the reusable component. Keep those two coordinate systems separate when troubleshooting.

The marker uses currentColor for its fill and inherits the colour chosen for each instance. The complete outer image has a title and an accessible name. This describes the two-marker illustration as one image; a row of interactive controls would need appropriate names and semantics on those controls instead.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 100"
     width="540" height="300" role="img" aria-labelledby="markers-title">
  <title id="markers-title">Two location markers in blue and green</title>
  <defs>
    <symbol id="pin" viewBox="0 0 24 24">
      <path fill="currentColor"
            d="M12 2 C7 2 4 6 4 10 C4 16 12 22 12 22
               C12 22 20 16 20 10 C20 6 17 2 12 2 Z"/>
      <circle cx="12" cy="10" r="3" fill="white"/>
    </symbol>
  </defs>
  <use href="#pin" x="16" y="26" width="48" height="48" color="#2563eb"/>
  <use href="#pin" x="88" y="14" width="72" height="72" color="#087f5b"/>
</svg>

Choose instance dimensions deliberately

The MDN use reference explains that width and height affect the instance when the referenced element defines a viewBox, as a symbol or svg can. Setting width on an instance of an ordinary path does not provide the same viewport-scaling mechanism. Use a symbol with a viewBox when you want a predictable reusable component size.

In this example, changing the first instance from 48 by 48 to 72 by 48 creates a wider viewport around the square symbol. The normal aspect-ratio fitting behaviour preserves the marker’s proportions. If the artwork appears too small or offset, check the symbol’s internal bounds before changing the outer document’s canvas.

Understand which attributes belong to the template

If the template itself fixes a fill such as fill="red", setting a different fill on use may not override that value. MDN documents this inheritance limitation. Decide which properties are shared geometry and which are intended to vary per instance. A deliberate currentColor pattern is easier to reason about than competing hardcoded fills.

Do not assume that a page selector can reach every cloned descendant as though you had pasted an ordinary group into the document. Keep the first test simple: local references, presentation attributes and one property change at a time. Once the example works, apply the pattern to a small copy of your real asset.

See the MDN use reference for sizing, inheritance and external-reference restrictions.

Keep references intact when moving the file

A local reference such as href="#pin" points to an id inside the same document. An external reference such as href="icons.svg#pin" also depends on another resource and its location. MDN notes that browsers can restrict cross-origin use references. Test external sprites from the actual deployment origin instead of treating a local preview as proof.

For a self-contained deliverable, include the necessary definitions in the SVG that you hand off. Make ids unique when combining several drawings on one page, and update every matching reference if you rename a definition. Removing defs because it contains no directly visible artwork can remove the source that makes all the instances work.

Check the exported result in its real destination

An SVG editor may preserve a reference without exposing every instance as an independently editable path. SVG Vector Lab is useful for inspecting source and working on supported geometry, but do not assume that importing a sprite automatically expands every symbol into editable nodes. Keep the original and verify the exported source and appearance.

Open the final SVG in the browser or application that will consume it. Confirm that both instances appear, their colours and sizes differ as intended, and no external resource is missing. If you also need PNG, inspect the raster export separately: it records the rendered image and does not preserve reusable SVG definitions.

Try the example, then check the next dependency

Open the SVG editor with a copy of your artwork. For canvas sizing, use the viewBox guide; for naming meaningful graphics, read SVG accessibility. Check the source, preview and exported file as separate steps.