General Techniques
These techniques are applicable across many different use cases for SVG.
Structure
There are two main aspects to the structure of an SVG document: the composition of shapes; and grouping and nesting.
Shape Composition
When creating an SVG, consider each individual shape for its function rather than just its initial appearance. Functional shapes can be styled, modified, and have new behavior added to them after the drawing is done.
In the following example, clock-bad-0.svg, the author has created a clock icon, which may appear satisfactory:
However, rather than simply using the stroke of the shape, the author defined the inner and outer sides of the line shape, meaning that you can't independently style the clock face (the shape's fill or "background") and the outline, as shown in the following example, clock-bad-0a.svg, where we would expect to be able to make the clock face yellow:
Changing the fill only changes the color of the shape outline, not the shape background. Also, frequently for icons, you'd like to be able to increase or decrease the stroke width for different image sizes, and this type of path-outline shape doesn't let you do that; the minimum thickness of the shape outline is fixed unless you change the geometry of the path.
Besides the styling problems, using shape outlines dramatically increases the file size, usually much more than double the size. Sometimes this shape-outline technique is useful and necessary, especially when you want to simulate variable stroke widths, like a calligraphic stroke, but for uniform stroke widths, this is unnecessary and even a disadvantage.
In Adobe Illustrator, this feature is called Outline Stroke (an option under Object > Path). It's easy to convert a stroke to an outline, but there is no easy way to convert an outline to a stroke. Thus, authors are encouraged not to use Outline Stroke unless required.
We can start to fix these problems by defining the shape as a simple stroke, which allows the stroke and fill to be styled seperately, as in the following example, clock-bad-1.svg:
Still, both the clock face and the hands are composed of a single path element. This means that if you decide to change any of the styling, such as the color of the stroke or the fill, or width of the stroke, you cannot change only the clock face or hands, but must change both together. And even more obvious, the fill has an artifact where the hands make a blank space.
We can fix that by splitting the clock face and hands into two separate shapes (now a circle and a path element), which allows individual styling, as in the following example, clock-bad-2.svg:
However, there is still a problem, because the individual hands are a single element, which doesn't let them be styled differently (among other problems we'll describe next). We split the clock hands into two separate shapes, which allows individual styling, as in the following example, clock-bad-3.svg:
This is an improvement, and now allows individual image components not only to be styled differently, but also replaced independently much more easily, such as making a more elaborate hour hand with a simple minute hand. In addition, we've added another functional aspect to the clock hands. An author could (and should) anticipate that someone (whether the developer on their team, a stranger reusing their image with permission, or themselves at some later point) would want to animate the clock hands. The following example, clock-animate-0.svg, shows that adding a simple rotation animation is now easy:
Another small improvement will make this even more robust. By changing the origin of the individual hands from the end points to the center points, we ensure that additional transforms do not disrupt the hand animation, as in the following example, clock-animate-1.svg:
In addition to animation, other functional aspects of a shape are various kinds of interactivity, such as clicking or mouseovers.
By thinking about a shape's possible functions and behaviors, and not only its appearance, an author can make their SVG more reusable from the beginning.
Grouping and Nesting
In SVG, you can organize your images into logically related items using the g (“group”) element. For example, if you have an image of a family standing under a tree, next to their car, in front of their house, where each object is made up of several components, you can group together each object, and even groups of objects; you can have one group for the tree and its branches and leaves, one group for the house and its doors and windows, one group for the car and its windows and tires, and one group for all the people, with a nest group for each person and their heads, bodies, limbs, and clothes.
For authors, grouping related items makes it easier to maintain and to style common objects, to nest sets of groups, to select and reorder collected objects, and to hide and show groups individually. For users, grouping helps navigation, especially for use through a keyboard or a screenreader.
In Adobe Illustrator and some other authoring tools, the g element corresponds to a layer. Each layer is a separate group, and the contents of the layer are the contents of the group.
TODO: add group example, nested groups
TODO: add group styling example
TODO: add group ID example
Document Order
An author should make sure that the SVG document has a document order that mirrors the intended reading order for the content, including any “hidden” text.
SVG uses absolute positioning and a painter's model for rendering graphical and textual content.
SVG's absolute positioning layout means that each element is positioned precisely by its geometric (e.g. x,y) description, and that this position is not affected by any other element; this is unlike the common case in CSS, where adding content “pushes” the content after it in document order to a new position. SVG's absolute positioning is shown in the following example, absolute-positioning.svg, in which the group with the blue circle (labeled 1) is before the gold square (labeled 2) in document order, but is positioned to the right of it in rendering order:
The painter's model means that the first element in the document is rendered first, the second element is rendered next, and so on, with each element that overlaps a previous element being drawn “on top” of that previous element, like the following example, painters-model.svg, in which the first element, a yellow square, is overlaid by the second element, a blue circle, which in turn is overlaid by the third element, a green line (hovering over each element will show the element below):
The combination of absolute positioning and painter's model lead to a circumstance where it is relatively easy for authors to inadvertently misorder the reading flow of a document. This risk is increased when the “invisible metadata” of the title and desc elements is added to the document, since it is easy for authors to overlook how the sequence of “hidden” text will flow with any visible text, or flow between multiple sets of “hidden” text.
A bad document reading order is illustrated in this example, document-order-bad.svg:
Though it is rendered in a logical order, the document reading order is #2, then #4, then #1, then #3, then the names of the fruits. This is corrected in the following example, document-order-good.svg, in which the reading order and the rendering order are aligned:
A simple way to check the reading order of the document is to “select all” in your SVG document in the browser, and paste it into a text file. If the resulting text makes sense in this text file, then then reading order of your SVG document is acceptable. Note that not all browsers include titles in a selection, so account for them separately.
Text and Text Equivalents
Unlike text in a raster image, which is simply pixels and shapes, text content in SVG can be included directly with the text element. This text content is machine–readable, indexable and searchable by search engines, findable though “find text” functionality, selectable with the keyboard or mouse, and translatable. As in HTML, SVG text can be styled (including different styles for fill and the stroke) and can use Web fonts (such as WOFF, TTF, and OTF formats).
The textPath element even permits text to run along the stroke of an SVG shape, something not possible in HTML alone, as in this example, textpath.svg:
Additionally, text is convenient for authoring, because it can be changed quickly and easily. The words themselves can be changed with little effort, and Web fonts afford a wide variety of styles that can substitute for logos or other stylized text.
Wherever possible, text in SVG should be actual textual content, and not simply elements shaped like text, because you lose all the benefits of text.
On a related note, authors should consider placing important, contextual, or navigation items first in the document order.
Text Equivalents
Sometimes, text is not enough for a particular use, either because the shapes can't be represented in a font (such as with custom-drawn interlocking words), or because the SVG image is graphical rather than textual.
In this case, the author should use the title and desc elements to provide text equivalents for all elements that are important for the user to understand the image.
The title element
The title element, when included as the first child of an element, lets the author provide a short, meaningful title for that element, similar to the alt attribute in HTML.
For example, if an SVG document contains an image of an apple that is important to the understanding of the document, the author should include a title element with the word “Apple”, like so:
<path d="…">
<title>Apple</title>
</path>
Screenreaders should treat the content of the title element as the “accessible name” in the accessibility tree. Unfortunately, due to inconsistencies in current browsers and screenreaders, the title element is not yet consistently supported, so for now if you want your SVG to be accessible you also need to give the title an id attribute, and point to it with the aria-labelledby attribute, as in this example, title.svg:
Similar to HTML, you can give the entire document a title by using a title as the first child element of the root svg element, as show in the last example. You should always give your SVG document a title in this way.
Most of the examples in this document don't include a root title element, for the sake of simplicity and clarity of the specific technique, but this should be an exception.
Whenever possible, authors should use a visible text element to provide a label, for affordance for all users. Authors must not duplicate the text of a text element in a related title element, since that will be distracting, confusing, annoying, and counterproductive for screenreader users.
Browsers typically provide a tooltip (an information popup) when elements with a title are hovered over. Authors should resist the temptation to use this as a means to provide instructions for use, but should only use the title element to give a meaningful title to that element. Otherwise, users of screenreaders will have no context for the instructions.
The desc element
The desc element, when included as a child of an element, lets the author provide a longer description, when necessary, to supplement the title for that element. The desc element should be used sparingly.
For example, if an SVG document contains an image of an apple that is important to the understanding of the document, and the title alone might not convey the whole context, the author may include a desc element to supplement a title, like so:
<path d="…">
<title>Apple</title>
<desc>A large Granny Smith apple with a bite taken out of it,
sitting on the grass.</desc>
</path>
Screenreaders will treat the content of the desc element as a supplementary description in the accessibility tree, available on request.
TODO: title and desc, title for document and group
Accessibility Tip: .
Navigation and Activation
Many users navigate Web documents, including SVG documents, via the keyboard. This may be a serial navigation via the tab key, through keyboard shortcuts, activating links and interactive elements via the enter/return key, or various other means. Other users have navigation challenges by using touch-screens, often with a small surface (such as smart phones), and no way to distinguish between "hovering" and "clicking". Still other users have unsteady hands or limited mobility, and must navigate slowly or through single-switch controls.
Users of screenreaders or screen magnifiers may have difficulty locating navigable or activatable elements.
In order to meet the needs of these users, if an element is important, navigable, or activatable, it must have an indication in the markup that it can receive focus control.
The a element will receive focus when it is a valid link. Generally, this is accomplished through the use of an href attribute.
All other elements, if they are to be focusable, must be have a tabindex attribute, with a non-negative value; generally, the value should be 0. SVG also includes a focusable attribute and property, but this is not well supported across browsers, and tabindex should be preferred for now.
In addition to being focusable, authors should make sure interactive elements are large enough for selection and activation by small-device users and users with unsteady hands.
TODO: add navigation example
Resizability
Many SVG images are defined to be of fixed dimensions, such as 150 pixels wide and 50 pixels high, just like raster images like JPEG or PNG format. However, the more common use case for SVG is to automatically resize to fit the available space. Raster images have intrinsic sizes and dimensions because they are composed of a fixed set of rows of pixels, and the appearance of those pixels would be distorted if displayed at a larger or smaller size, producing artifacts called pixelization. By contrast, SVG images are drawing instructions for an image that are equally crisp at any size, called vectors, a characteristic called scalability (thus the name Scalable Vector Graphics). The fixed-size output of many SVG generators is not optimized for use on the Web, where different devices have variably-sized screens, and where an SVG image may be referenced in an HTML file at different sizes than the original dimensions.
It's simple to take advantage of SVG's native scalability, while still defining the abstract native dimensions of the image. The SVG root element has three attributes to control these characteristics: the width; height; and viewBox attributes.
The width and height attributes
The width and height attributes respectively specify the horizontal and vertical dimensions of the image. The attribute values may have units, such as pixels (150px) or centimeters (7cm), or they may omit units dimensions and be interpreted abstractly in user units, e.g. relative dimensions that scale to the size of the container.
The viewBox attribute
The viewBox attribute sets the viewport of the SVG via 4 space-separated numbers, in the form "x y width height".
An SVG image has an infinite canvas, with the 0,0 origin at the top-left point, and positive values moving down and to the right (i.e. the fourth quadrant of a traditional Cartesian coordinate space); a graphical element may be located at any point in this space, whether at a positive or negative x or y. The viewBox attribute controls which section of this infinite canvas is visible in the viewport.
For example, the following code sample shows an SVG root element that has a viewport that starts at 0,0, and has a width of 100 units and a height of 50 units:
<svg viewBox="0 0 100 50">
This means that any graphical shape that is contained (fully or partially) within that space will be visible in the viewport (at least partially, based on the position and overlap).
To extend this example, the following code sample shows the same viewBox, and also includes a width and height:
<svg width="20" height="10" viewBox="0 0 100 50">
This will produce an SVG of a fixed size (20 pixels by 10 pixels) with a 2:1 dimension ratio, and a viewport that includes all elements that are within the confines of the viewport.
Setting the width and height attributes to 100% tells the browser to use the full available space of the container for the units. This means that the SVG will take up full width and height of the image (img) element in HTML, or the whole browser window if the SVG image is viewed as a stand-alone document.
<svg width="100%" height="100%" viewBox="0 0 150 70">
This is actually the default behavior for an SVG image that doesn't have explicit width and height attributes, so you can get the same effect by only using the viewBox attribute and omitting the width and height attributes:
<svg viewBox="0 0 150 70">
Because SVG is case-sensitive (a legacy of its XML origins), the attribute viewBox must have a capital “B”. It's a common mistake to type viewbox instead, which is easily overlooked and frustrates debugging. SVG uses a mix of attribute-name delimiters, including medial camelCase (“viewBox”), lower-case compound (“viewbox”), and kebab-case (“view-box”), so this is a common error. We're sorry about that.
We explore the viewBox attribute more in the section on Icons and Symbols.
Resizability Example
In this example, we show an auto-sizing SVG in an HTML object element at half-size, full-size, double-size, and triple-size, all referencing the same SVG document, auto-resizable.svg:
Note that although vector images have crisp borders and lines at all sizes, there are still perceivable differences at different sizes. For example, a curved corner may appear too rounded and text may appear too large if a small icon is displayed at a large size, or a complex image may appear more cluttered and hard to distinguish if displayed at a small size. Some of these vector artifacts may be reduced by changing styling or hiding or showing different elements at different sizes, using Media Queries as described in the section on Responsive Images.
Accessibility Tip: Making images auto-scaling can help users with low vision or mobility issues, since they can increase the size of the image to suit their needs, making it easier to see details or to click on interactive elements.
Fixed Sizes
Using fixed dimensions rather than auto-sizing does have some use cases, including specifying print sizes in real-world units, and seting intrinsic size for use in HTML when no sizing is defined in HTML or CSS (noting the width and height defaults of 300px by 150px for replaced elements in HTML). This differences between auto-sized and fixed-size SVGs are illustrated in these two examples, where no dimensions are specified in the object, with the first SVG using fixed dimensions (with intrisic width and height of 200px by 200px) and the second SVG using auto-sizing (with the default width and height of 300px by 150px):
Responsive Images
A responsive image is one which adapts to best fit the display device's capabilities, whether different sizes, resolutions, orientation (e.g. portrait or landscape), or color ranges (e.g. color or grayscale). One approach to creating responsive images is to use a media query, which is a CSS mechanism that allows a document to have different style rules based on different media features, such as width, height, color, display orientation, and resolution. SVG's scalable nature makes styling things based on sizing a natural fit in particular, though other factors, such as orientation or color gamut are also useful with SVG.
For instance, some images look good at a large size, but at a small size the stroke-width becomes too thin and there isn't enough visual contrast, as in the following example, clock-non-responsive.svg, referenced at two different sizes via object elements:
While the stroke-width remains constant relative to the the other details of the image, such as the radius of the circle, it now appears too thin. To address this perception issue, you can use media queries to increase the stroke-width of an SVG icon when it's shown at small sizes, to enhance the visual contrast and make certain details more distinct. We illustrate this in the following example, clock-responsive-0.svg, referenced at two different sizes via object elements:
Building on this example further, sometimes at large sizes (or "close up" zoomed images) you want more detail, but at small sizes (or "further away"), these extra details simply clutter up the image, detracting from it rather than enhancing it. Adding and removing detail based on size (or "nearness") is known as "level of detail" or LOD. To achieve LOD in SVG with media queries, in addition to changing stroke-width, you can change other styling characteristics, such as fill (a more complex gradient versus a simple flat color versus high-contrast colors), markers (such as arrowheads on the end of a line), or simply toggling the visibility of particular parts of the image (such as showing numbers at large sizes, tick marks at smaller sizes, and nothing at all at very small sizes). The the following more complex example, clock-responsive-1.svg, we illustrate some of these techniques in the same SVG image at three different sizes:
Note that Media Queries may not work in all SVG authoring tools. For example, opening a responsive SVG in Adobe Illustrator or Inkscape may not display the expected results.
We explore the viewBox attribute more in the section on Resizability.
Animation
.
TODO: talk about distraction, epilepsy, and slow movement
SVG in HTML
There are 5 main ways to use SVG in HTML content: inclusion in inline markup; referenced in the object element; referenced in the img element; referenced in the iframe element; or referenced as a CSS background.
Inline SVG in HTML results in a single hybrid HTML+SVG document. This has the advantages that the image is carried along with the document, so it can't be lost when moving the file around (the same advantage that inline CSS has over an external stylesheet), and that the SVG can share the same scripts and styles that are applied to the HTML content (that is, they share the same DOM).
All the other methods (linked by object, img, or iframe replaced elements or in CSS) assume an external SVG file, referenced like any other image format (such as PNG or JPEG). External SVGs have a few advantages, including the ability to easily swap out the image, to use the image in multiple files (taking advantage of caching), to use the image as a standalone SVG (that is, as an image outside any HTML), and to isolate the SVG DOM from HTML for easier scripting and styling or for security or privacy.
Inline SVG in HTML
Inline SVG in HTML .
The example inline-svg.html shows an inline SVG with styles applied from CSS in the HTML head:
It's not necessary in inline SVG to include the SVG and XLink namespace attributes. However, it is still necessary to include them in standalone SVG, so if an SVG file is intended for use both inline and standalone, it's a safe practice to include the SVG and XLink namespace attributes, in case an inline SVG is reused as a standalone file.
Script in Inline SVG in HTML
HTML5 specifies that the HTML external script element is not a self-closing element, unlike the SVG element of the same name, but also specifies that the SVG external script element in inline SVG should be parsed as normal for SVG. Thus, a self-closing external script element is valid, like so:
<svg>
<script xlink:href="…"/>
</svg>
However, not all browsers parse this self-closing element correctly, and may not load and run the script, so it is safer in inline SVG to use a closing tags for the exernal script element, like this:
<svg>
<script xlink:href="…"> </script>
</svg>
The example inline-svg-script.html shows an inline SVG with with both styles of external script element, which are theoretically the same but may differ in practice:
TODO: describe different behavior in onload and document in inline vs standalone
SVG in the object element
This example svg-in-object.html shows an external SVG referenced with the object element:
The object element is the preferred way to reference an external SVG. Using the object or iframe elements allow text search and selection, interactivity on a per-element level, and the execution of script, which aren't currently allowed using the img element. This is illustrated in these two examples, the first using <object> and the second using <img>
In comparison to the iframe element, the object element doesn't have a default border, and also scales to matches the intrinsic size and dimensions of the SVG content, while the iframe size is determined by styles in the HTML page. This is illustrated in these two examples, which have no CSS sizing defined:, the first using <object> and the second using <iframe> (which uses the default width and height of 300px by 150px for replaced elements in HTML):
The embed element is also a valid HTML5 element, which acts effectively the same as the object element. As with the iframe element, there are no advantages to using the embed element rather than the object element, so authors are encouraged to using object instead. Thus, this guide doesn't describe the embed element in any more detail.
SVG in the img element
The img element is another common way to reference an external SVG. The advantage of img is that many graphical authoring tools and environments support the insertion of img element, and may not support inserting the object element.
The img element allows animation, but does not enable text search and selection, interactivity on a per-element level, or the execution of script.
The example svg-in-img.html shows an external SVG referenced with the img element:
Note that not all browsers support animation in the img element, so the safest approach is to use inline SVG or the object element.
SVG in the iframe element
The iframe element is another way to reference an external SVG.
As with the object element, the iframe element allows text search and selection, interactivity on a per-element level, and the execution of script, which aren't currently possible with the img element. However, for SVG, there are no advantages to using the iframe element over the object element, and there are some disadvantages. As mentioned before, the iframe element has a border as the default style, which is not normally desirable, and the iframe size is determined by styles in the HTML page, rather than using the intrinsic size and dimensions of the SVG content. So, it's recommended to use object instead of iframe.
The example svg-in-iframe.html shows an external SVG referenced with the iframe element:
SVG as a CSS background
Another method to reference an external SVG in HTML is by specifying SVG as a background image in CSS, which can be applied to any HTML element.
As with the img element, SVG's used as a background image don't allow text search and selection, interactivity on a per-element level, or the execution of script.
The example svg-in-css-background.html shows an external SVG referenced as a CSS background image:
HTML in SVG
Sometimes, you may wish to include HTML in your SVG, such as structured text content like lists or form controls. The SVG foreignObject element lets you embed chunks of HTML directly into your SVG. You can include a whole HTML document, or just individual snippets of HTML. The most reliable content in a foreignObject element is a single HTML body element containing other HTML content, or one or more HTML flow content elements.
Because of SVG's XML origins, the HTML content should be well-formed XHTML, and you must use the HTML namespace declaration, xmlns="http://www.w3.org/1999/xhtml", in each HTML parent element in the foreignObject element. If you don't use the namespace declaration, the HTML content won't be rendered in current browsers.
For instance, in the following example, foreignObject-html-bad.svg, there is a list with 3 list items contained in a parent HTML ul element that has a namespace declaration that will render, and a paragraph that doesn't have namespace declaration that won't render:
The following example, foreignObject-html.svg, has two parent HTML elements in the foreignObject element, ul and select, and both have namespace declarations, so they'll both render correctly:
Accessibility Tip: Because modern screenreaders were designed to interface with HTML, using HTML in your SVG can often be a very effective way to make your structured content or interactive controls accessible.
Most SVG authoring tools, and some other SVG graphics tools, don't support HTML, so they won't render any HTML in your SVG. Some may not accept even an SVG file containing HTML as valid. Some authoring tools may accept the file, but not include the HTML content when saving the file. Be sure to test your SVG tools for HTML support before relying on them.
As defined in the SVG specification, the foreignObject element is not limited to rendering HTML, but should be able to contain any arbitrary XML, such as MathML. In practice, modern browser support for any other content than HTML in the foreignObject element is unreliable.
ARIA: Semantic Markup Attributes
SVG is a semantically-neutral markup language, so you can add semantics by using ARIA markup attributes.
HTML is a moderately semantic markup language, with elements that convey specific meaning about document structure (e.g. h2, section),
Aside from a few functional semantic elements such as a, title, and desc and structural semantic elements like g and defs, SVG has none of these semantics or native controls and focuses solely on geometry, positioning, presentation, and implicit semantics such as document order and structure (including grouping and nesting). This means that SVG is a blank canvas to apply whatever semantics you wish to your elements.
Unlike in HTML, there are very few native semantics to SVG, particularly around text or widget controls. If you want a well-structured document that ......
For instance, you can make SVG text explicitly considered to be a list, as in the following example, aria-list.svg, which uses ARIA to add a heading and a set of nested list items:
You can even create even more complex semantic structures like a table, as in the following example, aria-table.svg:
Note that you can very effectively style ARIA-decorated elements using the CSS attribute selector, similar to how you would style their semantic-element equivalents.
TODO: talk about ARIA