Skip to content
Tutorials Center
My learning

Topics

HTML Reference ยท SVG

SVG structural elements

Reference for SVG structure: grouping with g, definitions in defs, reusable symbol icons and use, nested svg viewports, viewBox and preserveAspectRatio values.

Structural elements organize an SVG drawing instead of painting anything themselves. <g> groups shapes so they share styles and transforms, <defs> holds things that are only drawn when referenced, <symbol> defines a reusable graphic with its own coordinate system, and <use> draws a copy of any of them. A nested <svg> creates a new viewport inside a drawing.

Together they let you build an icon set once and stamp it out anywhere on the page:

HTML
<svg width="0" height="0" style="position: absolute">
  <symbol id="icon-check" viewBox="0 0 24 24">
    <path d="M4 12 L10 18 L20 6" fill="none" stroke="currentColor" stroke-width="3"/>
  </symbol>
</svg>

<svg width="24" height="24" aria-hidden="true"><use href="#icon-check"/></svg>

Try it

An icon sprite with symbol and use

Each icon is drawn with currentColor, so it takes the text color of wherever it is used, including the button's hover color. Because the icons are sized in em, they also grow with the font size.

Elements

Element Rendered? Purpose
<g> Yes Groups children. Presentation attributes and transform on the group apply to every child.
<defs> No A container for definitions: gradients, patterns, clip paths, masks, markers, filters and shapes that are only drawn through <use>.
<symbol> No (only through <use>) A reusable graphic with its own viewBox, like a template.
<use> Yes Draws a copy of another element (a shape, a <g>, a <symbol> or an <svg>) found by its ID.
<svg> (nested) Yes A new viewport at x, y with its own size, viewBox and clipping.
<title> No (tooltip) The accessible name of its parent; browsers show it as a tooltip.
<desc> No A longer accessible description of its parent.
<switch> Yes Draws only the first child whose conditions (systemLanguage, requiredExtensions) match. Rarely needed.

Attributes

Element Attribute Values Description
<use> href #id, or file.svg#id The element to copy. A file must be same-origin (or served with CORS where supported). The old xlink:href still works but is deprecated.
x, y Length Moves the copy, like an extra translate(x, y).
width, height Length Only used when the referenced element is a <symbol> or <svg>: the size of its viewport. Default 100%.
<symbol> viewBox min-x min-y width height The symbol's own coordinate system, scaled to the size given by <use>.
preserveAspectRatio See the table below How the viewBox fits the viewport.
x, y, width, height Length Default position and size of the viewport (SVG 2); <use> can override width and height.
refX, refY Length or left/center/right, top/center/bottom A reference point that is placed at the <use> position (SVG 2).
<svg> (nested) x, y Length Position of the inner viewport in the parent's coordinates.
width, height, viewBox, preserveAspectRatio Size and coordinate system of the inner viewport. Content outside it is clipped unless overflow="visible".
<g> (none of its own) Takes presentation attributes, transform, class, id, style and ARIA attributes.

viewBox and preserveAspectRatio

viewBox="min-x min-y width height" defines which area of the drawing's coordinate space is shown; the browser scales that area to the element's actual size. When the shapes of the two boxes differ, preserveAspectRatio decides what happens. Its value is an alignment and, optionally, meet or slice:

Value Meaning
xMidYMid meet The default. Scale evenly so the whole viewBox fits, then center it. Empty space appears on two sides.
x{Min,Mid,Max}Y{Min,Mid,Max} The nine alignments: which edge or center of the viewBox lines up with the viewport on each axis, for example xMinYMax = bottom-left.
โ€ฆ meet Scale so the viewBox fits entirely (like CSS object-fit: contain).
โ€ฆ slice Scale so the viewBox covers the viewport entirely; the overflow is cut off (like object-fit: cover).
none Scale each axis separately so the viewBox fills the viewport exactly. Circles become ellipses.
preserveAspectRatio side by side

The same 100 ร— 100 drawing (yellow square, orange circle) is placed in wide boxes. With meet the whole square is visible and the alignment decides where the spare space goes; with slice the square fills the width and its top and bottom are cut; none stretches it.

Groups, nested viewports and use

g, a nested svg and use with x and y

The tree is defined around its own origin (0,0 is the base of the crown), so x and y on each <use> place it like a stamp. In the nested <svg>, a circle of radius 6 in a 10-unit viewBox is bigger than its viewport, so its edges are clipped.

Styling copies made by use

The content drawn by <use> lives in a closed shadow tree. Selectors in the page's CSS can't reach the elements inside it (.icon path matches nothing in the copy), but inherited properties flow in from the <use> element: fill, stroke, color, font properties and CSS custom properties. Leave those unset inside the symbol, or set them to currentColor or var(--name), and each copy can be styled differently.

Two-tone icons with custom properties

Usage notes

  • <defs> vs display: none. Put gradients, patterns and other definitions in <defs>. A sprite <svg> holding symbols should be hidden with width="0" height="0" and position: absolute, not display: none: in some browsers gradients inside a display: none SVG stop working.
  • IDs are page-wide. Every id inside inline SVG shares the HTML document's ID space. Two copies of the same inline SVG with id="grad" will both use the first one.
  • External sprites. <use href="/icons.svg#star"> keeps icons cached in one file, but the file must come from the same origin. It does not work across origins, so it fails from a CDN on another domain.
  • Accessibility. Hide decorative icons with aria-hidden="true" on the outer <svg>. For an icon that carries meaning on its own (an icon-only button), give the button an aria-label; for a standalone graphic use role="img" and an accessible name.
  • Transforms on groups. A transform on <g> moves the whole group; children's own transforms are applied inside it. See SVG presentation attributes.
  • Events. Events on the copy made by <use> are reported with the <use> element as their target, not the shape inside the shadow tree.

Technical summary

Permitted content <g>, <defs>, <symbol>, nested <svg>: any SVG content (shapes, text, containers, definitions). <use>: descriptive and animation elements only
Permitted parents <svg> and other SVG container elements; <symbol> is typically a child of <svg> or <defs>
Tag omission End tags required (or self-closing, such as <use โ€ฆ />)
Implicit ARIA role <g>: group when it has an accessible name, otherwise none; <use>: graphics-object when named; <defs> and <symbol>: not exposed
DOM interface SVGGElement, SVGDefsElement, SVGSymbolElement, SVGUseElement, SVGSVGElement, SVGTitleElement, SVGDescElement, SVGSwitchElement

Browser support

All of these elements are supported in every browser. Plain href on <use> (instead of xlink:href) works in all current browsers. The SVG 2 refX/refY and size attributes on <symbol> have less consistent support.