The SVG <symbol> element defines reusable graphical content that is rendered only when a <use> element instantiates it. A <symbol> acts like a template with its own coordinate system (similar to a nested <svg>), and the <use> element places an instance of that template into the document. This page covers how the <symbol> attributes (width, height, viewBox, and the rest) affect rendering when a <use> instantiates the symbol: default sizing, coordinate system transformations, and alignment.
A <symbol> element establishes an SVG viewport for its contents.
<symbol> elements are not rendered directly; their width and height define only the symbol's own viewport dimensions. By default, the user agent applies overflow: hidden to symbols, so content outside the symbol's viewport rectangle is clipped. If a symbol has no explicit size, its viewport expands to 100% in whatever context it is placed, and overflow clipping occurs at the bounds of that region.
If the symbol does not have a viewBox, its coordinate system uses the same absolute units as the parent SVG. Setting a width/height on the symbol, or letting it default, defines the clipping region but does not scale the content. The symbol's content is drawn at 1:1 scale in the symbol's own coordinates.
For example:
Without a viewBox, the symbol's coordinates are interpreted directly in the parent user space, and the <use>'s width/height (if any) affect the clipping region, not the content scale.
flowchart TD
question_wh_on_use{"`width/height on <use>?`"}
override_wh["Override <symbol> width/height"]
question_wh_on_symbol{"width/height on <symbol>?"}
sizes_to_viewport["Viewport set to 100% of the parent container or viewport (effectively covering the container)"]
viewport_explicit["Viewport = explicit width/height"]
question_viewBox{"viewBox on <symbol>?"}
viewport_scale["Scale content to placed region<br/>(respect preserveAspectRatio)"]
viewport_no_scale["No scaling"]
%% Flow
question_wh_on_use -- Yes --> override_wh
question_wh_on_use -- No --> question_wh_on_symbol
override_wh --> viewport_explicit
question_wh_on_symbol -- Yes --> viewport_explicit
question_wh_on_symbol -- No --> sizes_to_viewport
viewport_explicit --> question_viewBox
sizes_to_viewport --> question_viewBox
question_viewBox -- Yes --> viewport_scale
question_viewBox -- No --> viewport_no_scale
A <symbol> does not inherit any viewBox from its outer SVG; it must define its own viewBox if one is needed. The symbol's coordinate system is independent. When a <use> references a symbol, the symbol behaves as if an <svg> with its own viewport and viewBox were embedded at that point, so a viewBox on the outer SVG or on a parent coordinate frame does not apply to the symbol's content.
If the symbol has a viewBox attribute, it defines an internal coordinate system for the symbol's contents (min-x, min-y, width, height of the viewBox). This works the same way as an <svg> element's viewBox, establishing a mapping from the symbol's internal "user" coordinates to its viewport. The viewBox enables scaling: it scales the content to fit the viewport set by either the symbol's or the use's width/height.
Without a viewBox, a <use> element's width and height do not scale the content, as noted above.
When a symbol does have a viewBox, it behaves much like a mini SVG file. The viewBox defines the coordinate extents of the symbol's content and implicitly provides an aspect ratio. If the symbol's own width and height are specified, they define the viewport size into which the viewBox is scaled (by default). If the symbol's width/height are not specified (auto), and the <use> does not specify them either, the spec defaults the symbol's width/height to "100%" of the context, so the symbol stretches to fill the available area (for example, the parent SVG's viewport).
This scenario is uncommon, since typically either the symbol or the use provides an explicit size, but the behavior is defined for completeness.
<symbol> has the preserveAspectRatio attribute, as an <svg> element does. When it is not specified, the default is xMidYMid meet: the symbol's content is uniformly scaled to fit the viewport while preserving aspect ratio, centering the content and letterboxing it if the aspect ratios differ.
With preserveAspectRatio="none" on the symbol, the content is stretched non-uniformly to fill the viewport dimensions, which can distort the graphics.
This attribute applies when scaling the symbol's viewBox to the viewport, whether that viewport came from the symbol's own width/height or from the <use>. It does not inherit from any outer context; it is a property of the symbol itself.
When a <use> instantiates a symbol, several coordinate system transformations happen in sequence:
Accumulated Transformation: The net effect of all the above is a combined transformation from the symbol's original content coordinates to the final user space of the document. The SVG 2 spec describes this as the "cumulative effect" of the symbol's x, y, and its transformations, together with the host <use> element's transformations. The chain is:
All of these contribute to the final positioning. The symbol's content never inherits transforms or coordinate scaling from outside the <use>; it is encapsulated. The outer SVG's coordinate system comes into play only when the <use> places the symbol, through the <use>'s x, y, and transform. That encapsulation is why the symbol behaves like an independent nested SVG.
1.15.0