SVG Integration

Abstract

This specification details requirements on how SVG documents must be processed when used in various contexts, such as CSS background images, HTML ‘iframe’ elements, and so on. These requirements include which features are restricted or disabled, such as scripting and animation. A number of referencing modes are defined, which other specifications that allow the embedding or referencing of SVG documents can normatively reference.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document is the 08 March 2023 Editor’s Draft of SVG Integration. The purpose of this specification is to define how SVG documents that are referenced from SVG and HTML documents, and from CSS properties, are processed.

Comments on this Editor’s Draft are welcome. Comments can be sent to www-svg@w3.org, the public email list for issues related to vector graphics on the Web. This list is archived and senders must agree to have their message publicly archived from their first posting. To subscribe send an email to www-svg-request@w3.org with the word subscribe in the subject line.

This document has been produced by the W3C SVG Working Group as part of the Graphics Activity within the W3C Interaction Domain. The goals of the W3C SVG Working Group are discussed in the W3C SVG Charter. The W3C SVG Working Group maintains a public Web page, https://www.w3.org/Graphics/SVG/, that contains further background information. The authors of this document are the SVG Working Group participants.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Editor’s Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

A list of current W3C Recommendations and other technical documents can be found at https://www.w3.org/TR/. W3C publications may be updated, replaced, or obsoleted by other documents at any time.

1. Introduction

This section is non-normative.

SVG is a vector graphics markup language used both for artwork and to create interactive, rich content applications. In addition to being able to render graphical primitives such as shapes, text and images, SVG also supports a number of more complex features, including declarative animation, scripting using ECMAScript, and the ability to reference external resources.

For SVG to adhere to the security model of the Web platform, certain SVG features are required to be disabled depending on how the SVG document is being used. For example, SVG documents referenced by an HTML ‘img’ element are required to have scripting disabled.

The primary purpose of this document, SVG Integration, is to define a number of referencing modes for SVG documents, which detail the requirements for processing an SVG document when it is used in a certain context. These requirements include the set of features that must be disabled, any user agent style sheet rules to apply, and more.

Normative requirements are given for contexts in other SVG documents, such as how an SVG ‘image’ element must treat referenced SVG documents. Non-normative recommendations are given for other languages, including HTML and CSS, with the expectation that these other specifications will in time define which referencing mode from this document to use when SVG documents are used in a given context.

2. Referencing modes

There are various ways that an SVG document fragment can be referenced by or included in other documents and then as a consequence be processed by a user agent. SVG documents can also be viewed as a top-level document. Each different method by which an SVG document fragment can be used implies a certain set of requirements on how the SVG document fragment is to be processed.

This section defines a number of referencing modes that encompass the different ways SVG documents can be used on the Web platform and which specify how the documents must be processed. Each referencing mode is defined by requiring the SVG document be processed in a given processing mode. Processing modes are introduced in section 3 below and define which features are enabled or disabled in the document.

This document does not place normative requirements on other specifications that can reference or include SVG documents, such as HTML and various CSS specifications. The intention is for these other specifications to normatively point to the appropriate referencing mode from this document.

The available referencing modes are as follows:

top-level document

This referencing mode is for SVG documents that are loaded as a top-level document in a user agent.

SVG documents processed with the top-level document referencing mode must use the dynamic interactive processing mode.

This referencing mode is intended to be used when an SVG document is loaded in a browser's top-level browsing context. [HTML5]

embedded document

This referencing mode is for SVG documents that are externally referenced and embedded for presentation in a host document. SVG documents referenced by the @@ unknown element, attribute or property "iframe" element from SVG 2 or the ‘animation’ element from SVG Tiny 1.2 must use the embedded document referencing mode.

Note that the embedded document referencing mode is not used for inline SVG fragments within an HTML document.

SVG documents processed with the embedded document referencing mode must use the dynamic interactive processing mode.

