SVG Images

Both block and inline image macros have built-in support for scalable vector graphics (SVGs). But there’s more than one way to include an SVG into a web page, and the strategy used can affect how the SVG behaves (or misbehaves). Therefore, these macros provide additional options to control how the SVG is included (i.e., referenced).

Options for SVG images

When the image target is an SVG, the options attribute (often abbreviated as opts) on the macro accepts one of the following values to control how the SVG is referenced:

  • none (default)

  • interactive

  • inline

The following table demonstrates the impact these options have.

Demonstration of option values for SVG images

Observe that the SVG does not respond to the hover event.


Observe that the color changes when hovering over the SVG.


Observe that the color changes when hovering over the SVG. The SVG also inherits CSS from the document stylesheets.

How these options values work and when each should be used is described below:

Option values that control how an SVG image is referenced in the HTML output
Option HTML Element Used Effect When To Use

none (default)


Image is rasterized

Static image, no interactivity, no custom fonts



Image embedded as a live, interactive object

For using CSS animations, scripting, webfonts, or when you want to specify a fallback image



The SVG is embedded directly into the HTML itself

For using CSS animations, scripting, webfonts, when you require search engines to search the SVG content

To allow SVG content reachable by JavaScript in the main DOM or to inherit styles from the main DOM

When using the interactive option, you can specify a fallback image using the fallback attribute. The fallback image is used if the browser does not support the <object> tag. If the value of the fallback attribute is a relative path, it will be prefixed with the value of the imagesdir document attribute.

When using the inline or interactive options, the viewBox attribute must be defined on the root <svg> element in order for scaling to work properly.

When using the inline option, if you specify a width or height on the image macro in AsciiDoc, the width, height and style attributes on the <svg> element will be removed. Additionally, when using inline the primary SVG elements (e.g., <svg>) cannot have a namespace.

If using the interactive option, you must link to the CSS that declares the fonts in the SVG file using an XML stylesheet declaration.

If you’re inserting an SVG using either the inline or interactive options, we strongly recommend you optimize your SVG using a tool like svgo or SVG Editor.

As you work with SVG, you’ll become more comfortable making the decision about which method to employ given the circumstances. It’s only confusing when you first encounter the choice. To learn more about using SVG on the web, consult the online book SVG on the Web: A Practical Guide as well as these articles about SVG.