This referencing mode is intended to be used when an SVG document is loaded in an HTML ‘embed’, ‘iframe’ or ‘object’ element.

animated image document

This referencing mode is for SVG documents that are used as images, where the context would typically be expecting a raster image that can animate. SVG documents referenced by the SVG ‘image’ element must use the animated image document referencing mode if the referencing SVG document is using the top-level document, embedded document or animated image document mode.

SVG documents processed with the animated image document referencing mode must use the secure animated processing mode.

This referencing mode is intended to be used when an SVG document is referenced by an HTML ‘img’ element or by any CSS property that takes an <image> value, and if animations can be run.

static image document

This referencing mode is for SVG documents that are used as images, where the context would typically be expecting a raster image but where animations are unable to run. SVG documents referenced by the SVG ‘image’ element must use the static image document referencing mode if the referencing SVG document is using the static image document mode.

SVG documents processed with the static image document referencing mode must use the secure static processing mode.

This referencing mode is intended to be used when an SVG document is referenced by an HTML ‘img’ element or by any CSS property that takes an <image> value, and if animations cannot be run.

resource document

This referencing mode is for SVG documents that are loaded as resource documents in order to use their ‘mask’, ‘pattern’, gradient, or other resource elements. SVG documents loaded due to a reference to an external document from any of the following features must use the resource document referencing mode:

• the clip-path, cursor, fill, filter stroke, marker-mid, marker-start, marker-end and mask properties
• the ‘altGlyph’, ‘cursor’, ‘feImage’, ‘filter’, ‘linearGradient’, ‘mpath’, ‘pattern’, ‘radialGradient’, ‘textPath’, ‘tref’ and ‘use’ elements

SVG documents processed with the resource document referencing mode must use the secure animated processing mode.

Should animations run in the resource document?

font document

This referencing mode is for SVG documents that are being used to define font glyphs.

SVG documents processed with the font document referencing mode must use the secure animated processing mode.

Additionally, SVG documents processed with the font document referencing mode must apply the following user agent style sheet:

@namespace svg url(http://www.w3.org/2000/svg);

svg|text, svg|foreignObject {
  display: none !important;
}

:root {
  fill: context-fill;
  fill-opacity: context-fill-opacity;
  stroke: context-stroke;
  stroke-opacity: context-stroke-opacity;
  stroke-width: context-value;
  stroke-dasharray: context-value;
  stroke-dashoffset: context-value;
}

This referencing mode is intended to used by the OpenType specification for processing documents from the "SVG" table.

Should the CSS Variables that map the palette colors into the document be defined here too? It probably makes sense to keep that in the OpenType specification.

SVG document fragments that are included inline in a host document use a referencing mode that matches that of the host document. SVG document fragments included as children of an SVG ‘foreignObject’ element must use the referencing mode of the referencing SVG document.

For example, if an SVG document is being used in animated image document mode due to being referenced by an HTML ‘image’ element, then any inline SVG fragment that is a child of a ‘foreignObject’ element within that document is also processed using animated image document mode.

3. Processing modes

This section defines a number of processing modes for SVG documents. Each processing mode specifies whether certain high level SVG features are enabled.

3.1. Features

The features that can be enabled or disabled depending on the processing mode are as follows:

declarative animation

Declarative animation includes both the SMIL animation elements in SVG – ‘animate’, ‘animateColor’, ‘animateMotion’, ‘animateTransform’ and ‘set’ – and CSS Transitions and Animations. When declarative animations are disabled in an SVG document, any SMIL animations or CSS Transitions or Animations must not be applied or run.

This is not the same as pausing the document's animated state at 0s document time; if a SMIL animation is defined to begin at 0s, it still will not be applied.

references to external resources

References to external resources are URLs that can be used in any of the following SVG features, where any of the URL's components, ignoring the fragment, do not match the document's URL:

• the clip-path, cursor, fill, filter stroke, marker-mid, marker-start, marker-end and mask properties
• the ‘altGlyph’, ‘audio’, ‘color-profile’, ‘cursor’, ‘feImage’, ‘filter’, ‘font-face-uri’, ‘foreignObject’, ‘glyphRef’, ‘image’, ‘linearGradient’, ‘mpath’, ‘pattern’, ‘radialGradient’, ‘script’, ‘textPath’, ‘tref’, ‘use’ and ‘video’ elements
• any other network requests made by script, HTML, CSS or other Web platform features used in the document

User agents must apply CORS policies when fetching external resources used in any of the SVG features listed above.

To protect against unlimited resource fetching and cycles in external resources, user agents must limit external resources to a single level of depth, so that referenced external resources cannot reference external resources.

As noted in Referencing modes section, external resources must use resource document referencing mode.

When external references are disabled in an SVG document, any attempt to fetch a document through an external reference must instead be treated as if a network error occurred and no data was received.

This is all too handwavy. And we perhaps shouldn't try to make an exhaustive list. This needs to be defined in terms of Fetch, probably. And the URL Standard for comparing the URLs.

script execution

Script execution is the execution of any SVG ‘script’ elements, script found in event listener attributes (such as @@ ambiguous name "onclick" (matches multiple attributes) on SVG elements), or any other script defined by other Web platform features used in the document such as any HTML ‘script’ elements. When script execution is disabled in an SVG document, no script in the document must be run.

interaction

Interaction refers to the delivery of DOM Events or the invocation of any user agent specific UI behaviors such as text selection, focus changing, link traversal, or animation or transition triggering that is done in response to user input such as mouse or keyboard activity. When interaction is disabled in an SVG document, any user input events that would be targetted at the document or any elements within the document must have no effect.

3.2. Dynamic interactive mode

This processing mode imposes no restrictions on any feature of the SVG language.

3.3. Animated mode

This processing mode is intended for circumstances where an SVG document is to be used as an animated image that is allowed to resolve external references, but which is not intended to be used as an interactive document.

Note that this processing mode is not used by any of the referencing modes defined in this specification.

Should we remove this processing mode?

3.4. Secure animated mode

This processing mode is intended for circumstances where an SVG document is to be used as an animated image that is not allowed to resolve external references, and which is not intended to be used as an interactive document. This mode might be used where image support has traditionally been limited to raster images (such as JPEG, PNG and GIF).

3.5. Static mode

This processing mode is intended for circumstances where an SVG document is to be used as a non-animated image that is allowed to resolve external references, but which is not intended to be used as an interactive document.

Note that this processing mode is not used by any of the referencing modes defined in this specification.

Should we remove this processing mode?

3.6. Secure static mode

This processing mode is intended for circumstances where an SVG document is to be used as a non-animated image that is not allowed to resolve external references, and which is not intended to be used as an interactive document. This mode might be used where image support has traditionally been limited to non-animated raster images (such as JPEG and PNG.)

3.7. Examples

This section is non-normative.

Below are various methods of embedding SVG in an HTML page by reference. Each referencing mode element should display a yellow smiley face. In each example below, clicking on the eyes tests link traversal, and clicking on the face tests declarative interactivity and script execution. The link should replace the image with a blue square (clicking on that will return you to the original image). The declarative interactivity, which uses the ‘set’ element, should change the image from shades of yellow to shades of green. The script should fill in the smile. Time-based (as opposed to interactivity-based) declarative animation is supported if the left eye is winking.

object	iframe	img	CSS background

4. Sizing SVG content in CSS context

To present SVG content in CSS context (such as 'background-image', inline SVG in HTML or 'img' element referencing SVG document), user agents must use the rules below.

Initial ‘svg’ element width and height are set to 'auto', except cases when SVG element is the top level element in the document (including embedded documents). When SVG element is the top level element, the width and height are set to '100%'

To resolve 'auto' value on ‘svg’ element if the ‘viewBox’ attribute is not specified:

• Use author specified width and height ‘svg’ element attributes.
• If any of the sizing attributes are missing, resolve the missing ‘svg’ element width to '300px' and missing height to '150px' (using CSS 2.1 replaced elements size calculation).

To resolve 'auto' value on ‘svg’ element if the ‘viewBox’ attribute is specified:

• Use the ‘viewBox’ attribute to calculate the intrinsic aspect ratio of the ‘svg’ element.
• If the width or height attributes are not specified - keep not specified width or height as 'auto'.

The resolved ‘svg’ element width, height and aspect ratio are then used in CSS sizing as intrinsic element size properties (using CSS 2.1 replaced elements size calculations).

5. Embedding foreign content in SVG

The SVG ‘foreignObject’ element is an extension point that can be used to include document fragments from other languages to be rendered in an SVG document. This section defines how HTML and SVG elements are handled as children of ‘foreignObject’.

5.1. Using HTML in ‘foreignObject’

When ‘foreignObject’ is used to contain content which is styled by CSS, the viewport establishes the initial containing block (as defined in CSS 2.1). The dimensions of the CSS viewport in pixels are the width and height attribute values of the ‘foreignObject’ element in user units.

If ‘foreignObject’ contains SVG element, the viewport of this element is established according to initial viewport definition.

6. References

6.1. Normative references

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997.
Available at https://tools.ietf.org/html/rfc2119.

[SVG11]

Scalable Vector Graphics (SVG) 1.1, J. Ferraiolo, 藤沢 淳(Fujisawa Jun), D. Jackson, eds. World Wide Web Consortium, 14 January 2003.
This edition of SVG 1.1 is https://www.w3.org/TR/2003/REC-SVG11-20030114/.
The latest edition of SVG 1.1 is available at https://www.w3.org/TR/SVG11/.

[SVGT12]

Scalable Vector Graphics (SVG) Tiny 1.2, O. Andersson, R. Berjon, E. Dahlström, A. Emmons, J. Ferraiolo, A. Grasso, V. Hardy, S. Hayman, D. Jackson, C. Lilley, C. McCormack, A. Neumann, C. Northway, A. Quint, N. Ramani, D. Schepers, A. Shellshear, eds. World Wide Web Consortium, 22 December 2008.
This edition of SVG Tiny 1.2 is https://www.w3.org/TR/2008/REC-SVGTiny12-20081222/.
The latest edition of SVG Tiny 1.2 is available at https://www.w3.org/TR/SVGTiny12/.

[SVG2]

Scalable Vector Graphics (SVG) 2, N. Anrdronikos, T. Bah, B. Birtles, C. Concolato, E. Dahlström, C. Lilley, C. McCormack, D. Schepers, D. Schulze, R. Schwerdtfeger, S. Takagi, J. Watt, eds. World Wide Web Consortium, 11 February 2014.
This edition of SVG 2 is https://www.w3.org/TR/2014/WD-SVG2-20140211/.
The latest edition of SVG 2 is available at https://www.w3.org/TR/SVG2/.

[CORS]

Cross-Origin Resource Sharing, Anne van Kesteren. World Wide Web Consortium, 16 January 2014.
This edition of CORS is https://www.w3.org/TR/2014/REC-cors-20140116/.
The latest edition of CORS is available at https://www.w3.org/TR/cors/.

6.2. Non-normative references

[HTML5]

HTML5, R. Berjon, S. Faulkner, T. Leithead, E. D. Navara, E. O'Connor, S. Pfeiffer, I. Hickson. World Wide Web Consortium, work in progress, 04 February 2014.
This edition of HTML5 is //www.w3.org/TR/2014/CR-html5-20140204/.
The latest edition of HTML5 is available at https://www.w3.org/TR/html5/.

7. Acknowledgments

The editors would like to acknowledge and thank the following people for substantive aid with this specification: Erik Dahlström.