W3C

Scalable Vector Graphics (SVG) 2

W3C Editor’s Draft 28 July 2016

This version:
https://svgwg.org/svg2-draft/
Latest version:
http://www.w3.org/TR/SVG2/
Previous version:
http://www.w3.org/TR/2015/WD-SVG2-20150915/
Single page version:
https://svgwg.org/svg2-draft/single-page.html
GitHub repository:
https://github.com/w3c/svgwg/
Public comments:
www-svg@w3.org (archive)
Editors:
Nikos Andronikos, Canon, Inc. <nikos.andronikos@cisra.canon.com.au>
Rossen Atanassov, Microsoft Co. <ratan@microsoft.com>
Tavmjong Bah, Invited Expert <tavmjong@free.fr>
Amelia Bellamy-Royds, Invited Expert <amelia.bellamy.royds@gmail.com>
Brian Birtles, Mozilla Japan <bbirtles@mozilla.com>
Bogdan Brinza, Microsoft Co. <bbrinza@microsoft.com>
Cyril Concolato, Telecom ParisTech <cyril.concolato@telecom-paristech.fr>
Erik Dahlström, Invited Expert <erik@dahlström.net>
Chris Lilley, W3C <chris@w3.org>
Cameron McCormack, Mozilla Corporation <cam@mcc.id.au>
Doug Schepers, W3C <schepers@w3.org>
Dirk Schulze, Adobe Systems <dschulze@adobe.com>
Richard Schwerdtfeger, IBM <schwer@us.ibm.com>
Satoru Takagi, KDDI Corporation <sa-takagi@kddi.com>
Jonathan Watt, Mozilla Corporation <jwatt@jwatt.org>

Abstract

This specification defines the features and syntax for Scalable Vector Graphics (SVG) Version 2. SVG is a language based on XML for describing two-dimensional vector and mixed vector/raster graphics. SVG content is stylable, scalable to different display resolutions, and can be viewed stand-alone, mixed with HTML content, or embedded using XML namespaces within other XML languages. SVG also supports dynamic changes; script can be used to create interactive documents, and animations can be performed using declarative animation features or by using script.

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 http://www.w3.org/TR/.

This document is the 28 July 2016 Editor’s Draft of SVG 2. This version of SVG builds upon SVG 1.1 Second Edition by improving the usability of the language and by adding new features commonly requested by authors. The Changes appendix lists all of the changes that have been made since SVG 1.1 Second Edition.

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.

The specification includes a number of annotations that the Working Group is using to record links to meeting minutes and resolutions where specific decisions about SVG features have been made. Different coloring is also used to mark the maturity of different sections of the specification:

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, http://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 Working 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 http://www.w3.org/TR/. W3C publications may be updated, replaced, or obsoleted by other documents at any time.

This document is governed by the 1 September 2015 W3C Process Document.

The following features are at risk, and may be dropped during the CR period:

Acknowledgments

The SVG Working Group would like to thank the following people for contributing to this specification with patches or by participating in discussions that resulted in changes to the document: David Dailey, Eric Eastwood, Jarek Foksa, Daniel Holbert, Paul LeBeau, Robert Longson, Henri Manson, Ms2ger, Kari Pihkala, Philip Rogers, David Zbarsky.

In addition, the SVG Working Group would like to acknowledge the contributions of the editors and authors of the previous versions of SVG – as much of the text in this document derives from these earlier specifications – including:

Finally, the SVG Working Group would like to acknowledge the great many people outside of the SVG Working Group who help with the process of developing the SVG specifications. These people are too numerous to list individually. They include but are not limited to the early implementers of the SVG 1.0 and 1.1 languages (including viewers, authoring tools, and server-side transcoders), developers of SVG content, people who have contributed on the www-svg@w3.org and svg-developers@yahoogroups.com email lists, other Working Groups at the W3C, and the W3C Team. SVG 1.1 is truly a cooperative effort between the SVG Working Group, the rest of the W3C, and the public and benefits greatly from the pioneering work of early implementers and content developers, feedback from the public, and help from the W3C team.

SVG 2 – 28 July 2016 TopContentsNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Full Table of Contents

  1. 1. Introduction
    1. 1.1. About SVG
    2. 1.2. Compatibility with other standards efforts
    3. 1.3. Conformance
  2. 2. Rendering Model
    1. 2.1. Introduction
    2. 2.2. The rendering tree
      1. 2.2.1. Definitions
      2. 2.2.2. Rendered versus non-rendered elements
      3. 2.2.3. Controlling visibility: the effect of the ‘display’ and ‘visibility’ properties
      4. 2.2.4. Re-used graphics
    3. 2.3. The painters model
    4. 2.4. Rendering order
      1. 2.4.1. Controlling element rendering order: the ‘z-index’ property
      2. 2.4.2. Establishing a stacking context in SVG
    5. 2.5. How elements are rendered
    6. 2.6. How groups are rendered
      1. 2.6.1. Object and group opacity: the effect of the ‘opacity’ property
    7. 2.7. Types of graphics elements
      1. 2.7.1. Painting shapes and text
      2. 2.7.2. Painting raster images
    8. 2.8. Filtering painted regions
    9. 2.9. Clipping and masking
    10. 2.10. Parent compositing
    11. 2.11. The effect of the ‘overflow’ property
  3. 3. Basic Data Types and Interfaces
    1. 3.1. Definitions
    2. 3.2. Attribute syntax
    3. 3.3. Real number precision
    4. 3.4. DOM interfaces for SVG elements
      1. 3.4.1. Interface SVGElement
      2. 3.4.2. Interface SVGGraphicsElement
      3. 3.4.3. Interface SVGGeometryElement
    5. 3.5. DOM interfaces for basic data types
      1. 3.5.1. Interface SVGNumber
      2. 3.5.2. Interface SVGLength
      3. 3.5.3. Interface SVGAngle
      4. 3.5.4. List interfaces
      5. 3.5.5. Interface SVGNumberList
      6. 3.5.6. Interface SVGLengthList
    6. 3.6. DOM interfaces for reflecting SVG attributes
      1. 3.6.1. Interface SVGAnimatedBoolean
      2. 3.6.2. Interface SVGAnimatedEnumeration
      3. 3.6.3. Interface SVGAnimatedInteger
      4. 3.6.4. Interface SVGAnimatedNumber
      5. 3.6.5. Interface SVGAnimatedLength
      6. 3.6.6. Interface SVGAnimatedAngle
      7. 3.6.7. Interface SVGAnimatedString
      8. 3.6.8. Interface SVGAnimatedRect
      9. 3.6.9. Interface SVGAnimatedNumberList
      10. 3.6.10. Interface SVGAnimatedLengthList
      11. 3.6.11. Interface SVGStringList
    7. 3.7. Other DOM interfaces
      1. 3.7.1. Interface SVGUnitTypes
      2. 3.7.2. Interface SVGTests
      3. 3.7.3. Interface SVGFitToViewBox
      4. 3.7.4. Interface SVGZoomAndPan
      5. 3.7.5. Interface SVGURIReference
  4. 4. Document Structure
    1. 4.1. Defining an SVG document fragment: the ‘svg’ element
      1. 4.1.1. Overview
      2. 4.1.2. Namespace
      3. 4.1.3. Definitions
      4. 4.1.4. The ‘svg’ element
    2. 4.2. Grouping: the ‘g’ element
      1. 4.2.1. Overview
      2. 4.2.2. The ‘g’ element
    3. 4.3. Unknown elements
    4. 4.4. Defining content for reuse, and the ‘defs’ element
      1. 4.4.1. Overview
      2. 4.4.2. The ‘defs’ element
    5. 4.5. The ‘desc’ and ‘title’ elements
      1. 4.5.1. Definition
    6. 4.6. The ‘metadata’ element
    7. 4.7. The ‘symbol’ element
      1. 4.7.1. Attributes
      2. 4.7.2. Notes on symbols
    8. 4.8. The ‘use’ element
      1. 4.8.1. The use-element shadow tree
      2. 4.8.2. Layout of re-used graphics
      3. 4.8.3. Style Scoping and Inheritance
      4. 4.8.4. Multimedia in use-element shadow trees
      5. 4.8.5. Animations in use-element shadow trees
      6. 4.8.6. Event handling in use-element shadow trees
    9. 4.9. Conditional processing
      1. 4.9.1. Conditional processing overview
      2. 4.9.2. Definitions
      3. 4.9.3. The ‘switch’ element
      4. 4.9.4. The ‘requiredExtensions’ attribute
      5. 4.9.5. The ‘systemLanguage’ attribute
    10. 4.10. HTML metadata elements
    11. 4.11. Common attributes
      1. 4.11.1. Definitions
      2. 4.11.2. Attributes common to all elements: ‘id’
      3. 4.11.3. The ‘lang’ and ‘xml:lang’ attributes
      4. 4.11.4. The ‘xml:space’ attribute
      5. 4.11.5. The ‘tabindex’ attribute
      6. 4.11.6. The ‘data-*’ attributes
    12. 4.12. WAI-ARIA attributes
      1. 4.12.1. Definitions
      2. 4.12.2. Role attribute
      3. 4.12.3. State and property attributes (all aria- attributes)
      4. 4.12.4. Implicit and Allowed ARIA Semantics
    13. 4.13. DOM interfaces
      1. 4.13.1. Extensions to the Document interface
      2. 4.13.2. Interface SVGSVGElement
      3. 4.13.3. Interface SVGGElement
      4. 4.13.4. Interface SVGUnknownElement
      5. 4.13.5. Interface SVGDefsElement
      6. 4.13.6. Interface SVGDescElement
      7. 4.13.7. Interface SVGMetadataElement
      8. 4.13.8. Interface SVGTitleElement
      9. 4.13.9. Interface SVGSymbolElement
      10. 4.13.10. Interface SVGUseElement
      11. 4.13.11. Interface SVGUseElementShadowRoot
      12. 4.13.12. Interface SVGElementInstance
      13. 4.13.13. Interface ShadowAnimation
      14. 4.13.14. Interface SVGSwitchElement
      15. 4.13.15. Interface GetSVGDocument
  5. 5. Styling
    1. 5.1. Styling SVG content using CSS
    2. 5.2. Inline style sheets: the ‘style’ element
    3. 5.3. External style sheets: the effect of the HTML ‘link’ element
    4. 5.4. Style sheets in HTML documents
    5. 5.5. Element-specific styling: the ‘class’ and ‘style’ attributes
    6. 5.6. Presentation attributes
    7. 5.7. Required properties
    8. 5.8. User agent style sheet
    9. 5.9. Required CSS features
    10. 5.10. DOM interfaces
      1. 5.10.1. Interface SVGStyleElement
  6. 6. Geometry Properties
    1. 6.1. Horizontal center coordinate: The ‘cx’ property
    2. 6.2. Vertical center coordinate: The ‘cy’ property
    3. 6.3. Radius: The ‘r’ property
    4. 6.4. Horizontal radius: The ‘rx’ property
    5. 6.5. Vertical radius: The ‘ry’ property
    6. 6.6. Horizontal coordinate: The ‘x’ property
    7. 6.7. Vertical coordinate: The ‘y’ property
    8. 6.8. Sizing properties: the effect of the ‘width’ and ‘height’ properties
  7. 7. Coordinate Systems, Transformations and Units
    1. 7.1. Introduction
    2. 7.2. Computing the equivalent transform of an SVG viewport
    3. 7.3. The initial viewport
    4. 7.4. The initial coordinate system
    5. 7.5. The ‘transform’ property
    6. 7.6. The ‘viewBox’ attribute
    7. 7.7. The ‘preserveAspectRatio’ attribute
    8. 7.8. Establishing a new SVG viewport
    9. 7.9. Units
    10. 7.10. Bounding boxes
    11. 7.11. Object bounding box units
    12. 7.12. Intrinsic sizing properties of SVG content
    13. 7.13. Vector effects
      1. 7.13.1. Computing the vector effects
      2. 7.13.2. Computing the vector effects for nested viewport coordinate systems
      3. 7.13.3. Examples of vector effects
    14. 7.14. DOM interfaces
      1. 7.14.1. Interface SVGTransform
      2. 7.14.2. Interface SVGTransformList
      3. 7.14.3. Interface SVGAnimatedTransformList
      4. 7.14.4. Interface SVGPreserveAspectRatio
      5. 7.14.5. Interface SVGAnimatedPreserveAspectRatio
  8. 8. Paths
    1. 8.1. Introduction
    2. 8.2. The ‘path’ element
    3. 8.3. Path data
      1. 8.3.1. General information about path data
      2. 8.3.2. Specifying path data: the ‘d’ property
      3. 8.3.3. The "moveto" commands
      4. 8.3.4. The "closepath" command
      5. 8.3.5. The "lineto" commands
      6. 8.3.6. The cubic Bézier curve commands
      7. 8.3.7. The quadratic Bézier curve commands
      8. 8.3.8. The elliptical arc curve commands
      9. 8.3.9. The bearing commands
      10. 8.3.10. The grammar for path data
    4. 8.4. Path directionality
    5. 8.5. Implementation notes
      1. 8.5.1. Error handling in path data
    6. 8.6. Distance along a path
      1. 8.6.1. The ‘pathLength’ attribute
    7. 8.7. DOM interfaces
      1. 8.7.1. Interface SVGPathElement
  9. 9. Basic Shapes
    1. 9.1. Introduction and definitions
    2. 9.2. The ‘rect’ element
    3. 9.3. The ‘circle’ element
    4. 9.4. The ‘ellipse’ element
    5. 9.5. The ‘line’ element
    6. 9.6. The ‘polyline’ element
    7. 9.7. The ‘polygon’ element
    8. 9.8. The ‘mesh’ element
    9. 9.9. DOM interfaces
      1. 9.9.1. Interface SVGRectElement
      2. 9.9.2. Interface SVGCircleElement
      3. 9.9.3. Interface SVGEllipseElement
      4. 9.9.4. Interface SVGLineElement
      5. 9.9.5. Interface SVGMeshElement
      6. 9.9.6. Interface SVGAnimatedPoints
      7. 9.9.7. Interface SVGPointList
      8. 9.9.8. Interface SVGPolylineElement
      9. 9.9.9. Interface SVGPolygonElement
  10. 10. Text
    1. 10.1. Introduction
      1. 10.1.1. Definitions
      2. 10.1.2. Fonts and glyphs
      3. 10.1.3. Glyph metrics and layout
    2. 10.2. The ‘text’ and ‘tspan’ elements
      1. 10.2.1. Attributes
      2. 10.2.2. Notes on 'x', 'y', 'dx', 'dy' and 'rotate'
    3. 10.3. Text layout – Introduction
    4. 10.4. Text layout – Content Area
      1. 10.4.1. The ‘inline-size’ property
      2. 10.4.2. The ‘shape-inside’ property
      3. 10.4.3. The ‘shape-subtract’ property
      4. 10.4.4. The ‘shape-image-threshold’ property
      5. 10.4.5. The ‘shape-margin’ property
      6. 10.4.6. The ‘shape-padding’ property
    5. 10.5. Text layout – Algorithm
    6. 10.6. Pre-formatted text
      1. 10.6.1. Multi-line text via 'white-space'
      2. 10.6.2. Repositioning Glyphs
    7. 10.7. Auto-wrapped text
      1. 10.7.1. Notes on Text Wrapping
        1. 10.7.1.1. First Line Positioning
        2. 10.7.1.2. Broken Lines
    8. 10.8. Text on a path
      1. 10.8.1. The ‘textPath’ element
      2. 10.8.2. Attributes
      3. 10.8.3. Text on a path layout rules
    9. 10.9. Text rendering order
    10. 10.10. Properties and pseudo-elements
      1. 10.10.1. SVG properties
        1. 10.10.1.1. Text alignment, the ‘text-anchor’ property
        2. 10.10.1.2. The ‘glyph-orientation-horizontal’ property
        3. 10.10.1.3. The ‘glyph-orientation-vertical’ property
        4. 10.10.1.4. The ‘kerning’ property
      2. 10.10.2. SVG adaptions
        1. 10.10.2.1. The ‘font-variant’ property
        2. 10.10.2.2. The ‘line-height’ property
        3. 10.10.2.3. The ‘writing-mode’ property
        4. 10.10.2.4. The ‘direction’ property
        5. 10.10.2.5. The ‘dominant-baseline’ property
        6. 10.10.2.6. The ‘alignment-baseline’ property
        7. 10.10.2.7. The ‘baseline-shift’ property
        8. 10.10.2.8. The ‘letter-spacing’ property
        9. 10.10.2.9. The ‘word-spacing’ property
        10. 10.10.2.10. The ‘text-overflow’ property
      3. 10.10.3. White space
        1. 10.10.3.1. SVG 2 Preferred white space handling, the ‘white-space’ property
        2. 10.10.3.2. Legacy white-space handling, the ‘xml:space’ property
        3. 10.10.3.3. Duplicate white-space directives
    11. 10.11. Text decoration
      1. 10.11.1. The ‘text-decoration-fill’ and ‘text-decoration-stroke’ properties
    12. 10.12. Text selection and clipboard operations
    13. 10.13. DOM interfaces
      1. 10.13.1. Interface SVGTextContentElement
      2. 10.13.2. Interface SVGTextPositioningElement
      3. 10.13.3. Interface SVGTextElement
      4. 10.13.4. Interface SVGTSpanElement
      5. 10.13.5. Interface SVGTextPathElement
  11. 11. Embedded Content
    1. 11.1. Overview
    2. 11.2. Placement of the referenced resource
    3. 11.3. The ‘image’ element
    4. 11.4. HTML5 elements in SVG subtrees
    5. 11.5. Foreign namespaces and private data
    6. 11.6. Embedding foreign object types
    7. 11.7. The ‘foreignObject’ element
    8. 11.8. DOM interfaces
      1. 11.8.1. Interface SVGImageElement
      2. 11.8.2. Interface SVGForeignObjectElement
  12. 12. Painting: Filling, Stroking and Marker Symbols
    1. 12.1. Introduction
      1. 12.1.1. Definitions
    2. 12.2. Specifying paint
    3. 12.3. The effect of the ‘color’ property
    4. 12.4. Fill properties
      1. 12.4.1. Specifying fill paint: the ‘fill’ property
      2. 12.4.2. Winding rule: the ‘fill-rule’ property
      3. 12.4.3. Fill paint opacity: the ‘fill-opacity’ property
    5. 12.5. Stroke properties
      1. 12.5.1. Specifying stroke paint: the ‘stroke’ property
      2. 12.5.2. Stroke paint opacity: the ‘stroke-opacity’ property
      3. 12.5.3. Stroke width: the ‘stroke-width’ property
      4. 12.5.4. Drawing caps at the ends of strokes: the ‘stroke-linecap’ property
      5. 12.5.5. Controlling line joins: the ‘stroke-linejoin’ and ‘stroke-miterlimit’ properties
      6. 12.5.6. Dashing strokes: the ‘stroke-dasharray’ and ‘stroke-dashoffset’ properties
      7. 12.5.7. Computing the shape of the stroke
      8. 12.5.8. Computing the circles for the arcs 'stroke-linejoin'
      9. 12.5.9. Adjusting the circles for the arcs 'stroke-linejoin' when the initial circles do not intersect
    6. 12.6. Vector effects
    7. 12.7. Markers
      1. 12.7.1. The ‘marker’ element
      2. 12.7.2. Vertex markers: the ‘marker-start’, ‘marker-mid’ and ‘marker-end’ properties
      3. 12.7.3. Marker shorthand: the ‘marker’ property
      4. 12.7.4. Rendering markers
    8. 12.8. Controlling paint operation order: the ‘paint-order’ property
    9. 12.9. Color space for interpolation: the ‘color-interpolation’ property
    10. 12.10. Rendering hints
      1. 12.10.1. The ‘color-rendering’ property
      2. 12.10.2. The ‘shape-rendering’ property
      3. 12.10.3. The ‘text-rendering’ property
      4. 12.10.4. The ‘image-rendering’ property
    11. 12.11. The effect of the ‘will-change’ property
    12. 12.12. DOM interfaces
      1. 12.12.1. Interface SVGMarkerElement
  13. 13. Paint Servers: Solid Colors, Gradients, Patterns and Hatches
    1. 13.1. Introduction
      1. 13.1.1. Using paint servers as templates
    2. 13.2. Solid colors
      1. 13.2.1. Properties
    3. 13.3. Gradients
      1. 13.3.1. Definitions
      2. 13.3.2. Linear gradients
        1. 13.3.2.1. Attributes
        2. 13.3.2.2. Notes on linear gradients
      3. 13.3.3. Radial gradients
        1. 13.3.3.1. Attributes
        2. 13.3.3.2. Notes on radial gradients
      4. 13.3.4. Mesh gradients
        1. 13.3.4.1. Mesh Structure
        2. 13.3.4.2. Painting a Mesh Patch
        3. 13.3.4.3. Attributes
      5. 13.3.5. Gradient stops
        1. 13.3.5.1. Attributes
        2. 13.3.5.2. Properties
        3. 13.3.5.3. Notes on gradient stops
    4. 13.4. Patterns
      1. 13.4.1. Attributes
      2. 13.4.2. Notes on patterns
    5. 13.5. Hatches
      1. 13.5.1. Attributes
      2. 13.5.2. Notes on hatches
      3. 13.5.3. Hatch paths
        1. 13.5.3.1. Attributes
        2. 13.5.3.2. Notes on hatch paths
    6. 13.6. DOM interfaces
      1. 13.6.1. Interface SVGSolidcolorElement
      2. 13.6.2. Interface SVGGradientElement
      3. 13.6.3. Interface SVGLinearGradientElement
      4. 13.6.4. Interface SVGRadialGradientElement
      5. 13.6.5. Interface SVGMeshGradientElement
      6. 13.6.6. Interface SVGMeshrowElement
      7. 13.6.7. Interface SVGMeshpatchElement
      8. 13.6.8. Interface SVGStopElement
      9. 13.6.9. Interface SVGPatternElement
      10. 13.6.10. Interface SVGHatchElement
      11. 13.6.11. Interface SVGHatchpathElement
  14. 14. Scripting and Interactivity
    1. 14.1. Introduction
    2. 14.2. Supported events
    3. 14.3. User interface events
    4. 14.4. Pointer events
    5. 14.5. Hit-testing and processing order for user interface events
      1. 14.5.1. Hit-testing
      2. 14.5.2. Event processing
    6. 14.6. The ‘pointer-events’ property
    7. 14.7. Magnification and panning
    8. 14.8. Cursors
      1. 14.8.1. The effect of the ‘cursor’ property
      2. 14.8.2. The ‘cursor’ element
    9. 14.9. Focus
    10. 14.10. Event attributes
      1. 14.10.1. Animation event attributes
    11. 14.11. The ‘script’ element
    12. 14.12. DOM interfaces
      1. 14.12.1. Interface SVGCursorElement
      2. 14.12.2. Interface SVGScriptElement
  15. 15. Linking
    1. 15.1. References
      1. 15.1.1. Overview
      2. 15.1.2. Definitions
      3. 15.1.3. URLs and URIs
      4. 15.1.4. Syntactic forms: URL and <url>
      5. 15.1.5. URL reference attributes
      6. 15.1.6. Deprecated XLink URL reference attributes
      7. 15.1.7. Processing of URL references
        1. 15.1.7.1. Generating the absolute URL
        2. 15.1.7.2. Fetching the document
        3. 15.1.7.3. Processing the subresource document
        4. 15.1.7.4. Identifying the target element
        5. 15.1.7.5. Valid URL targets
    2. 15.2. Links out of SVG content: the ‘a’ element
    3. 15.3. Linking into SVG content: URL fragments and SVG views
      1. 15.3.1. SVG fragment identifiers
      2. 15.3.2. SVG fragment identifiers definitions
      3. 15.3.3. Predefined views: the ‘view’ element
    4. 15.4. DOM interfaces
      1. 15.4.1. Interface SVGAElement
      2. 15.4.2. Interface SVGViewElement
  16. Appendix A: SVG Document Object Model (DOM)
    1. A.1. SVG DOM overview
      1. A.1.1. SVG DOM object initialization
    2. A.2. Elements in the SVG DOM
    3. A.3. Naming conventions
    4. A.4. Relationship with DOM Level 3 Events
    5. A.5. Relationship with DOM Level 2 CSS
      1. A.5.1. User agents that support styling with CSS
    6. A.6. Invalid values
  17. Appendix B: IDL Definitions
  18. Appendix C: Implementation Requirements
    1. C.1. Introduction
    2. C.2. Error processing
    3. C.3. Clamping values which are restricted to a particular range
    4. C.4. Elliptical arc implementation notes
      1. C.4.1. Elliptical arc syntax
      2. C.4.2. Out-of-range parameters
      3. C.4.3. Parameterization alternatives
      4. C.4.4. Conversion from center to endpoint parameterization
      5. C.4.5. Conversion from endpoint to center parameterization
      6. C.4.6. Correction of out-of-range radii
    5. C.5. Text selection implementation notes
    6. C.6. Printing implementation notes
  19. Appendix D: Conformance Criteria
    1. D.1. Introduction
    2. D.2. Conforming SVG Document Fragments
    3. D.3. Conforming SVG Stand-Alone Files
    4. D.4. Conforming SVG Generators
    5. D.5. Conforming SVG Servers
    6. D.6. Conforming SVG DOM Subtree
    7. D.7. Conforming SVG Interpreters
    8. D.8. Conforming SVG Viewers
      1. D.8.1. Conforming High-Quality SVG Viewer
  20. Appendix E: Accessibility Support
    1. E.1. SVG Accessibility Features
    2. E.2. Supporting SVG Accessibility Specifications and Guidelines
  21. Appendix F: References
    1. F.1. Normative references
    2. F.2. Informative references
  22. Appendix G: Element Index
  23. Appendix H: Attribute Index
    1. H.1. Regular attributes
    2. H.2. Presentation attributes
  24. Appendix I: Property Index
  25. Appendix J: IDL Index
  26. Appendix K: Media Type Registration for image/svg+xml
    1. K.1. Introduction
    2. K.2. Registration of media type image/svg+xml
  27. Appendix L: Changes from SVG 1.1
    1. L.1. Editorial changes
    2. L.2. Substantial changes
      1. L.2.1. Across the whole document
      2. L.2.2. Concepts
      3. L.2.3. Rendering Model chapter
      4. L.2.4. Basic Data Types and Interfaces chapter
      5. L.2.5. Document Structure chapter
      6. L.2.6. Styling chapter
      7. L.2.7. Geometry Properties chapter
      8. L.2.8. Coordinate Systems, Transformations and Units chapter
      9. L.2.9. Paths chapter
      10. L.2.10. Basic Shapes chapter
      11. L.2.11. Text chapter
      12. L.2.12. Embedded Content chapter
      13. L.2.13. Painting chapter
      14. L.2.14. Color chapter
      15. L.2.15. Paint Servers chapter
      16. L.2.16. Clipping, Masking and Compositing chapter
      17. L.2.17. Filter Effects chapter
      18. L.2.18. Interactivity chapter
      19. L.2.19. Linking chapter
      20. L.2.20. Scripting chapter
      21. L.2.21. Animation chapter
      22. L.2.22. Fonts chapter
      23. L.2.23. Extensibility chapter
      24. L.2.24. Document Type Definition appendix
      25. L.2.25. SVG Document Object Model (DOM) appendix
      26. L.2.26. Java Language Binding appendix
      27. L.2.27. ECMAScript Language Binding appendix
      28. L.2.28. References appendix
      29. L.2.29. IDL Index appendix
      30. L.2.30. Feature Strings
SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 1: Introduction

1.1. About SVG

This specification defines the features and syntax for Scalable Vector Graphics (SVG).

SVG is a language for describing two-dimensional graphics. As a standalone format or when mixed with other XML, it uses the XML syntax [XML10]. SVG code used inside HTML documents uses the HTML syntax [HTML]. SVG allows for three types of graphic objects: vector graphic shapes (e.g., paths consisting of straight lines and curves), images and text. Graphical objects can be grouped, styled, transformed and composited. The feature set includes nested transformations, clipping paths, alpha masks, filter effects and template objects.

SVG drawings can be interactive and dynamic. Animations can be defined and triggered either declaratively (i.e., by embedding SVG animation elements in SVG content) or via scripting.

Sophisticated applications of SVG are possible by use of a supplemental scripting language which accesses SVG Document Object Model (DOM), which provides complete access to all elements, attributes and properties. A rich set of event handlers can be assigned to any SVG graphical object. Within a web page, the same scripts can work on both HTML and SVG elements. Scripting.

SVG is useful for rich graphical presentation of information, including a number of accessibility features that, used correctly, ensure the content can be used by the widest possible audience. But a direct link to source data, where possible, is helpful for many people to understand the content provided.

1.2. Compatibility with other standards efforts

SVG leverages and integrates with other W3C specifications and standards efforts, as described in the following:

1.3. Conformance

Within this specification, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels [RFC2119]. However, for readability, these words do not appear in all uppercase letters in this specification.

At times, this specification recommends good practice for authors and user agents.

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 2: Rendering Model

SVG 2 Requirement: Support the z-index.

Resolution: We will add Jonathan Watt's z-index proposal to SVG 2.

Auckland 2011 F2F day 5.

Purpose: Allow reordering (such as when a planet orbits the sun). Reordering without script support (e.g. CSS :hover).

Owner: Jonathan (Action 3002).

Status: Done.

The SVG 2 rendering model will follow the rules defined by the Compositing and Blending specification.

Resolution: Seattle/Paris 2012 F2F day 3.

Owner: Nikos (Action 3332).

Status: Done.

2.1. Introduction

Implementations of SVG must implement the rendering model as described in this chapter, as modified in the appendix on conformance requirementswhich describes situations where an implementation may deviate. In practice variability is allowed based on limitations of the output device (e.g. only a limited range of colors might be supported) and because of practical limitations in implementing a precise mathematical model (e.g. for realistic performance curves are approximated by straight lines, the approximation need only be sufficiently precise to match the conformance requirements).

The appendix on conformance requirements describes the extent to which an actual implementation may deviate from this description. In practice an actual implementation may deviate slightly because of limitations of the output device (e.g. only a limited range of colors might be supported) and because of practical limitations in implementing a precise mathematical model (e.g. for realistic performance curves are approximated by straight lines, the approximation need only be sufficiently precise to match the conformance requirements).

2.2. The rendering tree

The components of the final rendered representation of an SVG document do not have a one-to-one relationship with the underlying elements in the document model. The appearance of the graphic instead reflects a parallel structure, the rendering tree, in which some elements are excluded and others are repeated.

Many elements in the SVG namespace do not directly represent a component of the graphical document. Instead, they define graphical effects, metadata, content to be used to represent other elements, or alternatives to be displayed under certain conditions. In dynamic documents, certain components of the graphic may be rendered or not, depending on interaction or animation. These non-rendered elements are not directly included in the rendering tree.

Because SVG supports the reuse of graphical sub-components, some elements are rendered multiple times. The individual renderings may have context-dependent styling and may be rasterized at different scales or transformations.

2.2.1. Definitions

rendering tree

The rendering tree is the set of elements being rendered in an SVG document fragment. It is generated from the document tree by excluding non-rendered elements and inserting additional fragments for re-used graphics. Graphics are painted and composited in rendering-tree order, subject to stacking and re-ordering based on the z-index and paint-order properties. Note that elements that have no visual paint may still be in the rendering tree.

rendered element

An element that has a direct representation in the rendering tree for the current document. Includes a rendered instance of an element in a use-element shadow tree. Does not include elements that affect rendering as the source definition of re-used graphics but are not directly rendered themselves. See Rendered versus non-rendered elements

non-rendered element

An element that does not have a direct representation in the rendering tree for the current document. It may nonetheless affect the rendering tree as re-used graphics or graphical effects. See Rendered versus non-rendered elements.

re-used graphics

Graphical components that are included in the rendering tree but do not have a single direct equivalent element in the document model. They may be represented through shadow DOM elements (as in graphics re-used with a use element), or as image fragments generated as part of a graphical effect (as in patterns or masks).

never-rendered element

Any element type that is never directly rendered, regardless of context or display style value. It includes the following elements: clipPath, defs, desc, hatch, linearGradient, marker, mask, meshgradient, metadata, pattern, radialGradient, script, style and title; it also includes a symbol element that is not the instance root of a use-element shadow tree.

renderable element

Any element type that can have a direct representation in the rendering tree, as a graphic, container, text, audio, or animation. It includes the following elements: a, audio, canvas, circle, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, text, textPath, tspan, unknown, use and video; it also includes a symbol element that is the instance root of a use-element shadow tree.

A renderable element may or may not be rendered in a given document or point in time.

2.2.2. Rendered versus non-rendered elements

At any given time, every SVG element (or element instance in a use-element shadow tree) is either rendered or non-rendered. Whether an element is currently rendered or not affects not only its visual display but also interactivity and geometric calculations.

An element is not rendered in any of these four situations:

Non-rendered elements:

Non-rendered elements are not represented in the document accessibility tree. Nonetheless, they remain part of the document model, and participate in style inheritance and cascade.

2.2.3. Controlling visibility: the effect of the ‘display’ and ‘visibility’ properties

SVG uses two properties to toggle the visible display of elements that are normally rendered: display and visibility. Although they have a similar visible effect in static documents, they are conceptually distinct.

See the CSS 2.1 specification for the definitions of display and visibility. [CSS21]

Setting display to none results in the element not being rendered. When applied to graphics elements, text content elements, and container elements that are normally rendered, setting display to none results in the element (and all its descendents) not becoming part of the rendering tree. Note that display is not an inherited property.

Elements that have any other display value than none are rendered as normal.

The display property only applies to renderable elements. Setting display: none on an element that is never directly rendered or not rendered based on conditional processing has no effect.

The display property affects the direct processing of a given element, but it does not prevent it from being referenced by other elements. For example, setting display: none on a path element will prevent that element from getting rendered directly onto the canvas, but the path element can still be referenced by a textPath element and its geometry will be used in text-on-a-path processing.

When applied to a graphics element, setting visibility to hidden or collapse results in the element not being painted. It is, however, still part of the rendering tree. It may be sensitive to pointer events (depending on the value of pointer-events), may receive focus (depending on the value of tabindex), contributes to bounding box calculations and clipping paths, and does affect text layout.

The visibility property only directly applies to graphics elements, including text content elements. Since visibility is an inherited property, however, although it has no effect on a use element or container element itself, its inherited value can affect descendant elements.

2.2.4. Re-used graphics

Graphical content defined in one part of the document (or in another document) may be used to render other elements. There are two types of re-used graphics from a rendering perspective:

Shadow DOM elements are rendered in the same way as normal elements, as if the host element (e.g., the use element) was a container and the shadow content was its descendents. Style and geometry properties on the shadow DOM elements are resolved independently from those on their corresponding element in the source document. The display property has its normal effect on shadow elements, except for special rules that apply to the symbol element.

Unless properties on the host element create a stacking context, z-index values on shadow DOM elements can change their rendering order relative to elements in the main DOM. For blending purposes, the use element forms a non-isolated group.

In contrast, graphical effects elements generate a self-contained SVG fragment which is rendered independently as a stacking context and an isolated group. The canvas for this fragment is scaled The graphical effect element's child content is rendered and composited into this canvas. The flattened canvas as a whole is treated as a vector image when compositing and blending with other paint layers

The display property on any child content of a graphical effects element has its normal effect when set to none, excluding that subtree from being used in rendering. However, the graphical effect is not altered by a value of display: none on the graphical effect element or an ancestor.

2.3. The painters model

SVG uses a "painters model" of rendering. Paint is applied in successive operations to the output device such that each operation paints onto some area of the output device, possibly obscuring paint that has previously been layed down. After each object or group is painted, it becomes part of the background for the next painting operation. SVG 2 supports advanced blending modes and compositing operations that control how each painting operation interacts with the background. The rules governing these painting operations are outlined in the Compositing and Blending Specification.

2.4. Rendering order

Elements in SVG are positioned in three dimensions. In addition to their position on the x and y axis of the SVG viewport, SVG elements are also positioned on the z axis. The position on the z-axis defines the order that they are painted.

Along the z axis, elements are grouped into stacking contexts, each stacking context has an associated stack level. A stack level may contain one or more child nodes - either child stack levels, graphics elements, or g elements. graphics elements and g elements within single stack level are painted in document order - that is, they are painted in the order that they are defined in the document.

Each stack level is assigned an integer value that defines it's position on the z axis relative to other stack levels within the same stacking context. Lower values are painted first, and so elements in a stack level with a higher value will paint over one with a lower value.

By default, everything is placed in stack level zero.

2.4.1. Controlling element rendering order: the ‘z-index’ property

This feature is at risk.

See the CSS 2.1 specification for the definition of z-index. [CSS21]

The z-index property allows an element to be assigned to a stack level.

The rules governing behavior for SVG elements with the z-index property specified are outlined below:

CSS specifies a property named z-index. The CSS rules that define the effect of the ‘z-index’ property were written specifically for the CSS box model, and those rules do not make sense as they stand for most SVG elements (most SVG elements do not participate in or establish a CSS box model layout). This section specifies how implementations must handle the z-index property on elements in the SVG namespace.

Contrary to the rules in CSS 2.1, the z-index property applies to all SVG elements regardless of the value of the position property, with one exception: as for boxes in CSS 2.1, outer svg elements must be positioned for z-index to apply to them.

The z-index property specifies:

  1. The stack level of the element in the current stacking context.
  2. Whether the element establishes a new local stacking context.

Values have the following meanings:

<integer>
This integer is the stack level of the element in the current stacking context. The element also establishes a new local stacking context for its descendants.
auto
The stack level of the element in the current stacking context is the same as its parent element, unless its parent established a new stacking context, in which case its stack level is 0. The element does not establish a new local stacking context.

Here is a simple example:

<svg xmlns="http://www.w3.org/2000/svg">
  <rect x="0"  width="100" height="100" style="fill: red;    z-index: -1;"/>
  <rect x="40" width="100" height="100" style="fill: lime;"/>
  <rect x="80" width="100" height="100" style="fill: blue;   z-index: 1;/>
  <rect x="60" width="100" height="100" style="fill: aqua;"/>
  <rect x="20" width="100" height="100" style="fill: yellow; z-index: -1;"/>
</svg>

In this example there are three stack levels: -1, 0 (the default) and 1. The red and yellow rects are in stack level -1, the lime and aqua rects are in stack level 0 (the default), and the blue rect is in stack level 1. Going from lowest stack level to highest, and painting the elements in each stack level in document order, the painting order is: red, yellow, lime, aqua, blue.

2.4.2. Establishing a stacking context in SVG

A new stacking context must be established at an SVG element for its descendants if:

Stacking contexts and stack levels are conceptual tools used to describe the order in which elements must be painted one on top of the other when the document is rendered, and for determining which element is highest when determining the target of a pointer event. Stacking contexts and stack levels do not affect the position of elements in the DOM tree, and their presence or absence does not affect an element's position, size or orientation in the canvas' X-Y plane - only the order in which it is painted.

Stacking contexts can contain further stacking contexts. A stacking context is atomic from the point of view of its parent stacking context; elements in ancestor stacking contexts may not come between any of its elements.

Each element belongs to one stacking context. Each element in a given stacking context has an integer stack level. Elements with a higher stack level must be placed in front of elements with lower stack levels in the same stacking context. Elements may have negative stack levels. Elements with the same stack level in a stacking context must be stacked according to document order.

With the exception of the foreignObject element, the back to front stacking order for a stacking context created by an SVG element is:

  1. the background and borders of the element forming the stacking context, if any
  2. child stacking contexts created by descendants with negative stack levels, primarily ordered by most negative first, then by tree order
  3. descendants with 'z-index: auto' or 'z-index: 0', in tree order
  4. child stacking contexts created by descendants with positive stack levels, primarily ordered by lowest index first, then by tree order

Since the foreignObject element creates a "fixed position containing block" in CSS terms, the normative rules for the stacking order of the stacking context created by foreignObject elements are the rules in Appendix E of CSS 2.1.

In the following example, the z-index property on the g element is set to zero. This creates a new stacking context to contain the g element's children without moving the g to a different level in the document's root stacking context:

<svg xmlns="http://www.w3.org/2000/svg">
  <g style="z-index: 0;">
    <!-- this is a self contained graphic -->
    <rect x="40" width="100" height="100" style="fill: lime; z-index: 1;"/>
    <rect x="20" width="100" height="100" style="fill: yellow;"/>
  </g>
  <rect x="60" width="100" height="100" style="fill: aqua;"/>
  <rect x="0" width="100" height="100" style="fill: red; z-index: -1;"/>
</svg>

The example's root stacking context contains two stack levels: -1 and 0. The red rect is in level -1, and the g element and aqua rect are in level 0. Inside stack level 0, the g element's z-index property creates a new nested stacking context at the g for the g element's children. In this child stacking context there are two stack levels: 0 and 1. The yellow rect is in level 0 (the default), and the lime rect is in level 1.

Painting of this example starts with the stack levels of the root stacking context. First the red rect is painted in level -1, then in level 0 the g element is painted followed by the aqua rect. When the g element is painted, the child stacking context that its z-index created and all of that context's stack levels are also painted. In this child stacking context, first the yellow rect in level 0 is painted, followed by the lime rect in level 1. It's only after the g and the stacking context that it creates has been painted that the aqua rect is painted. Note that this means that although the z-index of 1 for the lime rect is a higher value than the (implicit) z-index of 0 for the aqua rect, the containment provided by the g's child stacking context results in the aqua rect painting over the lime rect. The painting order is therefore: red, yellow, lime, aqua.

2.5. How elements are rendered

Individual graphics elements are treated as if they are a non-isolated group, the components (fill, stroke, etc) that make up a graphic element (See Painting shapes and text) being members of that group. See How groups are rendered.

2.6. How groups are rendered

Grouping elements, such as the g element (see container elements ) create a compositing group. Similarly, a use element creates a compositing group for its shadow content. The Compositing and Blending specification normatively describes how to render compositing groups. In SVG, effects may be applied to a group. For example, opacity, filters or masking. These effects are applied to the rendered result of the group immediately before any transforms on the group are applied, which are applied immediately before the group is blended and composited with the group backdrop. Applying any such effects to a group makes that group isolated.

Thus, rendering a compositing group follows the following steps:
If the group is isolated:

  1. The initial backdrop is set to a new buffer initialised with rgba(0,0,0,0)
  2. The contents of the group that are graphics elements or g elements are rendered in order, onto the initial backdrop
  3. filters and other effects that modify the group canvas are applied

    To provide for high quality rendering, filter primitives and other bitmap effects must be applied in the operating coordinate space.

  4. Group transforms are applied
  5. The group canvas is blended and composited with the group backdrop
else (the group is not isolated):
  1. The initial backdrop is set to the group backdrop
  2. The contents of the group that are graphics elements or g elements are rendered in order, onto the initial backdrop. The group transforms are applied to each element as they are rendered.

2.6.1. Object and group opacity: the effect of the ‘opacity’ property

See the CSS Color Module Level 3 for the definition of opacity. [CSS3COLOR]

The opacity property specifies how opaque a given graphical element or container element will be when it is painted to the canvas. When applied to a container element, this is known as group opacity, and when applied to an individual rendering element, it is known as object opacity. The principle for these two operations however is the same.

There are several other opacity-related properties in SVG:

These four opacity properties are involved in intermediate rendering operations. Object and group opacity however can be thought of as a post-processing operation. Conceptually, the object or group to which opacity applies is rendered into an RGBA offscreen image. The offscreen image as whole is then blended into the canvas with the specified opacity value used uniformly across the offscreen image. Thus, the presence of opacity causes the group to be isolated.

The opacity property applies to the following SVG elements: svg, g, symbol, marker, a, switch, graphics elements and text content child elements.

The following example illustrates various usage of the opacity property on objects and groups.

<svg xmlns="http://www.w3.org/2000/svg"
     width="600" height="175" viewBox="0 0 1200 350">

  <!-- Background blue rectangle -->
  <rect x="100" y="100" width="1000" height="150" fill="blue"/>

  <!-- Red circles going from opaque to nearly transparent -->
  <circle cx="200" cy="100" r="50" fill="red" opacity="1"/>
  <circle cx="400" cy="100" r="50" fill="red" opacity=".8"/>
  <circle cx="600" cy="100" r="50" fill="red" opacity=".6"/>
  <circle cx="800" cy="100" r="50" fill="red" opacity=".4"/>
  <circle cx="1000" cy="100" r="50" fill="red" opacity=".2"/>

  <!-- Opaque group, opaque circles -->
  <g opacity="1">
    <circle cx="182.5" cy="250" r="50" fill="red" opacity="1"/>
    <circle cx="217.5" cy="250" r="50" fill="green" opacity="1"/>
  </g>
  <!-- Group opacity: .5, opacity circles -->
  <g opacity=".5">
    <circle cx="382.5" cy="250" r="50" fill="red" opacity="1"/>
    <circle cx="417.5" cy="250" r="50" fill="green" opacity="1"/>
  </g>
  <!-- Opaque group, semi-transparent green over red -->
  <g opacity="1">
    <circle cx="582.5" cy="250" r="50" fill="red" opacity=".5"/>
    <circle cx="617.5" cy="250" r="50" fill="green" opacity=".5"/>
  </g>
  <!-- Opaque group, semi-transparent red over green -->
  <g opacity="1">
    <circle cx="817.5" cy="250" r="50" fill="green" opacity=".5"/>
    <circle cx="782.5" cy="250" r="50" fill="red" opacity=".5"/>
  </g>
  <!-- Group opacity .5, semi-transparent green over red -->
  <g opacity=".5">
    <circle cx="982.5" cy="250" r="50" fill="red" opacity=".5"/>
    <circle cx="1017.5" cy="250" r="50" fill="green" opacity=".5"/>
  </g>
</svg>
Image showing different groups of circles blended into the background.

Each group of red and green circles is first rendered to an offscreen image before being blended with the background blue rectangle as a whole, with the given opacity values.

In the example, the top row of circles have differing opacities, ranging from 1.0 to 0.2. The bottom row illustrates five g elements, each of which contains overlapping red and green circles, as follows:

2.7. Types of graphics elements

SVG supports three fundamental types of graphics elements that can be rendered onto the canvas:

2.7.1. Painting shapes and text

Shapes and text can be filled (i.e., apply paint to the interior of the shape) and stroked (i.e., apply paint along the outline of the shape).

For certain types of shapes, marker symbols (which themselves can consist of any combination of shapes, text and images) can be drawn at positions along the shape boundary. Each marker symbol is painted as if its graphical content were expanded into the SVG document tree just after the shape object which is using the given marker symbol. The graphical contents of a marker symbol are rendered using the same methods as graphics elements. Marker symbols are not applicable to text.

The order in which fill, stroke and markers are painted is determined by the paint-order property. The default is that fill is painted first, then the stroke, and then the marker symbols. The marker symbols are rendered in order along the outline of the shape, from the start of the shape to the end of the shape.

The fill and stroke operations are entirely independent painting operations. Each fill and stroke operation has its own opacity settings; thus, you can fill and/or stroke a shape with a semi-transparently drawn solid color, with different opacity values for the fill and stroke operations.

SVG supports numerous built-in types of paint which can be used in fill and stroke operations. These are described in Paint Servers.

2.7.2. Painting raster images

When a raster image is rendered, the original samples are "resampled" using standard algorithms to produce samples at the positions required on the output device. Resampling requirements are discussed under conformance requirements.

As in HTML [HTML, 10.4.2], all animated images with the same absolute URL and the same image data are expected to be rendered synchronised to the same timeline as a group, with the timeline starting at the time of the least recent addition to the group.

When a user agent is to restart the animation for an img element showing an animated image, all animated images with the same absolute URL and the same image data in that img element's node document are expected to restart their animation from the beginning.

2.8. Filtering painted regions

SVG allows any painting operation to be filtered. (See Filter Effects.)

In this case the result must be as though the paint operations had been applied to an intermediate canvas initialized to transparent black, of a size determined by the rules given in Filter Effects then filtered by the processes defined in Filter Effects.

2.9. Clipping and masking

SVG supports the following clipping/masking features:

Both, clipping and masking, are specified in the module CSS Masking [CSS-MASKING].

2.10. Parent compositing

SVG document fragments can be semi-opaque.

In accordance with the Compositing and Blending specification, the svg element always creates an isolated group.

When the SVG document is a top-level document, the top level SVG element is considered to be the page group and is composited with a backdrop of white with 100% opacity. For all other referencing modes, there is no page group. The SVG document is composited into the parent document with opacity preserved.

2.11. The effect of the ‘overflow’ property

See the Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification [CSS21] for the definition of overflow.

A summary of the behavior of the overflow property in SVG.
element initial ua stylesheet auto visible hidden scroll
document root svgvisiblen/avisible | scrollvisiblehiddenscroll
other svgvisiblehiddenvisible | scrollvisiblehiddenscroll
meshvisiblen/avisiblevisiblehiddenhidden
textvisiblehiddenvisiblevisiblehiddenhidden
patternvisiblehiddenvisiblevisiblehiddenhidden
hatchesvisiblehiddenvisiblevisiblehiddenhidden
markervisiblehiddenvisiblevisiblehiddenhidden
symbolvisiblehiddenvisiblevisiblehiddenhidden
imagevisiblehiddenvisiblevisiblehiddenhidden
iframevisiblen/avisiblevisiblehiddenhidden
foreignObjectvisiblen/avisiblevisiblehiddenhidden

The overflow property has the same parameter values and has the same meaning as defined in CSS 2.1 ([CSS21], section 11.1.1); however, the following additional points apply:

Although the initial value for overflow is auto. In the User Agent style sheet, overflow is overriden for the svg element when it is not the root element of a stand-alone document, the pattern element, hatch element, and the marker element to be hidden by default.
SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 3: Basic Data Types and Interfaces

3.1. Definitions

initial value

The initial value of an attribute or property is the value used when that attribute or property is not specified, or when it has an invalid value. This value is to be used for the purposes of rendering, calculating animation values, and when accessing the attribute or property via DOM interfaces.

invalid value
An invalid value specified for a property, either in a style sheet or a presentation attribute, is one that is either not allowed according to the grammar defining the property's values, or is allowed by the grammar but subsequently disallowed in prose. A CSS declaration with an invalid value is ignored; see Declarations and properties ([CSS21], section 4.1.8).

3.2. Attribute syntax

In this specification, attributes are defined with an attribute definition table, which looks like this:

Name Value Initial value Animatable
exampleattr <length> | none none yes

In the Value column is a description of the attribute's syntax. There are six methods for describing an attribute's syntax:

  1. Using the CSS Value Definition Syntax [CSS3VALUES]. This is the notation used to define the syntax for most attributes in this specification and is the default.
  2. By reference to an EBNF symbol defined in this or another specification [XML10]. For external definitions, this is indicated by [EBNF] appearing in the Value column.
  3. By reference to an ABNF symbol defined in another specification [STD68]. This is indicated by [ABNF] appearing in the Value column.
  4. As a URL as defined by the URL Standard [URL]. This is indicated by [URL] appearing in the Value column.
  5. As a type as defined by the HTML Standard [HTML]. This is indicated by [HTML] appearing in the Value column.
  6. In prose, below the attibute definition table. This is indicated by the text "(see below)" appearing in the Value column.
SVG 2 Requirement: Consider relaxing case sensitivity of presentation attribute values.
Resolution: We will make property values case insensitivity.
Purpose: To align presentation attribute syntax parsing with parsing of the corresponding CSS property.
Owner: Cameron (ACTION-3276)
Status: Done

When a presentation attribute defined using the CSS Value Definition Syntax is parsed, this is done as follows:

  1. Let value be the value of the attribute.
  2. Let grammar be the grammar given in the attribute definition table's Value column.
  3. Replace all instances of <length> in grammar with [<length> | <number>].
  4. Replace all instances of <angle> in grammar with [<angle> | <number>].
  5. Return the result of parsing value with grammar.

The insertion of the <number> symbols allows for unitless length and angles to be used in presentation attribute while disallowing them in corresponding property values.

Note that all presentation attributes, since they are defined by reference to their corresponding CSS properties, are defined using the CSS Value Definition Syntax.

When any other attribute defined using the CSS Value Definition Syntax is parsed, this is done by parsing the attribute's value according to the grammar given in attribute definition table.

Note that this allows CSS comments and escapes to be used in such attributes. For example, a value of '10\px/**/' would successfully parse as '10px' in the ‘x’ presentation attribute of the rect element.

When an attribute defined as a URL is parsed, this is done by invoking the URL parser with the attribute's value as input and the document's URL as base [URL].

The Initial value column gives the initial value for the attribute. When an attribute fails to parse according to the specified CSS Value Definition Syntax, ABNF or EBNF grammar, or if parsing according to the URL Standard or by the prose describing how to parse the attribute indicates failure, the attribute is assumed to have been specified as the given initial value.

The initial value of a presentation attribute is its corresponding property's initial value. Since the use of an invalid value in a presentation attribute will be treated as if the initial value was specified, this value can override values that come from lower priority style sheet rules, such as those from the user agent style sheet.

For example, although the user agent style sheet sets the value of the overflow property to hidden for svg elements, specifying an invalid presentation attribute such as overflow="invalid" will result in a rule setting overflow to visible, overriding the user agent style sheet value.

The Animatable column indicates whether the attribute can be animated using animation elements as defined in the SVG Animation module.

3.3. Real number precision

Unless stated otherwise, numeric values in SVG attributes and in properties that are defined to have an effect on SVG elements must support at least all finite single-precision values supported by the host architecture.

It is recommended that higher precision floating point storage and computation be performed on operations such as coordinate system transformations to provide the best possible precision and to prevent round-off errors.

Conforming SVG Viewers are required to perform numerical computation in accordance with their conformance class, as described in Conformance Criteria.

3.4. DOM interfaces for SVG elements

3.4.1. Interface SVGElement

All of the SVG DOM interfaces that correspond directly to elements in the SVG language (such as the SVGPathElement interface for the path element) derive from the SVGElement interface.

The CSSOM specification augments SVGElement with a style IDL attribute, so that the style attribute can be accessed in the same way as on HTML elements.

interface SVGElement : Element {

  [SameObject] readonly attribute SVGAnimatedString className;

  [SameObject] readonly attribute DOMStringMap dataset;

  readonly attribute SVGSVGElement? ownerSVGElement;
  readonly attribute SVGElement? viewportElement;

  attribute long tabIndex;
  void focus();
  void blur();
};

SVGElement implements GlobalEventHandlers;
SVGElement implements SVGElementInstance;

The className IDL attribute reflects the class attribute.

This attribute is deprecated and may be removed in a future version of this specification. Authors are advised to use Element.classList intead.

The dataset IDL attribute provides access to custom data attributes on the element. Its behavior is the same as the corresponding IDL member on the HTMLElement interface.

The ownerSVGElement IDL attribute represents the nearest ancestor svg element. On getting ownerSVGElement, the nearest ancestor svg element is returned; if the current element is the outermost svg element, then null is returned.

The viewportElement IDL attribute represents the element that provides the SVG viewport for the current element. On getting viewport, the nearest ancestor element that establishes an SVG viewport is returned; if the current element is the outermost svg element, then null is returned.

The tabIndex IDL attribute and the focus and blur methods are used to control focus on SVG elements in the document. Their behavior is the same as the corresponding IDL members on the HTMLElement interface.

As in HTML documents, the use of the blur method is discouraged. Authors are recommended to focus another element instead.

Authors are strongly suggested not to use the blur method or any other technique to hide the focus ring from keyboard users, such as using a CSS rule to override the outline property. Removal of the focus ring leads to serious accessibility issues for users who navigate and interact with interactive content using the keyboard.

3.4.2. Interface SVGGraphicsElement

SVG 2 Requirement: Detect if a mouse event is on the fill or stroke of a shape.
Resolution: SVG 2 will make it easier to detect if an mouse event is on the stroke or fill of an element.
Purpose: To allow authors to discriminate between pointer events on the fill and stroke of an element without having to duplicate the element
Owner: Cameron (ACTION-3279)
Status: Done.

The SVGGraphicsElement interface represents SVG elements whose primary purpose is to directly render graphics into a group.

dictionary SVGBoundingBoxOptions {
  boolean fill = true;
  boolean stroke = false;
  boolean markers = false;
  boolean clipped = false;
};

interface SVGGraphicsElement : SVGElement {
  [SameObject] readonly attribute SVGAnimatedTransformList transform;

  DOMRect getBBox(optional SVGBoundingBoxOptions options);
  DOMMatrix? getCTM();
  DOMMatrix? getScreenCTM();
};

SVGGraphicsElement implements SVGTests;

The transform IDL attribute reflects the computed value of the transform property and its corresponding ‘transform’ presentation attribute.

The getBBox method is used to compute the bounding box of the current element. When the getBBox(options) method is called, the bounding box algorithm is invoked for the current element, with fill, stroke, markers and clipped members of the options dictionary argument used to control which parts of the element are included in the bounding box, using the element's local coordinate system as the coordinate system to return the bounding box in. A newly created DOMRect object that defines the computed bounding box is returned.

The getCTM method is used to get the matrix that transforms the current element's coordinate system to its SVG viewport's coordinate system. When getCTM() is called, the following steps are run:

  1. If the current element is not in the document, then return null.
  2. Let ctm be a matrix determined based on what the current element is:
    the current element is the outermost svg element
    ctm is a matrix that transforms the coordinate space of the svg (including its transform property) to the coordinate space of the document's viewport. The matrix includes the transforms produced by the viewBox and preserveAspectRatio attributes, the transform property, and any transform due to currentScale and currentTranslate properties on the SVGSVGElement.
    any other element
    ctm is a matrix that transforms the coordinate space of the current element (including its transform property) to the coordinate space of its closest ancestor viewport-establishing element (also including its transform property).
  3. Return a newly created, detached DOMMatrix object that represents the same matrix as ctm.

The getScreenCTM method is used to get the matrix that transforms the current element's coordinate system to the coordinate system of the SVG viewport for the SVG document fragment. When getScreenCTM() is called, the following steps are run:

  1. If the current element is not in the document, then return null.
  2. Let ctm be a matrix that transforms the coordinate space of the current element (including its transform property) to the coordinate space of the document's viewport.

    This will include:

  3. Return a newly created, detached DOMMatrix object that represents the same matrix as ctm.

This method would have been more aptly named as getClientCTM, but the name getScreenCTM is kept for historical reasons.

3.4.3. Interface SVGGeometryElement

Interface SVGGeometryElement represents SVG elements whose rendering is defined by geometry with an equivalent path, and which can be filled and stroked. This includes paths and the basic shapes.

interface SVGGeometryElement : SVGGraphicsElement {
  [SameObject] readonly attribute SVGAnimatedNumber pathLength;

  boolean isPointInFill(DOMPoint point);
  boolean isPointInStroke(DOMPoint point);
  float getTotalLength();
  DOMPoint getPointAtLength(float distance);
};

The isPointInFill and isPointInStroke methods determine whether a given point is within the fill or stroke shape of an element. Normal hit testing rules apply; the value of the pointer-events property on the element determines whether a point is considered to be within the fill or stroke. The point argument is interpreted as a point in the local coordiante system of the element.

The pathLength IDL attribute reflects the pathLength content attribute.

The getTotalLength method is used to compute the length of the path. When getTotalLength() is called, the user agent's computed value for the total length of the path, in user units, is returned.

The user agent's computed path length does not take the pathLength attribute into account.

The getPointAtLength method is used to return the point at a given distance along the path. When getPointAtLength(distance) is called, the following steps are run:

  1. Let length be the user agent's computed value for the total length of the path, in user units.

    As with getTotalLength, this does not take into account the pathLength attribute.

  2. Clamp distance to [0, length].
  3. Let (x, y) be the point on the path at distance distance.
  4. Return a newly created, detached DOMPoint object representing the point (x, y).

3.5. DOM interfaces for basic data types

3.5.1. Interface SVGNumber

The SVGNumber interface is used primarily to represent a <number> value that is a part of an SVGNumberList. Individual SVGNumber objects can also be created by script.

An SVGNumber object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below. SVGNumber objects reflected through the animVal IDL attribute are always read only.

An SVGNumber object can be associated with a particular element. The associated element is used to determine which element's content attribute to update if the object reflects an attribute. Unless otherwise described, an SVGNumber object is not associated with any element.

Every SVGNumber object operates in one of two modes. It can:

  1. reflect an element of the base value of a reflected animatable attribute (being exposed through the methods on the baseVal member of an SVGAnimatedNumberList),
  2. be detached, which is the case for SVGNumber objects created with createSVGNumber.

An SVGNumber object maintains an internal number value, which is called its value.

interface SVGNumber {
  attribute float value;
};

The value IDL attribute represents the number. On getting value, the SVGNumber's value is returned.

On setting value, the following steps are run:

  1. If the SVGNumber is read only, then throw a NoModificationAllowedError.
  2. Set the SVGNumber's value to the value being assigned to the value member.
  3. If the SVGNumber reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

3.5.2. Interface SVGLength

The SVGLength interface is used to represent a value that can be a <length>, <percentage> or <number> value.

An SVGLength object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below. SVGLength objects reflected through the animVal IDL attribute are always read only.

An SVGLength object can be associated with a particular element, as well as being designated with a directionality: horizontal, vertical or unspecified. The associated element and the directionality of the length are used to resolve percentage values to user units and is also used to determine which element's content attribute to update if the object reflects an attribute. Unless otherwise described, an SVGLength object is not associated with any element and has unspecified directionality.

Every SVGLength object operates in one of four modes. It can:

  1. reflect the base value of a reflected animatable attribute (being exposed through the baseVal member of an SVGAnimatedLength),
  2. reflect a presentation attribute value (such as by SVGRectElement.width.baseVal),
  3. reflect an element of the base value of a reflected animatable attribute (being exposed through the methods on the baseVal member of an SVGAnimatedLengthList), or
  4. be detached, which is the case for SVGLength objects created with createSVGLength.

An SVGLength object maintains an internal <length> or <percentage> or <number> value, which is called its value.

interface SVGLength {

  // Length Unit Types
  const unsigned short SVG_LENGTHTYPE_UNKNOWN = 0;
  const unsigned short SVG_LENGTHTYPE_NUMBER = 1;
  const unsigned short SVG_LENGTHTYPE_PERCENTAGE = 2;
  const unsigned short SVG_LENGTHTYPE_EMS = 3;
  const unsigned short SVG_LENGTHTYPE_EXS = 4;
  const unsigned short SVG_LENGTHTYPE_PX = 5;
  const unsigned short SVG_LENGTHTYPE_CM = 6;
  const unsigned short SVG_LENGTHTYPE_MM = 7;
  const unsigned short SVG_LENGTHTYPE_IN = 8;
  const unsigned short SVG_LENGTHTYPE_PT = 9;
  const unsigned short SVG_LENGTHTYPE_PC = 10;

  readonly attribute unsigned short unitType;
           attribute float value;
           attribute float valueInSpecifiedUnits;
           attribute DOMString valueAsString;

  void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits);
  void convertToSpecifiedUnits(unsigned short unitType);
};

The numeric length unit type constants defined on SVGLength are used to represent the type of an SVGLength's value. Their meanings are as follows:

ConstantMeaning
SVG_LENGTHTYPE_NUMBERA unitless <number> interpreted as a value in px.
SVG_LENGTHTYPE_PERCENTAGEA <percentage>.
SVG_LENGTHTYPE_EMSA <length> with an em unit.
SVG_LENGTHTYPE_EXSA <length> with an ex unit.
SVG_LENGTHTYPE_PXA <length> with a px unit.
SVG_LENGTHTYPE_CMA <length> with a cm unit.
SVG_LENGTHTYPE_MMA <length> with a mm unit.
SVG_LENGTHTYPE_INA <length> with an in unit.
SVG_LENGTHTYPE_PTA <length> with a pt unit.
SVG_LENGTHTYPE_PCA <length> with a pc unit.
SVG_LENGTHTYPE_UNKNOWNSome other type of value.

The use of numeric length unit type constants is an anti-pattern and new constant values will not be introduced for any other units or length types supported by SVGLength. If other types of lengths are supported and used, the SVGLength uses the SVG_LENGTHTYPE_UNKNOWN unit type. See below for details on how the other properties of an SVGLength operate with these types of lengths.

The unitType IDL attribute represents the type of value that the SVGLength's value is. On getting unitType, the following steps are run:

  1. If the SVGLength's value is a unitless <number>, a <percentage>, or a <length> with an em, ex, px, cm, mm, in, pt or pc unit, then return the corresponding constant value from the length unit type table above.
  2. Otherwise, return SVG_LENGTHTYPE_UNKNOWN.

    For example, for a <length> with a ch unit or one that has a non-scalar value such as calc(), SVG_LENGTHTYPE_UNKNOWN would be returned.

The value IDL attribute represents the SVGLength's value in user units. On getting value, the following steps are run:

  1. Let value be the SVGLength's value.
  2. If value is a <number>, return that number.
  3. Let viewport size be a basis to resolve percentages against, based on the SVGLength's associated element and directionality:
    has no associated element
    size is 100
    has an associated element and horizontal directionality
    size is the width of the associated element's SVG viewport
    has an associated element and vertical directionality
    size is the height of the associated element's SVG viewport
    has an associated element and unspecified directionality
    size is the length of the associated element's SVG viewport diagonal (see Units)
  4. Let font size be a basis to resolve font size values against, based on the SVGLength's associated element:
    has no associated element
    font size is the absolute length of the initial value of the font-size property
    has an associated element
    size is the computed value of the associated element's font-size property
  5. Return the result of converting value to an absolute length, using viewport size and font size as percentage and font size bases. If the conversion is not possible due to the lack of an associated element, return 0.

On setting value, the following steps are run:

  1. If the SVGLength object is read only, then throw a NoModificationAllowedError.
  2. Let value be the value being assigned to value.
  3. Set the SVGLength's value to a <number> whose value is value.
  4. If the SVGLength reflects the base value of a reflected attribute, reflects a presentation attribute, or reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

The valueInSpecifiedUnits IDL attribute represents the numeric factor of the SVGLength's value. On getting valueInSpecifiedUnits, the following steps are run:

  1. Let value be the SVGLength's value.
  2. If value is a <number>, return that number.
  3. Otherwise, if value is a <percentage> or any scalar <length> value, return the numeric factor before its unit.
  4. Otherwise, return 0.

    Thus valueInSpecifiedUnits would return 12 for both '12%' and 12em, but 0 would be returned for non-scalar values like calc(12px + 5%).

On setting valueInSpecifiedUnits, the following steps are run:

  1. If the SVGLength object is read only, then throw a NoModificationAllowedError.
  2. Let value be the value being assigned to valueInSpecifiedUnits.
  3. If the SVGLength's value is a <number>, then update its value to value.
  4. Otherwise, if the SVGLength's value is a <percentage> or a scalar-valued <length>, then update its numeric factor to value.
  5. Otherwise, the SVGLength's value is of some other type. Set it to a <number> whose value is value.
  6. If the SVGLength reflects the base value of a reflected attribute or reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

The valueAsString IDL attribute represents the SVGLength's value as a string. On getting valueAsString, the following steps are run:

  1. Let value be the SVGLength's value.
  2. Let string be an empty string.
  3. If value is a <number>, <percentage> or scalar <length> value, then:
    1. Let factor be value's numeric factor, if it is a <percentage> or <length>, or value itself it is a <number>.
    2. Append to string an implementation specific string that, if parsed as a <number> using CSS syntax, would return the number value closest to factor, given the implementation's supported real number precision.
    3. If value is a <percentage> then append to string a single U+0025 PERCENT SIGN character.
    4. Otherwise, if value is a <length>, then append to string the canonical spelling of value's unit.
    5. Return string.
  4. Otherwise, return an implementation specific string that, if parsed as a <length>, would return the closest length value to value, given the implementation's supported real number precision.

On setting valueAsString, the following steps are run:

  1. If the SVGLength object is read only, then throw a NoModificationAllowedError.
  2. Let value be the value being assigned to valueAsString.
  3. Parse value using the CSS syntax [ <number> | <length> | <percentage> ].
  4. If parsing failed, then throw a SyntaxError.
  5. Otherwise, parsing succeeded. Set SVGLength's value to the parsed value.
  6. If the SVGLength reflects the base value of a reflected attribute or reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

The newValueSpecifiedUnits method is used to set the SVGLength's value in a typed manner. When newValueSpecifiedUnits(unitType, valueInSpecifiedUnits) is called, the following steps are run:

  1. If the SVGLength object is read only, then throw a NoModificationAllowedError.
  2. If unitType is SVG_LENGTHTYPE_UNKNOWN or is a value that does not appear in the length unit type table above, then throw a NotSupportedError.
  3. Set SVGLength's value depending on the value of unitType:
    SVG_LENGTHTYPE_NUMBER
    a <number> whose value is valueInSpecifiedUnits
    SVG_LENGTHTYPE_PERCENTAGE
    a <percentage> whose numeric factor is valueInSpecifiedUnits
    anything else
    a <length> whose numeric factor is valueInSpecifiedUnits and whose unit is as indicated by the length unit type table above
  4. If the SVGLength reflects the base value of a reflected attribute or reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

The convertToSpecifiedUnits method is used to convert the SVGLength's value to a specific type. When convertToSpecifiedUnits(unitType) is called, the following steps are run:

  1. If the SVGLength object is read only, then throw a NoModificationAllowedError.
  2. If unitType is SVG_LENGTHTYPE_UNKNOWN or is a value that does not appear in the length unit type table above, then throw a NotSupportedError.
  3. Let absolute be the value that would be returned from the value member.
  4. If unitType is SVG_LENGTHTYPE_NUMBER, then:
    1. Set the SVGLength's value to a <number> whose value is absolute.
  5. Otherwise, if unitType is SVG_LENGTHTYPE_PERCENTAGE, then:
    1. Let viewport size be a basis to resolve percentages against, based on the SVGLength's associated element and directionality:
      has no associated element
      size is 100
      has an associated element and horizontal directionality
      size is the width of the associated element's SVG viewport
      has an associated element and vertical directionality
      size is the height of the associated element's SVG viewport
      has an associated element and unspecified directionality
      size is the length of the associated element's SVG viewport diagonal (see Units)
    2. Set the SVGLength's value to the result of converting absolute to a <percentage>, using viewport size as the percentage basis.
  6. Otherwise, if unitType is SVG_LENGTHTYPE_EMS or SVG_LENGTHTYPE_EXS, then:
    1. Let font size be a basis to resolve font size values against, based on the SVGLength's associated element:
      has no associated element
      font size is the absolute length of the initial value of the font-size property
      has an associated element
      size is the computed value of the associated element's font-size property
    2. Set the SVGLength's value to the result of converting absolute to a <length> with an em or ex unit (depending on unitType), using font size as the font-size basis.
  7. Otherwise:
    1. Set the SVGLength's value to the result of converting absolute to a <length> with the unit found by looking up unitType in the length unit type table above.
  8. If the SVGLength reflects the base value of a reflected attribute or reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

3.5.3. Interface SVGAngle

The SVGAngle interface is used to represent a value that can be an <angle> or <number> value.

An SVGAngle object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below. An SVGAngle reflected through the animVal attribute is always read only.

An SVGAngle object can be associated with a particular element. The associated element is used to determine which element's content attribute to update if the object reflects an attribute. Unless otherwise described, an SVGAngle object is not associated with any element.

Every SVGAngle object operates in one of two modes. It can:

  1. reflect the base value of a reflected animatable attribute (being exposed through the baseVal member of an SVGAnimatedAngle),
  2. be detached, which is the case for SVGAngle objects created with createSVGAngle.

An SVGAngle object maintains an internal <angle> or <number> value, which is called its value.

interface SVGAngle {

  // Angle Unit Types
  const unsigned short SVG_ANGLETYPE_UNKNOWN = 0;
  const unsigned short SVG_ANGLETYPE_UNSPECIFIED = 1;
  const unsigned short SVG_ANGLETYPE_DEG = 2;
  const unsigned short SVG_ANGLETYPE_RAD = 3;
  const unsigned short SVG_ANGLETYPE_GRAD = 4;

  readonly attribute unsigned short unitType;
           attribute float value;
           attribute float valueInSpecifiedUnits;
           attribute DOMString valueAsString;

  void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits);
  void convertToSpecifiedUnits(unsigned short unitType);
};

The numeric angle unit type constants defined on SVGAngle are used to represent the type of an SVGAngle's value. Their meanings are as follows:

ConstantMeaning
SVG_ANGLETYPE_UNSPECIFIEDA unitless <number> interpreted as a value in degrees.
SVG_ANGLETYPE_DEGAn <angle> with a deg unit.
SVG_ANGLETYPE_RADAn <angle> with a rad unit.
SVG_ANGLETYPE_GRADAn <angle> with a grad unit.
SVG_ANGLETYPE_UNKNOWNSome other type of value.

The use of numeric angle unit type constants is an anti-pattern and new constant values will not be introduced for any other units or angle types supported by SVGAngle. If other types of angles are supported and used, the SVGAngle uses the SVG_ANGLETYPE_UNKNOWN unit type. See below for details on how the other properties of an SVGAngle operate with these types of angles.

The unitType IDL attribute represents the type of value that the SVGAngle's value is. On getting unitType, the following steps are run:

  1. If the SVGAngle's value is a unitless <number> or a <length> with a deg, rad or grad unit, then return the corresponding constant value from the angle unit type table above.
  2. Otherwise, return SVG_ANGLETYPE_UNKNOWN.

    For example, for an <angle> with a turn unit, SVG_ANGLETYPE_UNKNOWN would be returned.

The value IDL attribute represents the SVGAngle's value in user units. On getting value, the following steps are run:

  1. Let value be the SVGAngle's value.
  2. If value is a <number>, return that number.
  3. Return the result of converting value to an angle in degrees.

On setting value, the following steps are run:

  1. If the SVGAngle object is read only, then throw a NoModificationAllowedError.
  2. Let value be the value being assigned to value.
  3. Set the SVGAngle's value to a <number> whose value is value.
  4. If the SVGAngle reflects the base value of a reflected attribute, then reserialize the reflected attribute.

The valueInSpecifiedUnits IDL attribute represents the numeric factor of the SVGAngle's value. On getting valueInSpecifiedUnits, the following steps are run:

  1. Let value be the SVGAngle's value.
  2. If value is a <number>, return that number.
  3. Otherwise, value is an <angle> value. Return the numeric factor before its unit.

On setting valueInSpecifiedUnits, the following steps are run:

  1. If the SVGAngle object is read only, then throw a NoModificationAllowedError.
  2. Let value be the value being assigned to valueInSpecifiedUnits.
  3. If the SVGAngle's value is a <number>, then update its value to value.
  4. Otherwise, if the SVGAngle's value is an <angle>, then update its numeric factor to value.
  5. If the SVGAngle reflects the base value of a reflected attribute or reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

The valueAsString IDL attribute represents the SVGAngle's value as a string. On getting valueAsString, the following steps are run:

  1. Let value be the SVGAngle's value.
  2. Let string be an empty string.
  3. Let factor be value's numeric factor, if it is an <angle>, or value itself it is a <number>.
  4. Append to string an implementation specific string that, if parsed as a <number> using CSS syntax, would return the number value closest to factor, given the implementation's supported real number precision.
  5. If value is an <angle>, then append to string the canonical spelling of value's unit.
  6. Return string.

On setting valueAsString, the following steps are run:

  1. If the SVGAngle object is read only, then throw a NoModificationAllowedError.
  2. Let value be the value being assigned to valueAsString.
  3. Parse value using the CSS syntax [ <number> | <angle> ].
  4. If parsing failed, then throw a SyntaxError.
  5. Otherwise, parsing succeeded. Set SVGAngle's value to the parsed value.
  6. If the SVGAngle reflects the base value of a reflected attribute or reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

The newValueSpecifiedUnits method is used to set the SVGAngle's value in a typed manner. When newValueSpecifiedUnits(unitType, valueInSpecifiedUnits) is called, the following steps are run:

  1. If the SVGAngle object is read only, then throw a NoModificationAllowedError.
  2. If unitType is SVG_ANGLETYPE_UNKNOWN or is a value that does not appear in the angle unit type table above, then throw a NotSupportedError.
  3. Set SVGAngle's value depending on the value of unitType:
    SVG_ANGLETYPE_UNSPECIFIED
    a <number> whose value is valueInSpecifiedUnits
    anything else
    an <angle> whose numeric factor is valueInSpecifiedUnits and whose unit is as indicated by the angle unit type table above
  4. If the SVGAngle reflects the base value of a reflected attribute or reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

The convertToSpecifiedUnits method is used to convert the SVGAngle's value to a specific type. When convertToSpecifiedUnits(unitType) is called, the following steps are run:

  1. If the SVGAngle object is read only, then throw a NoModificationAllowedError.
  2. If unitType is SVG_ANGLETYPE_UNKNOWN or is a value that does not appear in the angle unit type table above, then throw a NotSupportedError.
  3. Let degrees be the value that would be returned from the value member.
  4. If unitType is SVG_ANGLETYPE_UNSPECIFIED, then:
    1. Set the SVGAngle's value to a <number> whose value is degrees.
  5. Otherwise:
    1. Set the SVGAngle's value to the result of converting degrees to an <angle> with the unit found by looking up unitType in the angle unit type table above.
  6. If the SVGAngle reflects the base value of a reflected attribute or reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute.

3.5.4. List interfaces

SVG 2 Requirement: Make the SVGList* interfaces a bit more like other lists/arrays.
Resolution: Add array style indexing and .length and .item to svg list types.
Purpose: To align with other array types (e.g. NodeList). Already implemented in Opera and Firefox.
Owner: Erik (ACTION-2975)
Status: Done

Some SVG attributes contain lists of values, and to represent these values there are a number of SVG DOM list interfaces, one for each required element type – SVGNumberList, SVGLengthList, SVGPointList, SVGTransformList and SVGStringList. The first four are used to represent the base and animated components of SVGAnimatedNumberList, SVGAnimatedLengthList, SVGAnimatedPoints and SVGTransformList objects, while the fifth, SVGStringList, is used to reflect a few unanimated attributes that take a list of strings.

Most list interfaces take the following form:

interface SVGNameList {

  readonly attribute unsigned long length;
  readonly attribute unsigned long numberOfItems;

  void clear();
  Type initialize(Type newItem);
  getter Type getItem(unsigned long index);
  Type insertItemBefore(Type newItem, unsigned long index);
  Type replaceItem(Type newItem, unsigned long index);
  Type removeItem(unsigned long index);
  Type appendItem(Type newItem);
  setter void (unsigned long index, Type newItem);
};

where Name is a descriptive name for the list element's ("Number", "Length", "Point", "Transform" or "String") and Type is the IDL type of the list's elements (SVGNumber, SVGLength, DOMPoint, SVGTransform or DOMString).

The SVGTransformList interface takes the above form but has two additional methods on it.

All list interface objects apart from SVGTransformList reflect the base value of a reflected content attribute. SVGTransformList objects reflect a presentation attribute (‘transform’, gradientTransform or patternTransform). All list interface objects are associated with a particular element. Unlike SVGLength and similar objects, there are no "detached" list interface objects.

A list interface object maintains an internal list of elements, which is referred to in the text below simply as "the list". The IDL attributes and methods are used to inspect and manipulate elements of the list. The list can also be changed in response to changes to the reflected content attribute and to animation of the content attribute (or, for SVGTransformList objects, in response to changes to the computed value of the transform property).

A list interface object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below. list interface objects reflected through the animVal IDL attribute are always read only.

A list interface object is synchronized by running the following steps:

  1. Let value be the base value of the reflected content attribute (using the attribute's initial value if it is not present or invalid).
  2. Let length be the number of items in the list.
  3. Let new length be the number of values in value. If value is the keyword none (as supported by the transform property), new length is 0.
  4. If the list element type is SVGNumber, SVGLength, DOMPoint or SVGTransform, then:
    1. If length > new length, then:
      1. Detach each object in the list at an index greater than or equal to new length.
      2. Truncate the list to length new length.
      3. Set length to new length.
    2. While length < new length:
      1. Let item be a newly created object of the list element type.
      2. Attach item to this list interface object.
      3. Append item to the list.
      4. Set length to length + 1.
    3. Let index be 0.
    4. While index < length:
      1. Let item be the object in the list at index index.
      2. Let v be the value in value at index index.
      3. Set item's value to v.
      4. If item is an SVGTransform object, then set the components of its matrix object to match the new transform function value.
      5. Set index to index + 1.
  5. Otherwise, the list element type is DOMString:
    1. Replace the list with a new list consisting of the values in value.

Whenever a list element object is to be detached, the following steps are run, depending on the list element type:

SVGNumber
Set the SVGNumber to no longer be associated with any element. If the SVGNumber is read only, set it to be no longer read only.
SVGLength
Set the SVGLength to no longer be associated with any element. If the SVGLength is read only, set it to be no longer read only. Set the SVGLength to have unspecified directionality.
DOMPoint
Set the DOMPoint to no longer be associated with any element. If the DOMPoint is read only, set it to be no longer read only.
SVGTransform
Set the SVGTransform to no longer be associated with any element. If the SVGTransform is read only, set it to be no longer read only.
DOMString
Nothing is done.

Whenever a list element object is to be attached, the following steps are run, depending on the list element type:

SVGNumber
Associate the SVGNumber with the element that the list interface object is associated with. Additionally, depending on which IDL attribute the list interface object is reflected through:
baseVal
Set the SVGNumber to reflect an element of the base value.
animVal
Set the SVGNumber to reflect an element of the base value.
SVGLength
Associate the SVGLength with the element that the list interface object is associated with and set its directionality to that specified by the attribute being reflected. Additionally, depending on which IDL attribute the list interface object is reflected through:
baseVal
Set the SVGLength to reflect an element of the base value.
animVal
Set the SVGLength to reflect an element of the base value. Set the SVGLength to be read only.
DOMPoint
Associate the DOMPoint with the element that the list interface object is associated with. Additionally, depending on which IDL attribute the list interface object is reflected through:
baseVal
Set the DOMPoint to reflect an element of the base value.
animVal
Set the DOMPoint to reflect an element of the base value.
SVGTransform
Associate the SVGTransform with the element that the list interface object is associated with. Set the SVGTransform to reflect an element of a presentation attribute value.
DOMString
Nothing is done.

The supported property indices of a list interface object is the set of all non-negative integers less than the length of the list.

The length and numberOfItems IDL attributes represents the length of the list, and on getting simply return the length of the list.

The clear method is used to remove all items in the list. When clear() is called, the following steps are run:

  1. If the list is read only, then throw a NoModificationAllowedError.
  2. Detach and then remove all elements in the list.
  3. If the list reflects an attribute, or represents the base value of an object that reflects an attribute, then reserialize the reflected attribute.

The initialize method is used to clear the list and add a single, specified value to it. When initialize(newItem) is called, the following steps are run:

  1. If the list is read only, then throw a NoModificationAllowedError.
  2. Detach and then remove all elements in the list.
  3. If newItem is an object type, and newItem is not a detached object, then set newItem to be a newly created object of the same type as newItem and which has the same (number or length) value.
  4. Attach newItem to the list interface object.
  5. Append newItem to this list.
  6. If the list reflects an attribute, or represents the base value of an object that reflects an attribute, then reserialize the reflected attribute.
  7. Return newItem.

The getItem method is used to get an item from the list at the specified position. When getItem(index) is called, the following steps are run:

  1. If index is greater than or equal to the length of the list, then throw an IndexSizeError.
  2. Return the element in the list at position index.

    Note that if the list's element type is an object type, such as SVGLength, then a reference to that object and not a copy of it is returned.

The insertItemBefore method is used to insert an element into the list at a specific position. When insertItemBefore(newItem, index) is called, the following steps are run:

  1. If the list is read only, then throw a NoModificationAllowedError.
  2. If newItem is an object type, and newItem is not a detached object, then set newItem to be a newly created object of the same type as newItem and which has the same (number or length) value.
  3. If index is greater than the length of the list, then set index to be the list length.
  4. Insert newItem into the list at index index.
  5. Attach newItem to the list interface object.
  6. If the list reflects an attribute, or represents the base value of an object that reflects an attribute, then reserialize the reflected attribute.
  7. Return newItem.

The replaceItem method is used to replace an existing item in the list with a new item. When replaceItem(newItem, index) is called, the following steps are run:

  1. If the list is read only, then throw a NoModificationAllowedError.
  2. If index is greater than or equal to the length of the list, then throw an IndexSizeError.
  3. If newItem is an object type, and newItem is not a detached object, then set newItem to be a newly created object of the same type as newItem and which has the same (number or length) value.
  4. Detach the element in the list at index index.
  5. Replace the element in the list at index index with newItem.
  6. Attach newItem to the list interface object.
  7. If the list reflects an attribute, or represents the base value of an object that reflects an attribute, then reserialize the reflected attribute.
  8. Return newItem.

The removeItem method is used to remove an item from the list. When removeItem(index) is called, the following steps are run:

  1. If the list is read only, then throw a NoModificationAllowedError.
  2. If index is greater than or equal to the length of the list, then throw an IndexSizeError with code.
  3. Let item be the list element at index index.
  4. Detach item.
  5. Remove the list element at index index.
  6. Return item.

The appendItem method is used to append an item to the end of the list. When appendItem(newItem) is called, the following steps are run:

  1. If the list is read only, then throw a NoModificationAllowedError.
  2. If newItem is an object type, and newItem is not a detached object, then set newItem to be a newly created object of the same type as newItem and which has the same (number or length) value.
  3. Let index be the length of the list.
  4. Append newItem to the end of the list.
  5. Attach newItem to the list interface object.
  6. If the list reflects an attribute, or represents the base value of an object that reflects an attribute, then reserialize the reflected attribute.
  7. Return newItem.

The behavior of the indexed property setter is the same as that for the replaceItem method.

3.5.5. Interface SVGNumberList

The SVGNumberList interface is a list interface whose elements are SVGNumber objects. An SVGNumberList object represents a list of numbers.

interface SVGNumberList {

  readonly attribute unsigned long length;
  readonly attribute unsigned long numberOfItems;

  void clear();
  SVGNumber initialize(SVGNumber newItem);
  getter SVGNumber getItem(unsigned long index);
  SVGNumber insertItemBefore(SVGNumber newItem, unsigned long index);
  SVGNumber replaceItem(SVGNumber newItem, unsigned long index);
  SVGNumber removeItem(unsigned long index);
  SVGNumber appendItem(SVGNumber newItem);
  setter void (unsigned long index, SVGNumber newItem);
};

The behavior of all of the interface members of SVGNumberList are defined in the List interfaces section above.

3.5.6. Interface SVGLengthList

The SVGLengthList interface is a list interface whose elements are SVGLength objects. An SVGLengthList object represents a list of lengths.

interface SVGLengthList {

  readonly attribute unsigned long length;
  readonly attribute unsigned long numberOfItems;

  void clear();
  SVGLength initialize(SVGLength newItem);
  getter SVGLength getItem(unsigned long index);
  SVGLength insertItemBefore(SVGLength newItem, unsigned long index);
  SVGLength replaceItem(SVGLength newItem, unsigned long index);
  SVGLength removeItem(unsigned long index);
  SVGLength appendItem(SVGLength newItem);
  setter void (unsigned long index, SVGLength newItem);
};

The behavior of all of the interface members of SVGLengthList are defined in the List interfaces section above.

3.6. DOM interfaces for reflecting SVG attributes

In SVG 1.1 SE, the animVal attribute of the SVG DOM interfaces represented the current animated value of the reflected attribute. In this version of SVG, animVal no longer representes the current animated value and is instead an alias of baseVal.

Some IDL attributes reflect the value of a content attribute or a property. The way this reflection is done depends on the type of the IDL attribute:

Whenever a reflected content attribute's base value changes, then the reflecting object must be synchronized, immediately after the value changed, by running the following steps:

  1. If the reflecting object is a list interface object, then run the steps for synchronizing a list interface object.
  2. Otherwise, update the object's value to be the base value of the reflected content attribute (using the attribute's initial value if it is not present or invalid).

    This will, for example, update the value of an SVGLength object.

When a reflected content attribute is to be reserialized, optionally using a specific value, the following steps must be performed:

  1. Let value be the specific value given, or the value of the content attribute's reflecting IDL attribute if a specific value was not provided.
  2. Depending on value's type:
    SVGAnimatedBoolean
    SVGAnimatedNumber
    SVGAnimatedLength
    SVGAnimatedAngle
    SVGAnimatedRect
    SVGAnimatedString
    SVGAnimatedNumberList
    SVGAnimatedLengthList
    SVGAnimatedTransformList
    Reserialize the content attribute using value's baseVal member.
    SVGAnimatedEnumeration
    1. Let number be the value of value's baseVal member.
    2. Let keyword be the content attribute's keyword value corresponding to number, or the empty string if number is 0.

      This means that if the enumeration value is set to the "unknown" value, the content attribute will be set to the empty string.

    3. Set the content attribute to keyword.
    boolean
    Set the content attribute to "true" if value is true, and "false" otherwise.
    float
    double
    Set the content attribute to an implementation specific string that, if parsed as a <number> using CSS syntax, would return the number value closest to value, given the implementation's supported real number precision.
    SVGLength
    Set the content attribute to the value that would be returned from getting value's valueAsString member.
    SVGAngle
    Set the content attribute to the value that would be returned from getting value's valueAsString member.
    DOMRect
    1. Let components be a list of four values, being the values of the x, y, width and height members of value.
    2. Let serialized components be a list of four strings, where each is an implementation specific string that, if parsed as a <number> using CSS syntax, would return the number value closest to the corresponding value in components, given the implementation's supported real number precision.
    3. Set the content attribute to a string consisting of the strings in serialized components joined and separated by single U+0020 SPACE characters.
    DOMString
    Set the content attribute to value.
    SVGNumberList
    SVGLengthList
    SVGPointList
    SVGTransformList
    SVGStringList
    1. Let elements be the list of values in value.

      The values will be SVGNumber, SVGLength, DOMPoint or SVGTransform objects, or DOMString values, depending on value's type.

    2. Let serialized elements be a list of strings, where each string is formed based on the corresponding value in elements and its type:
      an SVGNumber object
      The string is an implementation specific string that, if parsed as a <number> using CSS syntax, would return the number value closest to the SVGNumber object's value member, given the implementation's supported real number precision.
      an SVGLength object
      The string is the value that would be returned from getting the value's valueAsString member.
      a DOMPoint object
      The string value is computed as follows:
      1. Let string be an empty string.
      2. Let x and y be the values of the DOMPoint object's x and y coordinates, respectively.
      3. Append to string an implementation specific string that, if parsed as <number> using CSS syntax, would return the number value closest to x, given the implementation's supported real number precision.
      4. Append a single U+002C COMMA character to string.
      5. Append to string an implementation specific string that, if parsed as <number> using CSS syntax, would return the number value closest to y, given the implementation's supported real number precision.
      6. The string is string.
      a SVGTransform object
      The string is the serialization of the SVGTransform object's matrix object.
      a DOMString
      The string is the DOMString's value itself.
    3. Set the content attribute to a string consisting of the strings in serialized elements joined and separated by single U+0020 SPACE characters.

3.6.1. Interface SVGAnimatedBoolean

An SVGAnimatedBoolean object is used to reflect an animatable attribute that takes a boolean value.

interface SVGAnimatedBoolean {
           attribute boolean baseVal;
  readonly attribute boolean animVal;
};

The baseVal and animVal IDL attributes both represent the current non-animated value of the reflected attribute. On getting baseVal or animVal, the following steps are run:

  1. Let value be the value of the reflected attribute, or the empty string if it is not present.
  2. If value is not "true" or "false", then set value to the reflected attribute's initial value.
  3. Return true if value is "true", and false otherwise.

On setting baseVal, the reflected attribute is set to "true" if the value is true, and "false" otherwise.

3.6.2. Interface SVGAnimatedEnumeration

An SVGAnimatedEnumeration object is used to reflect an animatable attribute that takes a keyword value (such as the method attribute on textPath) or to reflect the type of value that an animatable attribute has (done only by the orientType IDL attribute for the marker element's orient attribute).

interface SVGAnimatedEnumeration {
           attribute unsigned short baseVal;
  readonly attribute unsigned short animVal;
};

For SVGAnimatedEnumeration objects that reflect an animatable attribute that takes only a keyword value, the baseVal and animVal IDL attributes represents the current non-animated value of the reflected attribute. For orientType, they represent the type of the current non-animated value of the reflected orient attribute. On getting baseVal or animVal, the following steps are run:

  1. Let value be the value of the reflected attribute (using the attribute's initial value if it is not present or invalid).
  2. Return the numeric type value for value, according to the reflecting IDL attribute's definition.

On setting baseVal, the following steps are run:

  1. Let value be the value being assigned to baseVal.
  2. If value is 0 or is not the numeric type value for any value of the reflected attribute, then set the reflected attribute to the empty string.
  3. Otherwise, if the reflecting IDL attribute is orientType and value is SVG_MARKER_ORIENT_ANGLE, then set the reflected attribute to the string "0".
  4. Otherwise, value is the numeric type value for a specific, single keyword value for the reflected attribute. Set the reflected attribute to that value.

3.6.3. Interface SVGAnimatedInteger

An SVGAnimatedInteger object is used to reflect an animatable attribute that takes an integer value (such as numOctaves on feTurbulence). It is also used to reflect one part of an animatable attribute that takes an integer followed by an optional second integer (such as order on feConvolveMatrix).

This SVGAnimatedInteger interface is not used in this specification, however the Filter Effects specification has a number of uses of it.

interface SVGAnimatedInteger {
           attribute long baseVal;
  readonly attribute long animVal;
};

For SVGAnimatedInteger objects that reflect an animatable attribute that takes a single integer value, the baseVal and animVal IDL attributes represent the current non-animated value of the reflected attribute. For those that reflect one integer of an attribute that takes an integer followed by an optional second integer, they represent the current non-animated value of one of the two integers. On getting baseVal or animVal, the following steps are run:

  1. Let value be the value of the reflected attribute (using the attribute's initial value if it is not present or invalid).
  2. If the reflected attribute is defined to take an integer followed by an optional second integer, then:
    1. If this SVGAnimatedInteger object reflects the first integer, then return the first value in value.
    2. Otherwise, this SVGAnimatedInteger object reflects the second integer. Return the second value in value if it has been explicitly specified, and if not, return the implicit value as described in the definition of the attribute.

      For example, the definition of order says that the implicit second integer is the same as the explicit first integer.

  3. Otherwise, the reflected attribute is defined to take a single integer value. Return value.

On setting baseVal, the following steps are run:

  1. Let value be the value being assigned to baseVal.
  2. Let new be a list of integers.
  3. If the reflected attribute is defined to take an integer followed by an optional second integer, then:
    1. Let current be the value of the reflected attribute (using the attribute's initial value if it is not present or invalid).
    2. Let first be the first integer in current.
    3. Let second be the second integer in current if it has been explicitly specified, and if not, the implicit value as described in the definition of the attribute.
    4. If this SVGAnimatedInteger object reflects the first integer, then set first to value. Otherwise, set second to value.
    5. Append first to new.
    6. Append second to new.
  4. Otherwise, the reflected attribute is defined to take a single integer value. Append value to new.
  5. Set the content attribute to a string consisting of each integer in new serialized to an implementation specific string that, if parsed as an <number> using CSS syntax, would return that integer, joined and separated by a single U+0020 SPACE character.

3.6.4. Interface SVGAnimatedNumber

An SVGAnimatedNumber object is used to reflect an animatable attribute that takes a number value (such as pathLength on path). It is also used to reflect one part of an animatable attribute that takes an number followed by an optional second number (such as kernelUnitLength on feDiffuseLighting).

interface SVGAnimatedNumber {
           attribute float baseVal;
  readonly attribute float animVal;
};

For SVGAnimatedNumber objects that reflect an animatable attribute that takes a single number value, the baseVal and animVal IDL attributes represent the current non-animated value of the reflected attribute. For those that reflect one number of an attribute that takes a number followed by an optional second number, they represent the current non-animated value of one of the two numbers. On getting baseVal or animVal, the following steps are run:

  1. Let value be the value of the reflected attribute (using the attribute's initial value if it is not present or invalid).
  2. If the reflected attribute is defined to take an number followed by an optional second number, then:
    1. If this SVGAnimatedNumber object reflects the first number, then return the first value in value.
    2. Otherwise, this SVGAnimatedNumber object reflects the second number. Return the second value in value if it has been explicitly specified, and if not, return the implicit value as described in the definition of the attribute.

      For example, the definition of kernelUnitLength says that the implicit second number is the same as the explicit first number.

  3. Otherwise, the reflected attribute is defined to take a single number value. Return value.

On setting baseVal, the following steps are run:

  1. Let value be the value being assigned to baseVal.
  2. Let new be a list of numbers.
  3. If the reflected attribute is defined to take an number followed by an optional second number, then:
    1. Let current be the value of the reflected attribute (using the attribute's initial value if it is not present or invalid).
    2. Let first be the first number in current.
    3. Let second be the second number in current if it has been explicitly specified, and if not, the implicit value as described in the definition of the attribute.
    4. If this SVGAnimatedNumber object reflects the first number, then set first to value. Otherwise, set second to value.
    5. Append first to new.
    6. Append second to new.
  4. Otherwise, the reflected attribute is defined to take a single number value. Append value to new.
  5. Set the content attribute to a string consisting of each number in new serialized to an implementation specific string that, if parsed as an <number> using CSS syntax, would return the value closest to the number (given the implementation's supported Precisionreal number precision), joined and separated by a single U+0020 SPACE character.

3.6.5. Interface SVGAnimatedLength

An SVGAnimatedLength object is used to reflect either (a) an animatable attribute that takes a <length>, <percentage> or <number> value, or (b) a CSS property that takes one of these values and its corresponding presentation attribute.

interface SVGAnimatedLength {
  [SameObject] readonly attribute SVGLength baseVal;
  [SameObject] readonly attribute SVGLength animVal;
};

The baseVal and animVal IDL attributes represent the current value of the reflected content attribute. On getting baseVal or animVal, an SVGLength object is returned that:

3.6.6. Interface SVGAnimatedAngle

An SVGAnimatedAngle object is used to reflect the <angle> value of the animated orient attribute on marker, through the orientAngle IDL attribute.

interface SVGAnimatedAngle {
  [SameObject] readonly attribute SVGAngle baseVal;
  [SameObject] readonly attribute SVGAngle animVal;
};

The baseVal and animVal IDL attributes represent the current non-animated <angle> value of the reflected orient attribute. On getting baseVal or animVal, an SVGAngle object is returned that:

3.6.7. Interface SVGAnimatedString

An SVGAnimatedString object is used to reflect an animatable attribute that takes a string value. It can optionally be defined to additionally reflect a second, deprecated attribute.

interface SVGAnimatedString {
           attribute DOMString baseVal;
  readonly attribute DOMString animVal;
};

The baseVal and animVal IDL attributes represent the current non-animated value of the reflected attribute. On getting baseVal or animVal, the following steps are run:

  1. If the reflected attribute is not present, then:
    1. If the SVGAnimatedString object is defined to additionally reflect a second, deprecated attribute, and that attribute is present, then return its value.
    2. Otherwise, if the reflected attribute has an initial value, then return it.
    3. Otherwise, return the empty string.
  2. Otherwise, the reflected attribute is present. Return its value.

For the href member on the SVGURIReference interface, this will result in the deprecated xlink:href attribute being returned if it is present and the ‘href’ attribute is not, and in the ‘href’ attribute being returned in all other cases.

On setting baseVal, the following steps are run:

  1. If the reflected attribute is not present, the SVGAnimatedString object is defined to additionally reflect a second, deprecated attribute, and that deprecated attribute is present, then set that deprecated attribute to the specified value.
  2. Otherwise, set the reflected attribute to the specified value.

For the href member on the SVGURIReference interface, this will result in the deprecated xlink:href attribute being set if it is present and the ‘href’ attribute is not, and in the ‘href’ attribute being set in all other cases.

3.6.8. Interface SVGAnimatedRect

An SVGAnimatedRect object is used to reflect an animatable attribute that takes a rectangle value as specified by an x, y, width and height.

In this specification the only attribute to be reflected as an SVGAnimatedRect is viewBox.

interface SVGAnimatedRect {
  [SameObject] readonly attribute DOMRect baseVal;
  [SameObject] readonly attribute DOMRectReadOnly animVal;
};

The baseVal and animVal IDL attributes represent the current non-animated rectangle value of the reflected attribute. On getting baseVal or animVal, a DOMRect object is returned.

Upon creation of the baseVal or animVal DOMRect objects, and afterwards whenever the reflected content attribute is added, removed, or changed, the following steps are run:

  1. Let value be the value of the reflected attribute (using the attribute's initial value if it is not present or invalid).
  2. Let x, y, width and height be those corresponding components of value.
  3. Set the DOMRect object's x coordinate, y coordinate, width and height to x, y, width and height, respectively.

Whenever the x coordinate, y coordinate, width or height property of the baseVal or animVal DOMRect object changes, except as part of the previous algorithm that reflects the value of the content attribute into the DOMRect, the reflected content attribute must be reserialized.

3.6.9. Interface SVGAnimatedNumberList

An SVGAnimatedNumberList object is used to reflect an animatable attribute that takes a list of <number> values.

interface SVGAnimatedNumberList {
  [SameObject] readonly attribute SVGNumberList baseVal;
  [SameObject] readonly attribute SVGNumberList animVal;
};

The baseVal and animVal IDL attributes represent the current non-animated value of the reflected attribute. On getting baseVal or animVal, an SVGNumberList object is returned that reflects the base value of the reflected attribute.

3.6.10. Interface SVGAnimatedLengthList

An SVGAnimatedLengthList object is used to reflect an animatable attribute that takes a list of <length>, <percentage> or <number> values.

interface SVGAnimatedLengthList {
  [SameObject] readonly attribute SVGLengthList baseVal;
  [SameObject] readonly attribute SVGLengthList animVal;
};

The baseVal or animVal IDL attributes represent the current non-animated value of the reflected attribute. On getting baseVal or animVal, an SVGLengthList object is returned that reflects the base value of the reflected attribute.

3.6.11. Interface SVGStringList

The SVGStringList interface is a list interface whose elements are DOMString values. An SVGStringList object represents a list of strings.

interface SVGStringList {

  readonly attribute unsigned long length;
  readonly attribute unsigned long numberOfItems;

  void clear();
  DOMString initialize(DOMString newItem);
  getter DOMString getItem(unsigned long index);
  DOMString insertItemBefore(DOMString newItem, unsigned long index);
  DOMString replaceItem(DOMString newItem, unsigned long index);
  DOMString removeItem(unsigned long index);
  DOMString appendItem(DOMString newItem);
  setter void (unsigned long index, DOMString newItem);
};

The behavior of all of the interface members of SVGStringList are defined in the List interfaces section above.

3.7. Other DOM interfaces

3.7.1. Interface SVGUnitTypes

The SVGUnitTypes interface defines a commonly used set of constants used for reflecting gradientUnits, patternContentUnits and other similar attributes. It is mixed in to other interfaces for elements that support such attributes.

[NoInterfaceObject]
interface SVGUnitTypes {
  // Unit Types
  const unsigned short SVG_UNIT_TYPE_UNKNOWN = 0;
  const unsigned short SVG_UNIT_TYPE_USERSPACEONUSE = 1;
  const unsigned short SVG_UNIT_TYPE_OBJECTBOUNDINGBOX = 2;
};

The unit type constants defined on SVGUnitTypes have the following meanings:

ConstantMeaning
SVG_UNIT_TYPE_USERSPACEONUSECorresponds to the 'userSpaceOnUse' attribute value.
SVG_UNIT_TYPE_OBJECTBOUNDINGBOXCorresponds to the 'objectBoundingBox' attribute value.
SVG_UNIT_TYPE_UNKNOWNSome other type of value.

3.7.2. Interface SVGTests

The SVGTests interface is used to reflect conditional processing attributes, and is mixed in to other interfaces for elements that support these attributes.

[NoInterfaceObject]
interface SVGTests {
  [SameObject] readonly attribute SVGStringList requiredExtensions;
  [SameObject] readonly attribute SVGStringList systemLanguage;
};

The requiredExtensions IDL attribute reflects the requiredExtensions content attribute.

The systemLanguage IDL attribute reflects the systemLanguage content attribute.

3.7.3. Interface SVGFitToViewBox

The SVGFitToViewBox interface is used to reflect the viewBox and preserveAspectRatio attributes, and is mixed in to other interfaces for elements that support these two attributes.

[NoInterfaceObject]
interface SVGFitToViewBox {
  [SameObject] readonly attribute SVGAnimatedRect viewBox;
  [SameObject] readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;
};

The viewBox IDL attribute reflects the viewBox content attribute.

The preserveAspectRatio IDL attribute reflects the preserveAspectRatio content attribute.

3.7.4. Interface SVGZoomAndPan

The SVGZoomAndPan interface is used to reflect the zoomAndPan attribute, and is mixed in to other interfaces for elements that support this attribute.

[NoInterfaceObject]
interface SVGZoomAndPan {

  // Zoom and Pan Types
  const unsigned short SVG_ZOOMANDPAN_UNKNOWN = 0;
  const unsigned short SVG_ZOOMANDPAN_DISABLE = 1;
  const unsigned short SVG_ZOOMANDPAN_MAGNIFY = 2;

  attribute unsigned short zoomAndPan;
};

The zoom and pan type constants defined on SVGZoomAndPan have the following meanings:

ConstantMeaning
SVG_ZOOMANDPAN_DISABLECorresponds to the 'disable' attribute value.
SVG_ZOOMANDPAN_MAGNIFYCorresponds to the 'magnify' attribute value.
SVG_ZOOMANDPAN_UNKNOWNSome other type of value.

The zoomAndPan IDL attribute represents the value of the zoomAndPan attribute. On getting zoomAndPan, the following steps are run:

  1. Let value be the current value of the zoomAndPan attribute (using the attribute's initial value if it is not present or invalid).
  2. Return the corresponding constant in the zoom and pan type constant table above for value.

On setting zoomAndPan, the following steps are run:

  1. Let value be the value being assigned to a zoomAndPan.
  2. If value is SVG_ZOOMANDPAN_UNKNOWN or does not correspond to an entry in the zoom and pan type constant table above, then return.
  3. Set the zoomAndPan attribute to the keyword value in the zoom and pan type constant table above that corresponds to value.

3.7.5. Interface SVGURIReference

The SVGURIReference interface is used to reflect the ‘href’ attribute and the deprecated xlink:href attribute.

[NoInterfaceObject]
interface SVGURIReference {
  [SameObject] readonly attribute SVGAnimatedString href;
};

The href IDL attribute represents the value of the ‘href’ attribute, and, on elements that are defined to support it, the deprecated xlink:href attribute. On getting href, an SVGAnimatedString object is returned that:

The SVGAnimatedString interface is defined to reflect, through its baseVal and animVal members, the deprecated xlink:href attribute, if that attribute is present and the ‘href’ is not, and to reflect the ‘href’ attribute in all other circumstances. Animation elements treat attributeName='xlink:href' as being an alias for targetting the ‘href’ attribute.

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 4: Document Structure

4.1. Defining an SVG document fragment: the ‘svg’ element

4.1.1. Overview

The content model and set of allowed attributes, as listed in definitions.xml, needs to be reviewed for consistency across all elements.

An SVG document fragment consists of any number of SVG elements contained within an svg element.

An SVG document fragment can range from an empty fragment (i.e., no content inside of the svg element), to a very simple SVG document fragment containing a single SVG graphics element such as a rect, to a complex, deeply nested collection of container elements and graphics elements.

An SVG document fragment can stand by itself as a self-contained file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent HTML or XML document.

The following example shows simple SVG content embedded inline as a fragment within a parent XML document. Note the use of XML namespaces to indicate that the svg and ellipse elements belong to the SVG namespace:

<?xml version="1.0" standalone="yes"?>
<parent xmlns="http://example.org"
        xmlns:svg="http://www.w3.org/2000/svg">
   <!-- parent contents here -->
   <svg:svg width="4cm" height="8cm">
      <svg:ellipse cx="2cm" cy="4cm" rx="2cm" ry="1cm" />
   </svg:svg>
   <!-- ... -->
</parent>

This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:

<?xml version="1.0" standalone="no"?>
<svg width="5cm" height="4cm" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Four separate rectangles
  </desc>
    <rect x="0.5cm" y="0.5cm" width="2cm" height="1cm"/>
    <rect x="0.5cm" y="2cm" width="1cm" height="1.5cm"/>
    <rect x="3cm" y="0.5cm" width="1.5cm" height="2cm"/>
    <rect x="3.5cm" y="3cm" width="1cm" height="0.5cm"/>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="4.98cm" height="3.98cm"
        fill="none" stroke="blue" stroke-width=".02cm" />

</svg>

svg elements can appear in the middle of SVG content. This is the mechanism by which SVG document fragments can be embedded within other SVG document fragments.

Another use for svg elements within the middle of SVG content is to establish a new SVG viewport. (See Establishing a new SVG viewport.)

4.1.2. Namespace

When SVG is parsed as a XML, for compliance with the Namespaces in XML Recommendation [XML-NS], an SVG namespace declaration must be provided so that all SVG elements are identified as belonging to the SVG namespace.

When using the HTML syntax, the namespace is provided automatically by the HTML parser.

<html>
<svg viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="50" fill="green">
</svg>
</html>

As the example shows there's no need to have an ‘xmlns’ attribute declaring that the element is in the SVG namespace when using the HTML parser. The HTML parser will automatically create the SVG elements in the proper namespace.

This section should talk about how a document's behavior is defined in terms of the DOM, and also explain how the HTML parser can create SVG fragments.

The SVG 2 namespace is http://www.w3.org/2000/svg, which is the same as for earlier versions of SVG.

The following are possible ways to provide a namespace declaration when SVG is parsed as XML. An ‘xmlns’ attribute without a namespace prefix could be specified on an svg element, which means that SVG is the default namespace for all elements within the scope of the element with the ‘xmlns’ attribute:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <rect x="10" y="10" width="80" height="80" fill="green" />
</svg>

If a namespace prefix is specified on the ‘xmlns’ attribute (e.g., xmlns:svg="http://www.w3.org/2000/svg"), then the corresponding namespace is not the default namespace, so an explicit namespace prefix must be assigned to the elements:

<svg:svg xmlns:svg="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <svg:rect x="10" y="10" width="80" height="80" fill="green" />
</svg:svg>

Namespace prefixes can be specified on ancestor elements (illustrated in the above example). For more information, refer to the Namespaces in XML Recommendation [XML-NS].

4.1.3. Definitions

structural element
The structural elements are those which define the primary structure of an SVG document. Specifically, the following elements are structural elements: defs, g, svg, symbol and use.
structurally external element
Elements that define its structure by reference to an external resource. Specifically, the following elements are structurally external elements when they have an ‘href’ attribute: audio, foreignObject, iframe, image, script, use and video.
SVG user agent
An SVG user agent is a user agent that is able to retrieve and render SVG content.
user agent

The general definition of a user agent is an application that retrieves and renders Web content, including text, graphics, sounds, video, images, and other content types. A user agent may require additional user agents that handle some types of content. For instance, a browser may run a separate program or plug-in to render sound or video. User agents include graphical desktop browsers, multimedia players, text browsers, voice browsers, and assistive technologies such as screen readers, screen magnifiers, speech synthesizers, onscreen keyboards, and voice input software.

A "user agent" may or may not have the ability to retrieve and render SVG content; however, an "SVG user agent" retrieves and renders SVG content.

current SVG document fragment
The document sub-tree which starts with the outermost ancestor svg element of a given SVG element, with the requirement that all container elements between the outermost svg and the given element are all elements in the SVG namespace.
outermost svg element
The furthest svg ancestor element that remains in the current SVG document fragment.
SVG document fragment
A document sub-tree which starts with an svg element which is either the root element of the document or whose parent element is not in the SVG namespace. An SVG document fragment can consist of a stand-alone SVG document, or a fragment of a parent document enclosed by an svg element. When an svg element is a descendant of another svg element, only the outermost svg element is the root of an SVG document fragment.
SVG elements
Any element in the SVG namespace.
graphics element
One of the element types that can cause graphics to be drawn onto the target canvas. Specifically: audio, canvas, circle, ellipse, foreignObject, iframe, image, line, mesh, path, polygon, polyline, rect, text, textPath, tspan and video.
graphics referencing element
A graphics element which uses a reference to a different document or element as the source of its graphical content. Specifically: audio, iframe, image, mesh, use and video.

4.1.4. The ‘svg’ element

SVG 2 Requirement: Support transforming svg elements.
Resolution: We will allow ‘transform’ on ‘svg’ in SVG 2.
Purpose: To allow transforms on nested svg elements, in line with author expectations.
Owner: Dirk (no action)
Status: Done
svg
Categories:
Container element, renderable element, structural element
Content model:
Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
Geometry properties:
DOM Interfaces:

The x and y attributes specify the top-left corner of the rectangular region into which an embedded svg element is placed. On an outermost svg element, these attributes have no effect.

For outermost svg elements, the width and height attributes specify the intrinsic size of the SVG document fragment. For embedded svg elements, they specify the size of the rectangular region into which the svg element is placed. In either case, a computed style of auto is treated equivalent to 100%.

Attribute definitions:

Name Value Initial value Animatable
zoomAndPan disable | magnify magnify no

Specifies whether the user agent should supply a means to zoom and pan the SVG content. See the definition of zoomAndPan for details.

If an SVG document is likely to be referenced as a component of another document, the author will often want to include a viewBox attribute on the outermost svg element of the referenced document. This attribute provides a convenient way to design SVG documents to scale-to-fit into an arbitrary SVG viewport.

The svg element exposes as event handler content attributes a number of the event handlers of the Window object. It also mirrors their event handler IDL attributes.

The onblur, onerror, onfocus, onload, and onscroll event handlers of the Window object, exposed on the svg element, replace the generic event handlers with the same names normally supported by SVG elements.

4.2. Grouping: the ‘g’ element

4.2.1. Overview

container element
An element which can have graphics elements and other container elements as child elements. Specifically: a, clipPath, defs, g, marker, mask, pattern, svg, switch, symbol and unknown.

The g element is a container element for grouping together related graphics elements.

A group of elements, as well as individual objects, can be given a name using the id attribute. Named groups are needed for several purposes such as animation and re-usable objects.

An example:

<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" width="5cm" height="5cm">
  <desc>Two groups, each of two rectangles</desc>
  <g id="group1" fill="red">
    <rect x="1cm" y="1cm" width="1cm" height="1cm"/>
    <rect x="3cm" y="1cm" width="1cm" height="1cm"/>
  </g>
  <g id="group2" fill="blue">
    <rect x="1cm" y="3cm" width="1cm" height="1cm"/>
    <rect x="3cm" y="3cm" width="1cm" height="1cm"/>
  </g>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="4.98cm" height="4.98cm"
        fill="none" stroke="blue" stroke-width=".02cm"/>
</svg>

View this example as SVG (SVG-enabled browsers only)

A g element can contain other g elements nested within it, to an arbitrary depth.

4.2.2. The ‘g’ element

g
Categories:
Container element, renderable element, structural element
Content model:
Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
DOM Interfaces:

4.3. Unknown elements

SVG 2 Requirement: Have unknown elements treated as g for the purpose of rendering.
Resolution:
Purpose: To allow fallbacks without the use of switch, and to align with the behavior of unknown elements in HTML.
Owner: Nobody (no action)
Status:
unknown
Categories:
Container element, renderable element
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:

Treating unknown elements as a generic container element, resulting in the rendering of their child trees, and assigning the SVGUnknownElement interface to unknown elements are both at risk, with no known implementations.

Unknown elements are all elements that are in the SVG namespace that are not defined by this specification or any SVG module. The SVGUnknownElement interface must be used for unknown elements.

Unknown elements in the SVG namespace are renderable elements and container elements. They must render as if the unknown element were replaced with a g element or tspan, according to context. Any global attribute or property that is valid on any SVG graphics element is also valid on unknown elements, and must be processed as normal. This includes conditional processing attributes, ARIA attributes, data attributes, and the lang, id, class, tabindex and style. Styles specified on unknown elements must be inherited by their child elements according to the normal rules for inheritance for each style property.

Known and unknown elements in other namespaces that occur as a child of any SVG element except foreignObject, must not render unless explicitly stated otherwise in this specification.

Known elements in the SVG namespace that occur in places where SVG's content model doesn't explicitly allow it must not render unless explicitly stated otherwise in this specification.

Consequently, in the following example:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 200">
  <rect x=".1" y=".1" width="699.8" height="199.8"
        fill="none" stroke="blue" stroke-width=".2" />
  <mysteryElement>
    <path d="M0 0h600v200h-600z" fill="darkkhaki"/>
  </mysteryElement>
  <hideElement xmlns="http://www.example.com/invisibleML">
    nothing to see here
    <path d="M0 0h300v100h-300z" fill="whitesmoke"/>
  </hideElement>
  <text y="2em" font-size="20"><text>This text must not be visible</text></text>
  <linearGradient>
    <gradientExtension>
      <path d="M300 0h100v200h-100z" fill="fuchsia"/>
    </gradientExtension>
  </linearGradient>
  <div xmlns="http://www.w3.org/1999/xhtml">This must not be visible</div>
</svg>

View this example as SVG (SVG-enabled browsers only)

4.4. Defining content for reuse, and the ‘defs’ element

4.4.1. Overview

SVG allows graphical objects to be defined for later reuse. To do this, it makes extensive use of URL references [RFC3987] to these other objects. For example, to fill a rectangle with a linear gradient, you first define a linearGradient element and give it an ID, as in:

<linearGradient id="MyGradient">...</linearGradient>

You then reference the linear gradient as the value of the fill property for the rectangle, as in:

<rect style="fill:url(#MyGradient)"/>

Some types of element, such as gradients, will not by themselves produce a graphical result. They can therefore be placed anywhere convenient. However, sometimes it is desired to define a graphical object and prevent it from being directly rendered. it is only there to be referenced elsewhere. To do this, and to allow convenient grouping defined content, SVG provides the ‘defs’ element.

It is recommended that, where possible, referenced elements be defined prior to the elements that use them, in document order. Collecting all referenced elements inside of a single defs element near the top of the file can make the markup easier to read and understand.

4.4.2. The ‘defs’ element

defs
Categories:
Container element, never-rendered element, structural element
Content model:
Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
DOM Interfaces:

The defs element is a container element for referenced elements. For understandability and accessibility reasons, it is recommended that, whenever possible, referenced elements be defined inside of a defs.

The content model for defs is the same as for the g element; thus, any element that can be a child of a g can also be a child of a defs, and vice versa.

Elements that are descendants of a defs are not rendered directly; the display value for the defs element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute. Note, however, that the descendants of a defs are always present in the source tree and thus can always be referenced by other elements; thus, the value of the display property on the defs element does not prevent those elements from being referenced by other elements.

4.5. The ‘desc’ and ‘title’ elements

4.5.1. Definition

descriptive element
An element which provides supplementary descriptive information about its parent. Specifically, the following elements are descriptive elements: desc, metadata and title.

Multilingual descriptive text selection, based on the lang attribute, was added to allow internationalization of the desc and title elements.

New in SVG 2. Adding 'lang' resolved at Rigi Kaltbad face-to-face. Removed text that limited number of 'desc' and 'title' elements. Status: Done.

Any container element or graphics element in an SVG document can have zero or more desc and/or title elements as children, whose content is text. desc and title elements are not visually rendered as part of the graphics. The display value for the title and desc elements must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.

Multiple sibling desc or title elements must have different languages, as defined using a lang attribute (or xml:lang attribute) on the descriptive element or an ancestor. The user agent must select the element of each type whose language best matches language preferences set by the user. A descriptive element with an empty-string language tag (indicating no language, for example a text alternative consisting of emoji symbols) is a lowest-priority match for any user, ranked below all user-specified language preferences. If multiple equally valid matches exist, the first match should be used. If no match exists for either 'title' or 'desc', the first element of that type must be selected.

The following example shows alternative language titles on a re-used star icon, inline in an HTML document. The example assumes that the HTML document as a whole has a correctly-declared language of en (English without a specified country code).

<svg>
  <use href="#star">
    <title>Favourite</title>
    <title lang="en-us">Favorite</title>
    <title lang="nl">Favoriet</title>
    <title lang="">★</title>
  </use>
</svg>
  

The first title element inherits the language of the document (en); the others have explicitly-declared languages for each element. If the user's preferred language (out of those provided) is American English, the icon title is the American spelling "Favorite". If the user's preferred language is Dutch, the icon title is "Favoriet". If the user's preference list includes generic English ranked higher than Dutch, the title is "Favourite" with British spelling. If the user does not understand either Dutch or English, the title will be the star symbol character—which is not ideal (most screen readers will read it as a localized version of "black star"), but better than no text alternative at all.

Authors should be aware that SVG 1.1-supporting user agents that have not yet implemented multi-lingual descriptive text will normally select the first element of each type, regardless of user preferences. SVG 1.1 user agents may also fail to recognize a title element that is not the first child of its parent, or a desc element that has previous siblings that are not other descriptive elements.

The use of more than one title or desc element to provide localised information is at risk, with no known implementations.

User agents must make the text content of selected 'title' and 'desc' elements available to platform accessibility APIs as part of the name and description computation for the parent element, as defined in the SVG Accessibility API Mappings [SVG-AAM] specification.

Inclusion of any 'title' or 'desc' elements as a direct child of a rendered element indicates that the rendered element is of semantic importance in the graphic. Authors should not, and authoring tools must not, include empty 'title' or 'desc' elements with no text content or whitespace-only text content, as this will result in a nameless object being presented to assistive technology users.

If an individual graphic element has no meaning on its own, alternative text should instead be provided for the nearest container element that describes a meaningful object. Authors should use grouping (g) elements to structure their drawing elements into meaningful objects, and name those groups with title. Conversely, if a container object is used simply to apply styles or layout, and neither defines an object nor provides meaningful grouping structure, it does not need alternative text.

Descriptive text elements whose parent is not rendered may be used by authors or authoring tools as reference information; authors are warned that this data is not normally available to end users viewing the graphic through assistive technologies. Nonetheless, a non-rendered element may be referenced as part of the accessible name or description of a rendered element (as defined in SVG-AAM), and the recursive computation will use descriptive child elements of the referenced element.

title
Categories:
Descriptive element, never-rendered element
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:

The title child element represents a short text alternative for the element.

On a link, this could be the title or a description of the target resource; on an image or drawing object, it could be a short description of the graphic; on interactive content, it could be a label for, or instructions for, use of the element; and so forth.

Authors should not provide redundant information in a title element if there is also a visible label for the drawing element (e.g., using a text element). Instead, the visual label should be associated with the drawing element using an aria-labelledby attribute.

Interactive user agents should make the plain text content of title elements available in response to user interaction, in a manner consistent with platform conventions; existing user agents commonly render title elements as a tooltip on hovering the parent element.

Authors should provide a title child element to the root svg element within a stand-alone SVG document. Since users often consult documents out of context, authors should provide context-rich titles. Thus, instead of a title such as "Introduction", which doesn't provide much contextual background, authors should supply a title such as "Introduction to Medieval Bee-Keeping" instead. For reasons of accessibility, user agents should always make the content of the ‘title’ child element to the root svg element available to users. However, this is typically done through other means than the tooltips used for nested SVG and graphics elements, e.g., by displaying in a browser tab.

desc
Categories:
Descriptive element, never-rendered element
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:

The desc element represents more detailed textual information for the element such as a description. This is typically exposed to assistive technologies to provide more detailed information, such as a description of the visual appearance of a graphic or help to explain the functionality of a complex widget. It is not typically available to other users, so should not be used for essential instructions.

Authors may associate detailed information, including visible text, with part of the graphic using aria-describedby attribute (on the described element or a parent container), with the value being an ID reference to one or more SVG or HTML elements containing the description. The aria-describedby attribute takes precedence over the child desc when providing a description. If an element has both visible description and a child desc element providing supplementary information, authors should explicitly include the id of the element itself in its own aria-describedby list, in order to concatenate the two descriptions together.

Description and title elements may contain marked-up text from other namespaces. However, authors should not rely on such markup to provide meaning to alternative text; only the plain text content is currently required to be exposed to assistive technologies.

4.6. The ‘metadata’ element

Metadata which is included with SVG content should be specified within metadata elements. The contents of the metadata should be elements from other XML namespaces, with these elements from these namespaces expressed in a manner conforming with the Namespaces in XML Recommendation [XML-NS].

SVG 2 removes the recommendation to structure metadata elements in any particular way.

metadata
Categories:
Descriptive element, never-rendered element
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:

Metadata content is not directly rendered; the display value for the metadata element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.

Here is an example of how metadata can be included in an SVG document. The example uses the Dublin Core version 1.1 schema. (Other XML-compatible metadata languages, including ones not based on RDF, can be used also.)

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
    xmlns = 'http://www.w3.org/2000/svg'>
    <desc xmlns:myfoo="http://example.org/myfoo">
      <myfoo:title>This is a financial report</myfoo:title>
      <myfoo:descr>The global description uses markup from the
        <myfoo:emph>myfoo</myfoo:emph> namespace.</myfoo:descr>
      <myfoo:scene><myfoo:what>widget $growth</myfoo:what>
      <myfoo:contains>$three $graph-bar</myfoo:contains>
        <myfoo:when>1998 $through 2000</myfoo:when> </myfoo:scene>
   </desc>
    <metadata>
      <rdf:RDF
           xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#"
           xmlns:dc = "http://purl.org/dc/elements/1.1/" >
        <rdf:Description about="http://example.org/myfoo"
             dc:title="MyFoo Financial Report"
             dc:description="$three $bar $thousands $dollars $from 1998 $through 2000"
             dc:publisher="Example Organization"
             dc:date="2000-04-11"
             dc:format="image/svg+xml"
             dc:language="en" >
          <dc:creator>
            <rdf:Bag>
              <rdf:li>Irving Bird</rdf:li>
              <rdf:li>Mary Lambert</rdf:li>
            </rdf:Bag>
          </dc:creator>
        </rdf:Description>
      </rdf:RDF>
    </metadata>
</svg>

4.7. The ‘symbol’ element

The symbol element is used to define graphical templates which can be instantiated by a use element but which are not rendered directly.

A symbol establishes a nested coordinate system for the graphics it contains. When a symbol is instantiated as the referenced element of a use element, it is therefore rendered very similarly to a nested svg element.

symbol
Categories:
Container element, structural element
Content model:
Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
Geometry properties:
DOM Interfaces:

The x, y, width, and height geometry properties have the same effect as on an svg element, when the symbol is instantiated by a use element. In particular, if width and height compute to auto (and are not over-ridden by values on the instantiating use element), then they will be treated as a value of 100%.

New in SVG 2. Allowing geometry properties to be specified on a symbol provides a more consistent rendering model, and allows authors to set a default size for each symbol (which may still be over-ridden by attributes on the use element).

4.7.1. Attributes

Name Value Initial value Animatable
refX <length> | left | center | right (none) yes
refY <length> | top | center | bottom (none) yes

New in SVG 2. Added to make it easier to align symbols to a particular point, as is often done in maps. Similar to the matching attributes on marker.

Add refX/refY to symbol element. Resolved at Leipzig F2F. Status: Done.

We will add top/center/bottom, left/center/right keywords to refX/refY on marker/symbol. Resolved at London F2F. Values inspired by 'background-position'. Status: Done.

The refX and refY attributes define the reference point of the symbol which is to be placed exactly at the symbol's x,y positioning coordinate, as defined by the cumulative effect of the x and y properties and any transformations on the symbol and its host use element.

Keyword values have the same meaning as for the refX and refY attributes on the marker element, resolving to 0%, 50%, or 100% in the applicable direction.

Unlike other positioning attributes, refX and refY are interpreted as being in the coordinate system of the symbol contents, after application of the viewBox and preserveAspectRatio attributes. If one or both of the attributes is not specified, no adjustment is made in the corresponding dimension, and the top or left side of the symbol's rectangular viewport region (regardless of the viewBox coordinates) is positioned at the x,y point.

For backwards compatibility, the behavior when refX and refY are not specified on a symbol is different from when they are specified with a value of 0, and therefore different from the behavior when equivalent attributes are not specified on a marker.

4.7.2. Notes on symbols

The use of symbol elements for graphics that are used multiple times in the same document adds structure and semantics. Closely related to the symbol element are the marker and pattern elements; all three define a container of graphical content that can be rendered repeatedly at various positions and scales in the SVG. However, while re-used graphics in a pattern and marker provide a graphical effect on another element, the content in a symbol will be embedded as fully interactive content, within a use-element shadow tree.

The user agent style sheet sets the overflow property for symbol elements to hidden, which causes a rectangular clipping path to be created at the bounds of symbol's SVG viewport. Unless the overflow property is overridden, any graphics within the symbol which goes outside of the symbol's SVG viewport will be clipped.

symbol elements must never be rendered directly; their only usage is as something that can be referenced using the use element. The user agent must set the display property on the symbol element to none, as part of the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.

The generated instance of a symbol that is the direct referenced element of a use element must always have a computed value of inline for the display property. In other words, it must be rendered whenever the host use element is rendered. The user agent style sheet again defines this declaration to have importance over any other CSS rule or presentation attribute. Any other symbol that is cloned to create an element instance within the use-element shadow tree behaves as a symbol definition, and must not be rendered.

4.8. The ‘use’ element

SVG 2 Requirement: Allow use to reference an external document's root element by omitting the fragment.
Resolution: We will relax referencing requirements to particular elements to allow dropping fragments to mean referencing root element, where it makes sense, such as with use, in SVG 2.
Purpose: To avoid requiring authors to modify the referenced document to add an ID to the root element.
Owner: Cameron (ACTION-3417)
Status: Done
use
Categories:
Graphics referencing element, renderable element, structural element, structurally external element
Content model:
Any number of the following elements, in any order:clipPath, mask, script, style
Attributes:
Geometry properties:
DOM Interfaces:

The use element references another element, a copy of which is rendered in place of the use in the document. The referenced element may be a container element, in which case a copy of the complete SVG document subtree rooted at that element is used.

The cloned content inherits styles from the use element and can be the target of user events. However, these cloned element instances remain linked to the referenced source and reflect DOM mutations in the original. In addition, all style rules that apply in the scope of the referenced element also apply in the scope of the cloned shadow tree.

The x, y, width and height geometric properties specify the positioning of the referenced element. The width and height attributes only have an effect if the referenced element defines a viewport (i.e., if it is a svg or symbol); if so, a value other than auto for the use element overrides the value of the corresponding geometric property on that element.

A negative value for width or height must be treated as an illegal value. If width or height is zero, and the properties have an effect on the referenced element, then rendering of that element will be disabled.

The x and y properties affect the user coordinate system for the element. See the Layout section for implementation details.

Name Value Initial value Animatable
href URL [URL] (none) yes

An URL reference to the element/fragment within an SVG document to be cloned for rendering.

The use element can reference an entire SVG document by specifying an href value without a fragment. Such references are taken to be referring to the root element of the referenced document.

Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.

New in SVG 2. An href without a fragment allows an entire SVG document to be referenced without having to ensure that it has an ID on its root element.

User agents may restrict external resource documents for security reasons. In particular, this specification does not allow cross-origin resource requests in use. A future version of this or another specification may provide a method of securely enabling cross-origin re-use of assets.

When the href attribute is set (or, in the absence of an href attribute, an xlink:href attribute), the user agent must process the URL. The target element that results from URL processing is the referenced element of the use.

If the referenced element that results from resolving the URL is neither an SVG element nor an HTML-namespaced element that may be included as a child of an SVG container element, then the reference is invalid and the use element is in error.

If the referenced element is a (shadow-including) ancestor of the use element, then this is an invalid circular reference and the use element is in error.

Otherwise, the user agent must generate a shadow tree of re-used graphics to render as the contents of the use element, as described in the next section, The use-element shadow tree.

A use that has an unresolved or invalid URL reference is not rendered. For the purpose of bounding box calculations, it is equivalent to an empty container element.

4.8.1. The use-element shadow tree

The re-used graphics generated by a use element are defined in terms of a shadow tree. In terms of interactivity and style inheritance, they are therefore quite different from other types of re-used graphics in SVG, such as pattern and marker content.

Elements in the shadow tree are rendered as if the use element was a container and they were its children. However, the SVG Document Object Model (DOM) only contains the use element and its attributes. The SVG DOM does not include the element instances as children of the use element.

User agents that support scripting and the document object model must implement the use-element shadow tree as described in this section and in conformance with the Shadow DOM specification [SHADOWDOM], or its future replacement. In contrast, user agents that do not support the dynamic interactive processing mode may not need to implement all the details of the shadow DOM. However, all user agents must ensure that the layout and style inheritance for the re-used graphics, and any multimedia and declarative animations if applicable, are rendered in the same way as if the shadow DOM was implemented.

The following definitions apply when discussing use elements and their shadow trees:

referenced element
The element specified by the href (or xlink:href) attribute on the use element, or the root element of a document referenced by that attribute if the URL provided does not include a target fragment that links to a specific element id.
referenced document subtree
referenced graphics
The referenced element, and all of its descendent nodes.
shadow root
A ShadowRoot object, a type of DocumentFragment node which is associated with a host Element, and which contains the content that will be used to render that host. A shadow root should be implemented in conformance with the Shadow DOM specification [SHADOWDOM], or its future replacement.
shadow host
host
An element that has an associated shadow root; usage is consistent the definition of host in the DOM standard.
shadow tree
A node tree whose root is a shadow root; usage is consistent the definition of shadow tree in the DOM standard.
use-element shadow tree
A shadow tree whose host is a use element, which contains element instances generated by cloning the referenced graphics.
element instance
instance
An element in the use-element shadow tree, which is generated by cloning a corresponding element in the referenced document subtree.
instance root
The element instance for the referenced element; it is always a direct child of the use element's shadow root.
corresponding element
For each element instance, the element in the referenced document subtree from which it is cloned.
corresponding use element
For each element instance, the use element which causes it to be rendered in the document. This is the instance's shadow root's host use element if that element is not itself an element instance within a use element shadow tree, or is that element's corresponding use element otherwise, recursively exiting shadow trees as many times as necessary to reach a use element that was not itself generated as part of the shadow tree of another use element.

When the user agent successfully resolves a use element to identify a referenced element, the user agent must create a use-element shadow tree whose host is the use element itself. The shadow tree must be created even if the use element is not rendered because it is a descendent of a never-rendered element, because of conditional processing, or because of the display property being set to none on it or an ancestor element.

Each node in the shadow tree is an instance of a corresponding node from the referenced document subtree. The shadow nodes all descend from the instance root, which is the instance of the referenced element, and which itself is a direct child of the shadow root node.

The shadow tree is open (inspectable by script), but read-only. Any attempt to directly modify the elements, attributes, and other nodes in the shadow tree must throw a NoModificationAllowedError.

Within a use-element shadow tree, script elements are inert (do not execute); audio and video elements are subject to the limitations specified in the Multimedia section.

Previous versions of SVG restricted the contents of the shadow tree to SVG graphics elements. This specification allows any valid SVG document subtree to be cloned. Cloning non-graphical content, however, will not usually have any visible effect.

If the referenced element is in an external file, then all URL references in attributes and style properties must be made absolute as described in Generating the absolute URL, before copying the value to the element instances. The shadow tree itself uses the same document base URL as the document that includes it.

The user agent must ensure that all mutations to the referenced document subtree are reflected in the shadow tree. This includes changes to elements, attributes, and text and other nodes. In addition, changes to the stylesheets in effect for the referenced graphics must be reflected in changes to the stylesheets in the shadow tree's scope, as described futher in the section on style inheritance.

If either the use element or the referenced element is altered in a way that causes the use element's URL reference to become unresolved again, then the entire shadow tree for that use element is discarded.

When a use references another element which is another use or whose content contains a use element, then the shadow DOM cloning approach described above is recursive. However, a set of references that directly or indirectly reference a element to create a circular dependency is an invalid circular reference. The use element or element instance whose shadow tree would create the circular reference is in error and must not be rendered by the user agent.

4.8.2. Layout of re-used graphics

The value of the x, y, width and height properties on a use element are used to position the re-used graphics and to set the viewport size if the referenced element defines a nested viewport. The effect of these properties on a use element is notably different from their effect on a graphics element, or from their effect in CSS box layout.

The x and y properties define an additional transformation (translate(x,y), where x and y represent the computed value of the corresponding property) to be applied to the use element, after any transformations specified with other properties (i.e., appended to the right-side of the transformation list).

For historical reasons, the supplemental transformation is applied to the use element itself, rather than solely to the re-used content in the shadow tree. This affects the coordinate system used for any masks, clipping paths, or filters applied to the use element and calculated in userSpaceOnUse units.

To apply userSpaceOnUse graphical effects in an un-transformed coordinate space, while also using the x and y to position the graphics, authors can nest the use element inside a g, and apply the graphical effects to the g element.

The width and height properties on the use element override the values for the corresponding properties on a referenced svg or symbol element when determining the used value for that property on the instance root element. However, if the computed value for the property on the use element is auto, then the property is computed as normal for the element instance.

These properties can therefore be used to scale a graphic that defines its own coordinate system, each time it is re-used. Because auto is the initial value, if dimensions are not explicitly set on the use element, the values set on the svg or symbol will be used as defaults.

The width and height properties on the use element have no effect if the referenced element does not establish a new viewport. In particular, the use element does not itself establish a new viewport, and therefore does not affect the interpretation of percentages in the re-used graphics.

In all other ways, rendering and layout of elements within the use-element shadow tree occurs as if the use element was a container for its shadow content. In particular, unless elements within the shadow tree establish a new viewport, they must be drawn in the coordinate system in which the use element is defined (including any cumulative transformations). This affects the interpretation of percentage lengths, and also graphical effects with userSpaceOnUse units.

4.8.3. Style Scoping and Inheritance

The use-element shadow tree, like other shadow trees, exhibits style encapsulation, as defined in the CSS Scoping module [css-scoping-1]. This means that elements in the shadow tree inherit styles from its host use element, but that style rules defined in the outer document do not match the elements in the shadow tree. Instead, the shadow tree maintains its own list of stylesheets, whose CSS rules are matched against elements in the shadow tree.

Presentation attributes and the style attribute are cloned from the elements in the referenced graphics into the element instances in the same manner as other attributes.

When the referenced element is from the same document as the use element, the same document stylesheets will apply in both the original document and the shadow tree document fragment. Any changes to the stylesheets in the main document also affect the shadow tree; the StyleSheetList object accessed through the document and shadow root document fragment's styleSheets properties must be identical. If a style element is duplicated as part of the referenced document subtree, then the styleSheet property on the element instance points to the same object as for the corresponding element.

When the referenced element is from an external document, the stylesheet objects generated when processing that document apply to the shadow tree, and are read-only. All URL references in the stylesheet, including fragment-only references, must be made absolute, relative to the URL of the document that contains the referenced element. User agents may re-use the same stylesheet objects for any shadow trees that reference that same external document.

Style rules that are scoped to the shadow tree cannot normally affect any elements in the main document. Similarly, style rules in the main document can only affect the shadow tree elements by changing inherited values. However, CSS Scoping defines special selectors for styling the host element from within the shadow tree, or for adjusting styles within the shadow tree in response to changes in the host's context [css-scoping-1].

CSS media queries within a shadow tree's scope are evaluated using the same device features and dimensions as the corresponding "light" document (that is, the document that contains the corresponding use element for the shadow tree, after recursively exiting all nested shadow trees).

In most cases, the element instance in the shadow tree will match the same style rules as its corresponding element in the original document. However, if a CSS rule uses a complex selector to match an element based on its ancestors or siblings, and those ancestors or siblings are not cloned as part of the shadow tree, then that rule would no longer match the element instance. Similarly, child-indexed pseudo-classes such as nth-of-type and nth-child may apply to one element but not the other. This represents a change from how style cloning was defined in previous versions of SVG.

The following example demonstrates both the consistent and changed style-matching rules. The circle on the left is re-used to draw the circle on the right. The original circle has styles set in various ways:

  • stroke-width (20) is set in a presentation attribute on the circle itself.
  • stroke-opacity (0.7) is set via a CSS rule with a simple selector matching the circle tag name.
  • stroke color (green) is set using a complex CSS selector, matching the circle as a descendent of an element with class special.
  • fill color is not set directly on the circle, so is inherited from the style set on the containing g element (blue).

In the SVG 1.1 style-cloning model, the specified style values would be cloned from the original element to the element instance. The re-used circle would have the same styles as the original, except that the fill value would be inherited from the use (orange) instead of from the g (blue).

In the shadow DOM model required by SVG 2, the styles for the re-used circle are calculated as follows:

  • the stroke-width (20) presentation attribute is cloned to the element instance.
  • the CSS rule setting stroke-opacity (0.7) is part of the CSS stylesheet cloned into the shadow tree; it matches the circle tag name of the element instance, so is applied.
  • the CSS rule with the complex selector is also part of the cloned stylesheet, but it does not match the element instance of the circle, which is not a descendent of an element with class special; instead, stroke color on the circle is inherited from the host use element (purple).
  • fill color is still not set directly, so is once again inherited from the host use element.

The re-used circle therefore differs from the original in both fill color (because it inherits from a different element) and stroke color (because the complex selector no longer matches).

<svg xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     width="200" height="100" viewBox="0 0 200 100">
  <title>Style inheritance and the use element</title>
  <desc>
    Two circles, one of which is a re-styled clone of the other.
    This file demonstrates one of the cases where 
    the shadow-DOM style matching rules in SVG 2
    have a different effect than the SVG 1.1 style cloning rules. 
    The original circle on the left
    should have blue fill 
    and green stroke.
    In a conforming SVG 1.1 user agent,
    the re-used circle on the right
    should have orange fill and green stroke.
    In a conforming SVG 2 user agent,
    the re-used circle should have orange fill and purple stroke.
    In all cases,
    the stroke should be partially transparent
    and 20 units wide, 
    relative to a total circle diameter of 100 units.
  </desc>
  <style type="text/css">
    circle          { stroke-opacity: 0.7; }
    .special circle { stroke: green; }
    use             { stroke: purple;
                      fill: orange; }
  </style>
  <g class="special" style="fill: blue">
     <circle id="c" cy="50" cx="50" r="40" 
             stroke-width="20" />
  </g>
  <use xlink:href="#c" x="100" />
</svg>
Example Use-changed-styles — A 'use' element copying a 'circle', with various style matching rules demonstrated

Example Use-changed-styles

View this example as SVG (SVG-enabled browsers only)

Previous versions of SVG were not clear about how dynamic pseudo-classes (such as :hover) should apply to element instances. The shadow tree model requires that all such pseudo-classes are matched independently to the element instance or to its corresponding element, depending on which element the user is interacting with.

Specifying 'visibility:hidden' on a use element does not guarantee that the referenced content will not be rendered. Unlike the display or the opacity properties, the visibility property does not appy directly to container elements, and therefore does not apply directly to the use element. Because visibility is normally inherited, hiding the use element will often hide the child content, but not necessarily. If any graphics elements in the shadow tree have 'visibility:visible' specified, then that element will be visible even if the use element specifies 'visibility:hidden'.

In the following example, key style rules are as follows:

.dark {
  visibility: hidden;
}
.eyes {
  visibility: visible;
}
svg:hover .dark, svg:focus .dark {
  visibility: visible;
}

The "dark" class is set on the group containing the use elements, so all parts of the re-used graphics inherit the hidden visibility setting, except for the subtrees with class "eyes", where it is reset to visible. Upon hovering or focusing the graphic, the hiding effect is removed.

Multiple use-copies of a creature-symbol on a black background; the use elements have visibility: hidden, but the creatures' eyes have visibility: visible.

Example Use-visibility-hidden, default styles

Multiple use-copies of a rabbit-symbol on a light green background; each rabbit has different=coloured fur, but the same pink noses and white fluffy tails.

Example Use-visibility-hidden, interactive styles

View this example as SVG

The example also demonstrates inheritance of other style properties (fill and stroke) specified on the use elements, and how these are also not used if any elements within the symbol specify explicit values (e.g., the pink noses and ears and the white tails).

4.8.4. Multimedia in use-element shadow trees

When a use-element shadow tree includes audio or video elements, the following behaviors must be enforced:

4.8.5. Animations in use-element shadow trees

The Web Animations API and the SVG Animations specification define ways to animate attributes and styles on targetted elements without directly manipulating DOM properties. User agents that implement those features must ensure that all animations that apply to an element in a referenced document subtree also apply to instances of that element in a use-element shadow tree, as described in this section.

Scripted animations created by directly manipulating attributes on elements in the referenced graphics (including the style attribute or its IDL property) will be propagated to the element instances in the shadow tree in the same manner as any other DOM manipulations.

Animation effects applied using CSS will be duplicated along with other stylesheet rules, following the procedure specified in the Style Scoping and Inheritance section.

All animations within a use-element shadow tree operate in the same document timeline as for the corresponding use element, regardless of whether the referenced element is from the same or an external document.

For animation effects applied using a Web Animations API method [WAAPI], if the target of the animation is a corresponding element to an element instance in a shadow tree, the user agent must construct a ShadowAnimation whose source is that Animation object and whose target is the element instance. If there are multiple instances of the element in different trees, then there will be multiple shadow animations, one for each.

The user agent must create such a ShadowAnimation for all Web Animations API animations in effect (including pending and frozen animations) at the time the shadow tree is generated, and for any new animations applied while the shadow tree exists. The user agent must not create ShadowAnimation objects for CSS animations or animation elements (as these are duplicated separately).

As part of the inteface definition, a ShadowAnimation is read-only, and must reflect any changes to its sourceAnimation.

Any attempts to directly apply new animations to a target that is a read-only element instance (or pseudo-element) within a use-element shadow tree must throw a NoModificationAllowedError.

For each animation element that targets an element in the referenced document subtree, the user agent must ensure that an equivalent animation element is in effect in the use-element shadow tree. If the animation element itself is part of the referenced document subtree, then this happens as a matter of course through the creation of an element instance for the animation element. Otherwise, the user agent must generate an element instance for the animation element that has the same effect as if it was a node in the shadow tree. The effective document order for these generated animation elements must be the same as the document order for their corresponding elements.

Each animation element or instance must only affect a target element in the same node tree (shadow or light), regardless of whether the targetting is implicit (the parent element) or explicit (a URL cross-reference to an element id). In this way, the one-to-one relationship between animation elements and target elements is preserved.

The id attribute is cloned, like any other attribute, from the corresponding element to the element instance; This does not conflict with the requirement for id to be unique, because the clone and the original are in distinct node trees.

All animation elements, in the document or in the shadow trees, which are timed to begin or end in response to an event on another element identified by its id attribute, must also begin or end when any instance of an element with that id receives the same event. This is consistent with how event listeners on a referenced element also listen to events on instances of that element, as described in the section on Event handling in use-element shadow trees. This behavior does not apply to animation begin or end times defined only by an event and not by an id (and therefore implicitly listening for the event on the target element); in that case, each animation element is only triggered by its own target.

At the time an instance of an animation element is generated within a shadow tree, if there is an active animation associated with the corresponding element (including a frozen animation), and the timing event that initiated that animation would also have initiated the instance if it existed, then the animation for the element instance must be initiated, with its begin time adjusted backwards in the document timeline to match the timing of the corresponding element.

In many cases, the requirements of this section mean that the element instance and its corresponding element will animate synchronously. This will be the case if the animation is purely time-based, or if it begins and ends in response to user interaction on an element referenced by its id. However, if the animation is triggered by a user interaction event on the targetted element (implicitly), then only the element or element instance that receives the interaction event will display the animation.

This is a change from previous versions of SVG, which required all animations on the corresponding element to be mirrored, regardless of user interaction, but which did not offer clear guidance for responding to user interactions with the element instances. The change ensures that interactive animations declared with animation elements behave in the same manner as interactive CSS styles and CSS animations.

In order to create animations that apply to all instances when any instance or the original element receives an event, specify the element id explicitly:


<set href="#target" begin="mouseover" ... />
  <!-- only affects the element that is moused over -->
  
<set href="#target" begin="target.mouseover" ... />
  <!-- affects all instances of the element with the id 'target',
          in all light and shadow node trees,
          when any of them are moused over -->
  

4.8.6. Event handling in use-element shadow trees

Element in a use-element shadow tree can both listen for and be the target of DOM events. Event retargetting provides encapsulation, so that the details of the shadow DOM structure are masked when an event bubbles out of the shadow tree and into the light.

Event retargeting is new in SVG 2. It provides consistency with the Shadow DOM specification, with existing implementations, and with the expectations of authors who are only concerned with elements in the main DOM.

Any event listeners defined on an element in the referenced graphics must also listen for the same event, at the same capture phase, on each instance of that element in a use-element shadow tree. This includes event listeners assigned using event attributes (which would be duplicated as with any other DOM attribute) and also event listeners assigned using the addEventListener method. The user agent must ensure that the list of event listeners for each element instance is synchronized to match its corresponding element. An event listener cannot be directly assigned to a read-only element instance in a use-element shadow tree. Any attempt to add an event listener to such an element must throw a NoModificationAllowedError.

Events in the use-element shadow tree are dispatched and bubble according to the shadow tree event path and event retargeting algorithm [SHADOWDOM].

In general, the event path for a use-element shadow tree is constructed from the ancestors of the event target element up to the shadow root, then the host use element and its event path through to the document window. This means that, in the capture phase, an event propagates from the window through the regular document tree to the use element and then to the shadow root object and down through the shadow tree (or recursively through multiple shadow trees) to the event target element. In the bubbling phase, the event passes in the opposite direction, from the shadow tree elements to the shadow root, then to the use element and its ancestors.

The event retargeting algorithm ensures that from the perspective of event listeners on the use element or its ancestors, all events targetted to element instances in the shadow tree instead have a target of the use element itself. If the event has both a target and a relatedTarget, and both of these properties would be retargeted to point to the same use element, then the event is not propagated at all outside of the shadow tree. This would occur, for example, if focus moved from one element inside the shadow tree to another. Certain other event types are constrained to not propagate outside of the shadow tree in which they were created.

In contrast, event listeners that process the event while it is propagating through the shadow tree (because the listener has been added to a corresponding element) will receive the event with its target pointing to a read-only element instance in the shadow tree. The correspondingElement and correspondingUseElement properties of that element instance can be used to connect it to the modifiable elements in the main DOM.

4.9. Conditional processing

4.9.1. Conditional processing overview

SVG contains a switch element along with attributes requiredExtensions and systemLanguage to provide an ability to specify alternate viewing depending on the capabilities of a given user agent or the user's language.

Attributes requiredExtensions and systemLanguage act as tests and evaluate to either true or false. The switch renders the first of its children for which all of these attributes test true. If the given attribute is not specified, then a true value is assumed.

When an element is excluded because of conditional processing, it is treated as if it had a used value of none for the display property. Similar to the display property, conditional processing attributes only affect the direct rendering of elements and do not prevent elements from being successfully referenced by other elements (such as via a use).

In consequence:

Previous versions of SVG included a third conditional processing attribute, requiredFeatures. This was intended to allow authors to provide fallback behavior for user agents that only implemented parts of the SVG specification. Unfortunately, poor specification and implementation of this attribute made it unreliable as a test of feature support.

4.9.2. Definitions

conditional processing attribute
A conditional processing attribute is one that controls whether or not the element on which it appears is processed. Most elements, but not all, may have conditional processing attributes specified on them. See Conditional processing for details. The conditional processing attributes defined in SVG 2 are requiredExtensions and systemLanguage.

4.9.3. The ‘switch’ element

switch
Categories:
Container element, renderable element
Content model:
Any number of the following elements, in any order:a, foreignObject, g, image, svg, switch, text, use
Attributes:
DOM Interfaces:

The switch element evaluates the requiredExtensions and systemLanguage attributes on its direct child elements in order, and then processes and renders the first child for which these attributes evaluate to true. All others will be bypassed and therefore not rendered. If the child element is a container element such as a g, then the entire subtree is either processed/rendered or bypassed/not rendered.

In SVG, when evaluating the systemLanguage attribute, the order of evaluation of descendant elements of the switch element must be as if the 'allowReorder' attribute, defined in the SMIL specification [SMIL] always has a value of 'yes'.

Note that the values of properties display and visibility have no effect on switch element processing. In particular, setting display to none on a child of a switch element has no effect on true/false testing associated with switch element processing.

The switch element does not affect the processing of script and style elements.

For more information and an example, see Embedding foreign object types.

4.9.4. The ‘requiredExtensions’ attribute

The requiredExtensions attribute defines a list of required language extensions. Language extensions are capabilities within a user agent that go beyond the feature set defined in this specification. Each extension is identified by an URL reference.

Name Value Initial value Animatable
requiredExtensions set of space-separated tokens [HTML] (none) no

The value is a list of URL references which identify the required extensions, with the individual values separated by white space. Determines whether all of the named extensions are supported by the user agent. If all of the given extensions are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.

If a given URL reference contains white space within itself, that white space must be escaped.

If the attribute is not present, then it implicitly evaluates to "true". If a null string or empty string value is given to attribute requiredExtensions, the attribute evaluates to "false".

requiredExtensions is often used in conjunction with the switch element. If the requiredExtensions is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

The URL names for the extension should include versioning information, such as "http://example.org/SVGExtensionXYZ/1.0", so that script writers can distinguish between different versions of a given extension.

4.9.5. The ‘systemLanguage’ attribute

Name Value Initial value Animatable
systemLanguage set of comma-separated tokens [HTML] (none) no

The value is a set of comma-separated tokens, each of which must be a Language-Tag value, as defined in BCP 47 [BCP47].

Evaluates to "true" if one of the languages indicated by user preferences exactly equals one of the languages given in the value of this parameter, or if one of the languages indicated by user preferences exactly equals a prefix of one of the languages given in the value of this parameter such that the first tag character following the prefix is "-".

Evaluates to "false" otherwise.

If the attribute is not present, then it implicitly evaluates to "true". If a null string or empty string value is given to attribute systemLanguage, the attribute evaluates to "false".

Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way that it is always true that if a user understands a language with a certain tag, then this user will also understand all languages with tags for which this tag is a prefix.

The prefix rule simply allows the use of prefix tags if this is the case.

Implementation note: When making the choice of linguistic preference available to the user, implementers should take into account the fact that users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may assume that on selecting "en-gb", they will be served any kind of English document if British English is not available. The user interface for setting user preferences should guide the user to add "en" to get the best matching behavior.

Multiple languages may be listed for content that is intended for multiple audiences. For example, content that is presented simultaneously in the original Maori and English versions, would call for:

<text systemLanguage="mi, en"><!-- content goes here --></text>

However, just because multiple languages are present within the object on which the systemLanguage test attribute is placed, this does not mean that it is intended for multiple linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to be used by an English-literate audience. In this case, the systemLanguage test attribute should only include "en".

Authoring note: Authors should realize that if several alternative language objects are enclosed in a switch, and none of them matches, this may lead to situations where no content is displayed. It is thus recommended to include a "catch-all" choice at the end of such a switch which is acceptable in all cases.

systemLanguage is often used in conjunction with the switch element. If the systemLanguage is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

4.10. HTML metadata elements

For user agents that support HTML, the following HTML elements (in the HTML namespace) must be supported in SVG documents:

Note that the base element will affect all URL values in the document, including e.g paint server references.

4.11. Common attributes

4.11.1. Definitions

core attributes
The core attributes are those attributes that can be specified on any SVG element. This includes common attributes, and styling attributes. The core attributes are id, tabindex, lang and xml:space, class and style, and all custom data attributes.

4.11.2. Attributes common to all elements: ‘id’

The id attribute is available on all SVG elements:

Name Value Initial value Animatable
id (see below) (none) no

Must reflect the element's ID [DOM4]. The id attribute must be any value other than the empty string.

4.11.3. The ‘lang’ and ‘xml:lang’ attributes

The ‘lang’ attribute (in no namespace) specifies the primary language for the element's contents and for any of the element's attributes that contain text.

The ‘lang’ attribute in the XML namespace is defined in XML [XML10].

If these attributes are omitted from an element, then the language of this element is the same as the language of its parent element, if any.

The ‘lang’ attribute in the XML namespace may be used on SVG elements in XML documents. If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute in the XML namespace are specified on the same element, they must have exactly the same value when compared in an ASCII case-insensitive manner.

If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute in the XML namespace are set on an element, user agents must use the ‘lang’ attribute in the XML namespace, and the ‘lang’ attribute in no namespace must be ignored for the purposes of determining the element's language.

Name Value Initial value Animatable
lang Language-Tag [ABNF] (none) no

The ‘lang’ attribute specifies the primary language for the element's contents and for any of the element's attributes that contain text. Its value must be a valid BCP 47 language tag, or the empty string. Setting the attribute to the empty string indicates that the primary language is unknown. [BCP47].

4.11.4. The ‘xml:space’ attribute

SVG 2 Requirement: Deprecate the use of ‘xml:space’ to affect text layout and use the ‘white-space’ property instead.
Resolution: We drop xml:space from SVG 2 and remove the relating tests from the SVG 1.1. test suite.
Purpose: To align with CSS.
Owner: Chris (ACTION-3004, done; and ACTION-3005, done)
Status Done.
Name Value Initial value Animatable
xml:space (see below) default no

Deprecated XML attribute to specify whether white space is preserved in character data. The only possible values are the strings 'default' and 'preserve', without white space. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10] and to the discussion white space handling in SVG.

New content should use the white-space property instead.

4.11.5. The ‘tabindex’ attribute

Name Value Initial value Animatable
tabindex valid integer [HTML] (none) no

This content attribute allows authors to control whether an element is focusable, whether it is supposed to be reachable using sequential focus navigation, and what is to be the relative order of the element for the purposes of sequential focus navigation.

The name "tab index" comes from the common use of the "tab" key to navigate through the focusable elements. The term "tabbing" refers to moving forward through the focusable elements that can be reached using sequential focus navigation.

4.11.6. The ‘data-*’ attributes

All SVG elements support custom data attributes, which are those in no namespace whose names begin with the string "data-". See the requirements for custom data attributes in the HTML specification.

4.12. WAI-ARIA attributes

4.12.1. Definitions

ARIA attributes
These are the attributes defined in WAI-ARIA, consisting of WAI-ARIA states and properties as well as the role attribute. See the WAI-ARIA Definition of Roles, the WAI-ARIA Graphics Module Graphics Roles, and the WAI-ARIA Supported States and Properties. The aria attributes are aria-activedescendant, role, aria-autocomplete, aria-busy, aria-checked, aria-colcount, aria-colindex, aria-colspan, aria-controls, aria-current, aria-describedby, aria-details, aria-disabled, aria-dropeffect, aria-errormessage, aria-expanded, aria-flowto, aria-grabbed, aria-haspopup, aria-hidden, aria-invalid, aria-label, aria-labelledby, aria-level, aria-atomic, aria-modal, aria-multiline, aria-multiselectable, aria-orientation, aria-owns, aria-placeholder, aria-posinset, aria-pressed, aria-readonly, aria-relevant, aria-required, aria-roledescription, aria-rowcount, aria-rowindex, aria-rowspan, aria-selected, aria-setsize, aria-sort, aria-valuemax, aria-valuemin, aria-valuenow, aria-valuetext and aria-live.

Note that the above list of ARIA attributes may be expanded by future WAI-ARIA specifications.

4.12.2. Role attribute

Any renderable element may have an ARIA role attribute specified; the role attribute is ignored on non-rendered elements. The attribute, if specified, must have a value that is a set of space-separated tokens representing the various WAI-ARIA roles that the element belongs to. These tokens are role values defined in Definition of Roles ([ARIA], section 5.4) and Graphics Roles ([ARIA-GRAPHICS], section 4).

The WAI-ARIA role that an SVG element has assigned to it is the first valid role found in the list of tokens generated when the role attribute is split on spaces. A valid role is a recognized, non-abstract role that is allowed for the element type.

Name Value Initial value Animatable
role set of space-separated tokens [HTML] (see below) no

The role attribute must be a set of space-separated tokens having values defined in Definition of Roles ([ARIA], section 5.4).

The role value is a set of white-space separated machine-extractable semantic information used to define the purpose of the element.

The initial value for the role attribute, for each SVG element, is the corresponding default implied ARIA semantic for SVG elements.

To be valid and useful, many element roles require additional information to be provided in the form of an accessible name or explicit state and property values. Accessible names may be provided using SVG descriptive elements or ARIA attributes. The requirements for each role are indicated where the role is defined, e.g., in WAI-ARIA ([ARIA]) or the WAI-ARIA Graphics Module ([ARIA-GRAPHICS]).

4.12.3. State and property attributes (all aria- attributes)

WAI-ARIA state and property attributes may be specified on SVG elements. These attributes are defined by ARIA in Definitions of States and Properties (all aria-* attributes) ([ARIA], section 6.6).

These attributes, if specified, must have a value that is the WAI-ARIA value type in the "Value" field of the definition for the state or property, mapped to the appropriate SVG value type according to Mapping WAI-ARIA Value types to languages using the SVG mapping ([ARIA], section 10.2).

WAI-ARIA State and Property attributes can be used on any element. They are not always meaningful, however, and in such cases user agents might not perform any processing aside from including them in the DOM. State and property attributes are processed according to the ARIA and SVG Accessibility API Mappings specification specifications. [ARIA] [SVG-AAM]

4.12.4. Implicit and Allowed ARIA Semantics

The following table defines the default implicit ARIA semantics that apply to SVG elements. Each language feature (element) in a cell in the first column implies the ARIA semantics (role, states, and/or properties) given in the cell in the second column of the same row. The third column defines restrictions as to what WAI-ARIA semantic (role, state, or property) may or may not apply.

For many graphics elements, an implicit role is only assigned if the author provides information that indicates semantic importance. The complete inclusion criteria for the accessibility tree are defined by the SVG Accessibility API Mappings specification for user agents [SVG-AAM]. For authors, the preferred means of indicating semantic importance is to provide an accessible name for the element. This can be done through a direct child title element, or through the aria-label or aria-labelledby attributes. Authors should use one of these methods to provide an accessible name for any content that is essential to the comprehension of the SVG, and especially for any interactive content.

Language feature Default implied ARIA semantics Allowed roles
a link role if the element has a valid href or xlink:href attribute. For a elements that are not links, the default semantics are the same as tspan if the a element is a descendent of text, or the same as g otherwise. no restrictions
audio platform-specific role mappings, as defined in the HTML Accessibility API Mappings specification If specified, role must be application
canvas platform-specific role mappings, as defined in the HTML Accessibility API Mappings specification no restrictions
circle graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
clipPath none no role may be applied
cursor none no role may be applied
defs none no role may be applied
desc none no role may be applied
ellipse graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
feBlend none no role may be applied
feColorMatrix none no role may be applied
feComponentTransfer none no role may be applied
feComposite none no role may be applied
feConvolveMatrix none no role may be applied
feDiffuseLighting none no role may be applied
feDisplacementMap none no role may be applied
feDistantLight none no role may be applied
feDropShadow none no role may be applied
feFlood none no role may be applied
feFuncA none no role may be applied
feFuncB none no role may be applied
feFuncG none no role may be applied
feFuncR none no role may be applied
feGaussianBlur none no role may be applied
feImage none no role may be applied
feMerge none no role may be applied
feMergeNode none no role may be applied
feMorphology none no role may be applied
feOffset none no role may be applied
fePointLight none no role may be applied
feSpecularLighting none no role may be applied
feSpotLight none no role may be applied
feTile none no role may be applied
feTurbulence none no role may be applied
filter none no role may be applied
foreignObject group role if the element meets the inclusion criteria, otherwise none no restrictions
g group role if the element meets the inclusion criteria, otherwise none no restrictions
hatch none no role may be applied
hatchpath none no role may be applied
iframe platform-specific role mappings, as defined in the HTML Accessibility API Mappings specification If Specified, role must be either application, document, or img roles
image img role no restrictions
line graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
linearGradient none no role may be applied
marker none no role may be applied
mask none no role may be applied
mesh img role if the element meets the inclusion criteria, otherwise none no restrictions
meshgradient none no role may be applied
meshpatch none no role may be applied
meshrow none no role may be applied
metadata none no role may be applied
mpath none no role may be applied
path graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
pattern none no role may be applied
polygon graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
polyline graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
radialGradient none no role may be applied
rect graphics-symbol role if the element meets the inclusion criteria, otherwise none no restrictions
script none no role may be applied
solidcolor none no role may be applied
stop none no role may be applied
style none no role may be applied
svg graphics-document role no restrictions
switch none no role may be applied
symbol graphics-object role if the element is a rendered element instance that meets the inclusion criteria, otherwise none no restrictions
text grouprole, with platform-specific role mappings, as defined in the SVG Accessibility API Mappings specification no restrictions
textPath group role if the element meets the inclusion criteria, otherwise none no restrictions
title none no role may be applied
tspan group role if the element meets the inclusion criteria, otherwise none no restrictions
use graphics-object role if the element meets the inclusion criteria, otherwise none no restrictions
video platform-specific role mappings, as defined in the HTML Accessibility API Mappings specification If specified, role must be application
view none no role may be applied

4.13. DOM interfaces

4.13.1. Extensions to the Document interface

The DOM Core specification defines a Document interface, which this specification extends.

In the case where an SVG document is embedded by reference, such as when an HTML document has an ‘object’ element whose ‘data’ attribute references an SVG document (i.e., a document whose MIME type is "image/svg+xml" and whose root element is thus an svg element), there will exist two distinct DOM hierarchies. The first DOM hierarchy will be for the referencing document (e.g., an XHTML document). The second DOM hierarchy will be for the referenced SVG document.

partial interface Document {
  readonly attribute SVGSVGElement rootElement;
};

The rootElement IDL attribute represents the root svg element. On getting rootElement, the root element of the document is returned, if it is an svg element, or null otherwise.

This attribute is deprecated, and may be removed in a future SVG specification. Authors are encouraged to use the documentElement attribute on Document instead.

SVG implementations that implement HTML must support the HTML extensions to the document interface. Other SVG implementations must support the following IDL fragment.

// must only be implemented in certain implementations
partial interface Document {
  readonly attribute DOMString title;
  readonly attribute DOMString referrer;
  readonly attribute DOMString domain;
  readonly attribute Element? activeElement;
};

The title, referrer, domain and activeElement IDL attributes must behave the same as the corresponding IDL attributes defined in HTML.

4.13.2. Interface SVGSVGElement

An SVGSVGElement object represents an svg element in the DOM. The SVGSVGElement interface also contains miscellaneous utility methods, such as data type object factory methods.

An SVGSVGElement object maintains an internal DOMPoint object, called its current translate point object, which is the object returned from the currentTranslate IDL attribute.

interface SVGSVGElement : SVGGraphicsElement {

  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;

  attribute float currentScale;
  [SameObject] readonly attribute DOMPointReadOnly currentTranslate;

  NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement? referenceElement);
  NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement? referenceElement);
  boolean checkIntersection(SVGElement element, DOMRectReadOnly rect);
  boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect);

  void deselectAll();

  SVGNumber createSVGNumber();
  SVGLength createSVGLength();
  SVGAngle createSVGAngle();
  DOMPoint createSVGPoint();
  DOMMatrix createSVGMatrix();
  DOMRect createSVGRect();
  SVGTransform createSVGTransform();
  SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix);

  Element getElementById(DOMString elementId);

  // Deprecated methods that have no effect when called,
  // but which are kept for compatibility reasons.
  unsigned long suspendRedraw(unsigned long maxWaitMilliseconds);
  void unsuspendRedraw(unsigned long suspendHandleID);
  void unsuspendRedrawAll();
  void forceRedraw();
};

SVGSVGElement implements SVGFitToViewBox;
SVGSVGElement implements SVGZoomAndPan;
SVGSVGElement implements WindowEventHandlers;

The x, y, width and height IDL attributes reflect the computed values of the x, y, width and height properties and their corresponding presentation attributes, respectively.

The currentScale and currentTranslate IDL attributes represent the transform applied to the document in response to user magnification and panning operations, as described under Magnification and panning.

The document's magnification and panning transform is a 2x3 matrix of the form [currentScale 0 0 currentScale currentTranslate.x currentTranslate.y]. The value of the transform property does not affect currentScale or currentTranslate.

On getting currentScale, the following steps are run:

  1. If the current svg element is not the outermost svg element, then return 1.
  2. Let [a b c d e f] be the 2x3 matrix that represents the document's magnification and panning transform.
  3. Return a.

On setting currentScale, the following steps are run:

  1. If the current svg element is not the outermost svg element, then return.
  2. Let scale be the value being assigned to currentScale.
  3. Let [a b c d e f] be the 2x3 matrix that represents the document's magnification and panning transform.
  4. Set the document's magnification and panning transform to [scale 0 0 scale e f].

On getting currentTranslate, the SVGSVGElement object's current translate point object is returned. This object represents the current translation for the svg element. A current translate point object must be read only when its svg element is not the outermost svg element, and writable otherwise.

See the rules for assigning to a DOMPoint for how modifying the current translate point object affects the document's magnification and panning transform.

Whenever the document's magnification and panning transform changes in response to user interaction or whenever the outermost svg element changes, the following steps are run:

  1. Let [a b c d e f] be the 2x3 matrix that represents the document's magnification and panning transform.
  2. Let element be the outermost svg element.
  3. Update the x and y components of element's current translate point object to e and f, respectively.

Running these steps when the outermost svg element changes will ensure that if the document element is replaced with a different svg element, that its currentTranslate will be immediately updated to reflect the translation component of the document's magnification and panning transform.

Whenever an svg element is no longer outermost svg element, the x and y components of its current translate point object must be set to 0.

Note that the value of the zoomAndPan attribute on the outermost svg element only controls whether the document's magnification and panning transform can be updated through user interaction. Regardless of the value of that attribute, the current scale and translation can be changed by modifying currentScale and currentTranslate.

The suspendRedraw, unsuspendRedraw, unsuspendRedrawAll and forceRedraw methods are all deprecated and defined to have no effect. When the suspendRedraw method is called, it must return 1.

The getIntersectionList, getEnclosureList, checkIntersection and checkEnclosure methods are used to perform geometry operations on graphics elements to find those whose (or check whether their) graphical content lies partially or completely within a given rectangle.

To find the intersecting or enclosed descendants of a given element element with a given rectangle rectangle using ancestor as the element in whose coordinate space rectangle is to be interpreted, the following steps are run:

  1. Let result be an initially empty list.
  2. If element is not displayed, due to having a display value of none or being in a subtree that has failing conditional processing attributes or a failing branch of a switch, then return result.
  3. For each child element child of element, in document order:
    1. If child is an svg or g element, then:
      1. Let descendants be the result of finding the intersecting (or enclosed) descendants of child with rectangle in ancestor's coordinate space.
      2. Append to result all the elements of descendants.
    2. Otherwise, if child is a use element, then:
      1. Let root be the root of the child's shadow tree.
      2. Let descendants be the result of finding the intersecting (or enclosed) descendants of root with rectangle in ancestor's coordinate space.
      3. If descendants is not empty, then append child to result.

        This means that although we look at the the elements in the use-element shadow tree, we don't place the element instances or their corresponding element in the result list; only the use element itself is returned.

    3. Otherwise, if child is a graphics element, then:
      1. Let region be the shape in child's coordinate system that is sensitive to hit detection, taking into account the rules for interpreting child's pointer-events value.
      2. Transform region into ancestor's coordinate system.
      3. If we are finding intersecting descendants and region lies partially or fully within rectangle, then append child to result.
      4. Otherwise, we are finding enclosed descendants. If region lies fully within rectangle, then append child to result.
  4. Return result.

To find the non-container graphics elements within a given element element, the following steps are run:

  1. Let result be an initially empty list.
  2. If element is an svg or g element, then for each child element child of element, in document order:
    1. Let descendants be the result of finding the non-container graphics elements within child.
    2. Append to result all the elements of descendants.
  3. Otherwise, if element is a graphics element then append element to result.
  4. Return result.

When getIntersectionList(rect, referenceElement) or getEnclosureList(rect, referenceElement) is called, the following steps are run:

  1. Let descendants be a list, depending on what method we are in:
    getIntersectionList
    descendants is the result of finding the intersecting descendants of the current svg element with rectangle rect in the current svg element's coordinate system.
    getEnclosureList
    descendants is the result of finding the enclosed descendants of the current svg element with rectangle rect in the current svg element's coordinate system.
  2. If referenceElement is not null, then remove from descendants any element that does not have referenceElement as an ancestor.
  3. Return a static NodeList that contains all of the elements in descendants. ([DOM4], section 5.2.7)

When checkIntersection(element, rect) or checkEnclosure(element, rect) is called, the following steps are run:

  1. Let descendants be a list, depending on what method we are in:
    getIntersectionList
    descendants is the result of finding the intersecting descendants of the current svg element with rectangle rect in the current svg element's coordinate system.
    getEnclosureList
    descendants is the result of finding the enclosed descendants of the current svg element with rectangle rect in the current svg element's coordinate system.
  2. Let elements be the result of finding the non-container graphics elements within element.
  3. If elements is empty, then return false.
  4. If any element in elements is not also in descendants, then return false.
  5. Return true.

The deselectAll method is used to remove any selections from the document. When deselectAll() is called, all ranges from the document's selection are removed and the selection's direction is set to forwards. [DOM4][EDITING] This method is deprecated, as it duplicates functionality from the Selection API.

This is equivalent to calling document.getSelection().removeAllRanges() on the document that this svg element is in.

The createSVGNumber, createSVGLength, createSVGAngle, createSVGPoint, createSVGMatrix, createSVGRect and createSVGTransform methods are all factory functions used to create a new datatype object of a particular type. When one of these methods is called, a new object is returned according to the following table:

MethodObject and details
createSVGNumberA new, detached SVGNumber object whose value is 0.
createSVGLengthA new, detached SVGLength object whose value is the unitless <number> 0.
createSVGAngleA new, detached SVGAngle object whose value is the unitless <number> 0.
createSVGPointA new, detached DOMPoint object whose coordinates are all 0.
createSVGMatrixA new, detached DOMMatrix object representing the identity matrix.
createSVGRectA new, DOMRect object whose x, y, width and height are all 0.
createSVGTransformA new, detached SVGTransform object whose value is matrix(1, 0, 0, 1, 0, 0).

The createSVGPoint, createSVGMatrix and createSVGRect methods are all deprecated and kept only for compatibility with legacy content. Authors are encouraged to use the DOMPoint, DOMMatrix and DOMRect constructors instead.

The createSVGTransformFromMatrix method is used to create a new SVGTransform object from a matrix object. Its behavior is the same as the createSVGTransformFromMatrix method on SVGTransformList.

The getElementById method, must return the first element in tree order, within the svg element's descendants, whose ID is elementId, or null if there is no such element.

4.13.3. Interface SVGGElement

An SVGGElement object represents a g element in the DOM.

interface SVGGElement : SVGGraphicsElement {
};

4.13.4. Interface SVGUnknownElement

An SVGUnknownElement object represents an unknown element in the SVG namespace.

interface SVGUnknownElement : SVGGraphicsElement {
};

4.13.5. Interface SVGDefsElement

An SVGDefsElement object represents a defs element in the DOM.

interface SVGDefsElement : SVGGraphicsElement {
};

4.13.6. Interface SVGDescElement

An SVGDescElement object represents a desc element in the DOM.

interface SVGDescElement : SVGElement {
};

4.13.7. Interface SVGMetadataElement

An SVGMetadataElement object represents a metadata element in the DOM.

interface SVGMetadataElement : SVGElement {
};

4.13.8. Interface SVGTitleElement

An SVGTitleElement object represents a title element in the DOM.

interface SVGTitleElement : SVGElement {
};

4.13.9. Interface SVGSymbolElement

An SVGSymbolElement object represents a symbol element in the DOM.

interface SVGSymbolElement : SVGGraphicsElement {
};

SVGSymbolElement implements SVGFitToViewBox;

New in SVG 2. The SVGSymbolElement interface now inherits from SVGGraphicsElement, so that the instantiated symbol in the shadow DOM can be queried as a graphics element.

4.13.10. Interface SVGUseElement

An SVGUseElement object represents a use element in the DOM.

interface SVGUseElement : SVGGraphicsElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
  [SameObject] readonly attribute SVGElement? instanceRoot;
  [SameObject] readonly attribute SVGElement? animatedInstanceRoot;
};

SVGUseElement implements SVGURIReference;

The x, y, width and height IDL attributes reflect the computed values of the x, y, width and height properties and their corresponding presentation attributes, respectively.

The instanceRoot and animatedInstanceRoot IDL attributes both point to the instance root, the SVGElementInstance that is a direct child of this element's shadow root (u.instanceRoot is equivalent to getting u.shadowRoot.firstChild). If this element does not have a shadow tree (for example, because its URI is invalid or because it has been disabled by conditional processing), then getting these attributes returns null.

4.13.11. Interface SVGUseElementShadowRoot

The root object of each use-element shadow tree implements the SVGUseElementShadowRoot interface. This interface does not currently define any extensions to the properties and methods defined for the ShadowRoot interface and DocumentOrShadowRoot mixin. However, the tree rooted at this node is entirely read-only from the perspective of author scripts.

interface SVGElementInstance : ShadowRoot {

};

4.13.12. Interface SVGElementInstance

The SVGElementInstance interface defines extensions to the SVGElement interface, which are only used for elements in a use-element shadow tree.

In previous versions of SVG, SVG element instances were defined as non-element objects that were valid event targets but not full DOM nodes. This specification re-defines the use-element shadow tree to be consistent with the Shadow DOM specification, which means that instances are actual SVGElement objects. This interface adds the missing functionality for backwards compatibility. However, authors should be aware that compatibility is not perfect, and design their scripts accordingly. Also note that these properties will not be available on HTML-namespaced element objects in the shadow tree.

[NoInterfaceObject]
interface SVGElementInstance {
  [SameObject] readonly attribute SVGElement? correspondingElement;
  [SameObject] readonly attribute SVGUseElement? correspondingUseElement;
};

The correspondingElement IDL attribute points to the corresponding element if this element is an element instance in a use-element shadow tree, or is null otherwise.

When the referenced element is in an external file, the presence of this pointer implies that the entire DOM of the external file must be maintained in memory. However, as currently specified, the external DOM is read-only. It therefore offers limited functionality and a potentially large performance impact. Pending feedback from implementers, authors should consider the use of correspondingElement with external file references to be at-risk.

The correspondingUseElement IDL attribute points to the corresponding use element if this element is an element instance in a use-element shadow tree, or is null otherwise.

4.13.13. Interface ShadowAnimation

The ShadowAnimation inteface defines a read-only Animation object, which mirrors all changes to the sourceAnimation object from which it was constructed. They are used to mirror author-initiated animation objects in the use-element shadow tree.

[Constructor (Animation source, Animatable newTarget) ]
interface ShadowAnimation : Animation {
  [SameObject] readonly attribute Animation sourceAnimation;
};

The sourceAnimation IDL property points to the Animation object passed in the constructor.

The constructor generates a new ShadowAnimation object, which reflects all properties on the sourceAnimation, except that its effect is created by constructing a new KeyframeEffectReadOnly using the keyframe effect of the sourceAnimation as its source, and then modifying its target to match the newTarget parameter.

A ShadowAnimation is read-only. Any attempt to set any of the inherited IDL properties, or call any of the Animation methods that change its state, must throw a NoModificationAllowedError. However, the user agent must ensure that any changes to the properties or state of the sourceAnimation are reflected in changes to the ShadowAnimation.

4.13.14. Interface SVGSwitchElement

An SVGSwitchElement object represents a switch element in the DOM.

interface SVGSwitchElement : SVGGraphicsElement {
};

4.13.15. Interface GetSVGDocument

This interface provides access to an SVG document embedded by reference in another DOM-based language. The expectation is that the interface is implemented on DOM objects that allow such SVG document references.

This interface is deprecated and may be dropped from future versions of the SVG specification. To access the SVG document inside an ‘iframe’ or ‘object’ element, authors are suggested to use the contentDocument attribute on the HTMLIFrameElement or HTMLObjectElement interface, respectively.

The HTMLIFrameElement, HTMLEmbedElement and HTMLObjectElement interfaces all define their own getSVGDocument method, which provides access to the SVG document in the same way that the GetSVGDocument does. Those three interfaces therefore do not need to implement GetSVGDocument. Still, authors are strongly recommended to use contentDocument instead.

[NoInterfaceObject]
interface GetSVGDocument {
  Document getSVGDocument();
};

The getSVGDocument method is used to return a referenced SVG document. When getSVGDocument() is called, it must return the Document object referenced by the embedding element that implements the GetSVGDocument interface; if there is no document, null is returned.

Note that this does no check to see whether the referenced document is indeed an SVG document. Instead, any document is returned.

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 5: Styling

5.1. Styling SVG content using CSS

Elements in an SVG document can be styled using CSS. Most visual characteristics and some aspects of element geometry are controlled using CSS properties. For example, the fill property controls the paint used to fill the inside of a shape, and the width and height properties are used to control the size of a rect element.

SVG user agents must support all of the CSS styling mechanisms described in this chapter.

In SVG 1.1, support for inline style sheets using the style element and style was not required. In SVG 2, these are required.

5.2. Inline style sheets: the ‘style’ element

SVG 2 Requirement: Add HTML5 ‘style’ element attributes to SVG's style element.
Resolution: SVG 2 ‘style’ element shall be aligned with the HTML5 ‘style’ element.
Purpose: To not surprise authors with different behavior for the ‘style’ element in HTML and SVG content.
Owner: Cameron (ACTION-3277)

The style element allows style sheets to be embedded directly within SVG content. SVG's style element has the same attributes as the corresponding element in HTML.

style
Categories:
Never-rendered element
Content model:
Character data.
Attributes:
DOM Interfaces:

Attribute definitions:

Name Value Initial value Animatable
type (see below) text/css no

This attribute specifies the style sheet language of the element's contents, as a media type. [RFC2046]. If the attribute is not specified, then the style sheet language is assumed to be CSS.

Name Value Initial value Animatable
media (see below) all no

This attribute specifies a media query that must be matched for the style sheet to apply. Its value is parsed as a media_query_list. If not specified, the style sheet applies unconditionally.

Name Value Initial value Animatable
title (see below) (none) no

This attribute specifies a title for the style sheet, which is used when exposing and selecting between alternate style sheets. The attribute takes any value.

The semantics and processing of a style and its attributes must be the same as is defined for the HTML ‘style’ element.

The style sheet's text content is never directly rendered; the display value for the style element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.

5.3. External style sheets: the effect of the HTML ‘link’ element

An HTML ‘link’ element in an SVG document (that is, an element in the HTML namespace with local name "link") with its ‘rel’ attribute set to 'stylesheet' must be processed as defined in the HTML specification and cause external style sheets to be loaded and applied to the document. Such elements in HTML documents outside of an inline SVG fragment must also apply to the SVG content.

Because the element is required to be in the HTML namespace, it is not possible for an HTML ‘link’ element to be parsed as part of an inline SVG fragment in a text/html document. However, when parsing an SVG document using XML syntax, XML namespace declarations can be used to place the element in the HTML namespace.

Note that an alternative way to reference external style sheets without using the HTML ‘link’ element is to use an @import rule in an inline style sheet. For example:

<svg xmlns="http://www.w3.org/2000/svg">
  <style>
    @import url(mystyles.css);
  </style>
  <rect .../>
</svg>

would behave similarly to:

<svg xmlns="http://www.w3.org/2000/svg">
  <link xmlns="http://www.w3.org/1999/xhtml" rel="stylesheet" href="mystyles.css" type="text/css"/>
  <rect .../>
</svg>

Or, in XML documents, external CSS style sheets may be included using the <?xml-stylesheet?> processing instruction [XML-SS].

5.4. Style sheets in HTML documents

When an SVG style or an HTML ‘style’ element is used in an HTML document, those style sheets must apply to all HTML and inline SVG content in the document. Similarly, any HTML ‘style’ element used in an SVG document must also apply its style sheet to the document.

5.5. Element-specific styling: the ‘class’ and ‘style’ attributes

As with HTML, SVG supports the class and style attributes on all elements to support element-specific styling.

Attribute definitions:

Name Value Initial value Animatable
class set of space-separated tokens [HTML] (none) yes

The class attribute assigns one or more class names to an element, which can then be used for addressing by the styling language.

Name Value Initial value Animatable
style (see below) (none) no

The style attribute is used to supply a CSS declaration of an element. The attribute is parsed as a declaration-list.

Aside from the way that the class attribute is reflected in the SVG DOM (in the className IDL attribute on SVGElement), the semantics and behavior of the class and style attributes must be the same as that for the corresponding attributes in HTML.

In the following example, the text element is used in conjunction with the class attribute to markup document messages. Messages appear in both English and French versions.

<!-- English messages -->
<text class="info" lang="en">Variable declared twice</text>
<text class="warning" lang="en">Undeclared variable</text>
<text class="error" lang="en">Bad syntax for variable name</text>
<!-- French messages -->
<text class="info" lang="fr">Variable déclarée deux fois</text>
<text class="warning" lang="fr">Variable indéfinie</text>
<text class="error" lang="fr">Erreur de syntaxe pour variable</text>

The following CSS style rules would tell visual user agents to display informational messages in green, warning messages in yellow, and error messages in red:

text.info    { fill: green; }
text.warning { fill: yellow; }
text.error   { fill: red; }

This example shows how the style attribute can be used to style text elements similarly to the previous example:

<text style="fill: green;" lang="en">Variable declared twice</text>
<text style="fill: yellow;" lang="en">Undeclared variable</text>
<text style="fill: red;" lang="en">Bad syntax for variable name</text>

5.6. Presentation attributes

Some styling properties can be specified not only in style sheets and style attributes, but also in presentation attributes. These are attributes whose name matches (or is similar to) a given CSS property and whose value is parsed as a value of that property. Presentation attributes contribute to the author level of the cascade, following all other author-level style sheets, and have specificity 0.

Since presentation attributes are parsed as CSS values, an !important declaration within a presentation attribute will cause it to have an invalid value. See Attribute syntax for details on how presentation attributes are parsed.

Not all properties supported by an implementation have a corresponding presentation attribute. Attributes of the same name on other elements must not be parsed as a presentation attribute and will not affect CSS cascading and inheritance. Also, only elements in the SVG namespace support presentation attributes. Presentation attributes may be set on any element where there is not a name clash with an existing attribute or property.

Properties with a presentation attribute Elements that support the presentation attribute
cx, cy circle and ellipse
height, width, x, y foreignObject, image, mask, rect and svg
r circle
rx, ry ellipse and rect
d path and textPath
alignment-baseline, baseline-shift, clip, clip-path, clip-rule, color, color-interpolation, color-interpolation-filters, color-rendering, cursor, direction, display, dominant-baseline, fill, fill-opacity, fill-rule, filter, flood-color, flood-opacity, font-family, font-size, font-size-adjust, font-stretch, font-style, font-variant, font-weight, glyph-orientation-horizontal, glyph-orientation-vertical, image-rendering, letter-spacing, lighting-color, marker-end, marker-mid, marker-start, mask, opacity, overflow, pointer-events, shape-rendering, solid-color, solid-opacity, stop-color, stop-opacity, stroke, stroke-dasharray, stroke-dashoffset, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-opacity, stroke-width, text-anchor, text-decoration, text-overflow, text-rendering, transform, unicode-bidi, vector-effect, visibility, white-space, word-spacing, writing-mode Any element in the SVG namespace.

Since presentation attributes are only available on elements in the SVG namespace, an HTML video element is classified as a graphics element, for example, but does not support any presentation attributes.

Note that ‘x’, ‘y’, ‘width’ and ‘height’ attributes are not always presentation attributes. For example, the x attribute on text and tspan is not a presentation attribute for the x property.

The following table lists the presentation attributes whose names are different from their corresponding property. All other presentation attributes have names that do match their property.

PropertyElementPresentation attribute name
transformlinearGradient and radialGradient‘gradientTransform’
transformpattern‘patternTransform’

In the future, any new properties that apply to SVG content will not gain presentation attributes. Therefore, authors are suggested to use styling properties, either through inline style properties or style sheets, rather than presentation attributes, for styling SVG content.

Animation of presentation attributes is equivalent to animating the corresponding property.

5.7. Required properties

The following properties must be supported by all SVG user agents:

5.8. User agent style sheet

The following user agent style sheet must be applied in all SVG user agents.

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

svg:not(:root), hatch, image, marker, pattern, symbol { overflow: hidden; }

*:not(svg),
*:not(foreignObject) > svg {
  transform-origin: 0 0;
}

*[xml|space=preserve] {
  text-space-collapse: preserve-spaces;
}

defs, 
clipPath, mask, marker, 
desc, title, metadata, 
pattern, hatch,
linearGradient, radialGradient, meshGradient, 
script, style,
symbol {
  display: none !important;
}
:host(use) > symbol {
  display: inline !important;
}

An !important rule in a user agent stylesheet over-rides all user and author styles [css-cascade-4]. The display value for never-rendered elements and for symbol elements can therefore not be changed. A symbol must only be rendered if it is the direct child of a shadow root whose host is a use element (and must always be rendered if the host use element is rendered). The other elements, and their child content, are never rendered directly.

CSS Transforms defines that the initial value for transform-origin is 50% 50%. Since elements in SVG must, by default, transform around their origin at (0, 0), transform-origin is overridden and set to a default value of 0 0 for all SVG elements (except for root svg elements and svg elements that are the child of a foreignObject element or an element in a non-SVG namespace; these elements must transform around their center). [CSS3TRANSFORMS]

5.9. Required CSS features

Besides the features described above, the following CSS features must be also supported in SVG user agents:

5.10. DOM interfaces

5.10.1. Interface SVGStyleElement

An SVGStyleElement object represents a style element in the DOM.

interface SVGStyleElement : SVGElement {
  attribute DOMString type;
  attribute DOMString media;
  attribute DOMString title;
};

SVGStyleElement implements LinkStyle;

The type, media and title IDL attributes reflect the type, media and title content attributes, respectively.

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 6: Geometry Properties

Beside SVG's styling properties, SVG also defines geometry properties. Geometry properties describe the position and dimension of the graphics elements circle, ellipse, rect, image, foreignObject and the svg element.

6.1. Horizontal center coordinate: The ‘cx’ property

Name: cx
Value: <length> | <percentage>
Initial: 0
Applies to: circle and ellipse
Inherited: no
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

The cx property describes the horizontal center coordinate of the position of the element.

6.2. Vertical center coordinate: The ‘cy’ property

Name: cy
Value: <length> | <percentage>
Initial: 0
Applies to: circle and ellipse
Inherited: no
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

The cy property describes the vertical center coordinate of the position of the element.

6.3. Radius: The ‘r’ property

Name: r
Value: <length> | <percentage>
Initial: 0
Applies to: circle
Inherited: no
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

The r property describes the radius of the circle element.

A negative value for r must be treated as an illegal value.

6.4. Horizontal radius: The ‘rx’ property

Name: rx
Value: <length> | <percentage> | auto
Initial: auto
Applies to: ellipse, rect
Inherited: no
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

The rx property describes the horizontal radius of the ellipse element and the curve radius of the rect element. When the computed value of ‘rx’ is auto, the used radius is equal to the absolute length used for ry, creating a circular arc. If both ‘rx’ and ‘ry’ have a computed value of auto, the used value is 0.

Regardless of how the value is calculated, the used value of ‘rx’ for a rect is never more than 50% of the used value of width for the same shape.

The auto behavior is new in SVG 2 for ellipse, matching the behavior for rect elements when rx was not specified.

A negative value for rx must be treated as an illegal value.

6.5. Vertical radius: The ‘ry’ property

Name: ry
Value: <length> | <percentage> | auto
Initial: auto
Applies to: ellipse, rect
Inherited: no
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

The ry property describes the vertical radius of the ellipse element and the vertical curve radius of the rect element. When the computed value of ‘ry’ is auto, the used radius is equal to the absolute length used for rx, creating a circular arc. If both ‘rx’ and ‘ry’ have a computed value of auto, the used value is 0.

Regardless of how the value is calculated, the used value of ‘ry’ for a rect is never more than 50% of the used value of height for the same shape.

The auto behavior is new in SVG 2 for ellipse, matching the behavior for rect elements when ry was not specified.

A negative value for ry must be treated as an illegal value.

6.6. Horizontal coordinate: The ‘x’ property

Name: x
Value: <length> | <percentage>
Initial: 0
Applies to: svg, rect, image, foreignObject
Inherited: no
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

The x property describes the horizontal coordinate of the position of the element.

6.7. Vertical coordinate: The ‘y’ property

Name: y
Value: <length> | <percentage>
Initial: 0
Applies to: svg, rect, image, foreignObject
Inherited: no
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

The y property describes the vertical coordinate of the position of the element.

6.8. Sizing properties: the effect of the ‘width’ and ‘height’ properties

See the CSS 2.1 specification for the definitions of width and height.

The CSS width and height properties are used for sizing some SVG elements. Specifically, they are used to size rect, svg, image and foreignObject. All of these elements have ‘width’ and ‘height’ presentation attributes.

The value auto for width and height on the svg element is treated as 100%.

The value auto for width and height on the image element is calculated from the referenced image's intrinsic dimensions and aspect ratio, according to the CSS default sizing algorithm.

New in SVG 2. Images embedded in SVG can now be auto-sized to the intrinsic size, or scaled to a fixed height or width according to the intrinsic aspect ratio. This matches the behavior of embedded images in HTML.

The value auto for width and height on other elements is treated as 0.

This means that, for example, a foreignObject object element will not shrink-wrap to its contents if auto is used.

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 7: Coordinate Systems, Transformations and Units

7.1. Introduction

All SVG content is drawn inside SVG viewports. Every SVG viewport defines a drawing region characterized by a size (width, height), and an origin, measured in abstract user units.

Note that the term SVG viewport is distinct from the "viewport" term used in CSS.

The initial viewport is a top-level SVG viewport that establishes a mapping between the coordinate system used by the containing environment (for example, CSS pixels in web browsers) and user units. Establishing an initial viewport is described in more detail in The initial viewport.

SVG viewports are only established by elements. See Establishing a new SVG viewport for information on which elements generate viewports.

Each SVG viewport generates a viewport coordinate system and a local coordinate system, initially identical. Providing a viewBox on a viewport's element transforms the local coordinate system relative to the viewport coordinate system as described in The viewBox attribute. Child elements of a viewport can further modify the local coordinate system, for example by specifying the transform property.

SVG viewports can be nested. Percentage units are resolved with reference to the width and height of the nearest ancestral SVG viewport. Hence, nesting SVG viewports provides an opportunity to redefine the meaning of percentage units and provide a new reference rectangle for "fitting" a graphic relative to a particular rectangular area.

The width, height and origin of SVG viewports is established by a negotiation process between the SVG document fragment generating the SVG viewport, and the parent of that fragment (whether real or implicit). See Establishing a new SVG viewport for a description of this negotiation process.

By default, a nested SVG viewport's viewport coordinate system is equivalent to the local coordinate system of the parent element, translated by the origin of the SVG viewport's element. However, a transform property on an SVG viewport's element will modify the viewport coordinate system relative to the parent element's local coordinate system.

Abstractly, all SVG viewports are embedded in the canvas, a drawing region that is infinitely large in all relevant dimensions.

7.2. Computing the equivalent transform of an SVG viewport

This process converts the min-x, min-y, width and height values of a viewBox attribute, the position and size of the element on which the viewBox attribute is defined, and the value of the preserveAspectRatio attribute on that element into a translation and a scale that is applied to content contained by the element.

  1. Let vb-x, vb-y, vb-width, vb-height be the min-x, min-y, width and height values of the viewBox attribute respectively.
  2. Let e-x, e-y, e-width, e-height be the position and size of the element respectively.
  3. Let align be the align value of preserveAspectRatio, or 'xMidyMid' if preserveAspectRatio is not defined.
  4. Let meetOrSlice be the meetOrSlice value of preserveAspectRatio, or 'meet' if preserveAspectRatio is not defined or if meetOrSlice is missing from this value.
  5. Initialize scale-x to e-width/vb-width.
  6. Initialize scale-y to e-height/vb-height.
  7. If align is not 'none' and meetOrSlice is 'meet', set the larger of scale-x and scale-y to the smaller.
  8. Otherwise, if align is not 'none' and meetOrSlice is 'slice', set the smaller of scale-x and scale-y to the larger.
  9. Initialize translate-x to vb-x - e-x.
  10. Initialize translate-y to vb-y - e-y.
  11. If align contains 'xMid', add (e-width - vb-width * scale-x) / 2 to transform-x.
  12. If align contains 'xMax', add (e-width - vb-width * scale-x) to transform-x.
  13. If align contains 'yMid', add (e-height - vb-height * scale-y) / 2 to transform-y.
  14. If align contains 'yMax', add (e-height - vb-height * scale-y) to transform-y.

The transform applied to content contained by the element is given by translate(translate-x, translate-y) scale(scale-x, scale-y).

7.3. The initial viewport

The initial viewport's width, must be the value of the width presentation attribute on the outermost svg element, unless the following conditions are met:

Under these conditions, the viewport's width must be established via the positioning properties.

Similarly, if there are positioning properties specified on the referencing element or on the outermost svg element that are sufficient to establish the height of the viewport, then these positioning properties must establish the viewport's height; otherwise, the initial viewport's height must be the value of the height presentation attribute on the outermost svg element.

If the width or height presentation attributes on the outermost svg element are in user units (i.e., no unit identifier has been provided), then the value is assumed to be equivalent to the same number of "px" units (see Units).

In the following example, an SVG graphic is embedded inline within a parent XML document which is formatted using CSS layout rules. Since CSS positioning properties are not provided on the outermost svg element, the width="100px" and height="200px" attributes determine the size of the initial viewport:

<?xml version="1.0" standalone="yes"?>
<parent xmlns="http://some.url">

   <!-- SVG graphic -->
   <svg xmlns='http://www.w3.org/2000/svg'
      width="100px" height="200px">
      <path d="M100,100 Q200,400,300,100"/>
      <!-- rest of SVG graphic would go here -->
   </svg>

</parent>

7.4. The initial coordinate system

For the outermost svg element, the SVG user agent must determine an initial viewport coordinate system and an initial local coordinate system such that the two coordinates systems are identical. The origin of both coordinate systems must be at the origin of the SVG viewport, and one unit in the initial coordinate system must equal one CSS 2.1 px ([CSS21], section 4.3.2) in the SVG viewport. In stand-alone SVG documents and in SVG document fragments embedded (by reference or inline) within parent documents where the parent's layout is determined by CSS [CSS21] or XSL [XSL], the initial viewport coordinate system (and therefore the initial user coordinate system) must have its origin at the top/left of the viewport, with the positive x-axis pointing towards the right, the positive y-axis pointing down, and text rendered with an "upright" orientation, which means glyphs are oriented such that Roman characters and full-size ideographic characters for Asian scripts have the top edge of the corresponding glyphs oriented upwards and the right edge of the corresponding glyphs oriented to the right.

If the SVG implementation is part of a user agent which supports styling documents using CSS 2.1 compatible px units, then the SVG user agent should set its initial value for the size of a px unit in real world units to match the value used for other styling operations; otherwise, if the user agent can determine the size of a px unit from its environment, it should use that value; otherwise, it should choose an appropriate size for one px unit. In all cases, the size of a px must be in conformance with the rules described in CSS 2.1 ([CSS21], section 4.3.2).

Example InitialCoords below shows that the initial coordinate system has the origin at the top/left with the x-axis pointing to the right and the y-axis pointing down. The initial user coordinate system has one user unit equal to the parent (implicit or explicit) user agent's "pixel".

<?xml version="1.0" standalone="no"?>
<svg width="300px" height="100px" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Example InitialCoords - SVG's initial coordinate system</desc>

  <g fill="none" stroke="black" stroke-width="3" >
    <line x1="0" y1="1.5" x2="300" y2="1.5" />
    <line x1="1.5" y1="0" x2="1.5" y2="100" />
  </g>
  <g fill="red" stroke="none" >
    <rect x="0" y="0" width="3" height="3" />
    <rect x="297" y="0" width="3" height="3" />
    <rect x="0" y="97" width="3" height="3" />
  </g>
  <g font-size="14" font-family="Verdana" >
    <text x="10" y="20">(0,0)</text>
    <text x="240" y="20">(300,0)</text>
    <text x="10" y="90">(0,100)</text>
  </g>
</svg>
Example InitialCoords — SVG's initial coordinate system

Example InitialCoords

View this example as SVG (SVG-enabled browsers only)

7.5. The ‘transform’ property

User agents must support the transform property and presentation attribute as defined in [CSS3TRANSFORMS].

7.6. The ‘viewBox’ attribute

Name Value Initial value Animatable
viewBox [<min-x> <min-y> <width> <height>] As if not specified. yes
<min-x>, <min-x>, <width>, <height> = <number>

Transform on the svg element is a bit special due to the viewBox attribute. The transform should be applied as if the svg had a parent element with that transform set.

RESOLUTION: transform property applies conceptually to the outside of the 'svg' element and there is no difference between presentation attribute and style property (in terms of the visual result).

The viewBox attribute, in conjunction with the preserveAspectRatio attribute, provides the capability to stretch an SVG viewport to fit a particular container element.

The value of the viewBox attribute is a list of four numbers <min-x>, <min-y>, <width> and <height>, separated by whitespace and/or a comma, that specify a rectangle in user space that should be mapped to the bounds of the SVG viewport established by the given element, taking into account the preserveAspectRatio attribute. The presence of the viewBox attribute results in a transformation being applied to the viewport coordinate system as described in Computing the equivalent transform of an SVG viewport.

A negative value for <width> or <height> is an error and invalidates the viewBox attribute. A value of zero disables rendering of the element.

Example ViewBox illustrates the use of the viewBox attribute on the outermost svg element to specify that the SVG content should stretch to fit bounds of the SVG viewport.

<?xml version="1.0" standalone="no"?>
<svg width="300px" height="200px"
     viewBox="0 0 1500 1000" preserveAspectRatio="none"
     xmlns="http://www.w3.org/2000/svg">
  <desc>Example ViewBox - uses the viewBox
   attribute to automatically create an initial user coordinate
   system which causes the graphic to scale to fit into the
   SVG viewport no matter what size the SVG viewport is.</desc>
  <!-- This rectangle goes from (0,0) to (1500,1000) in local coordinate system.
       Because of the viewBox attribute above,
       the rectangle will end up filling the entire area
       reserved for the SVG content. -->
  <rect x="0" y="0" width="1500" height="1000"
        fill="yellow" stroke="blue" stroke-width="12"  />
  <!-- A large, red triangle -->
  <path fill="red"  d="M 750,100 L 250,900 L 1250,900 z"/>
  <!-- A text string that spans most of the SVG viewport -->
  <text x="100" y="600" font-size="200" font-family="Verdana" >
    Stretch to fit
  </text>
</svg>
Example ViewBox
Rendered into
SVG viewport with
width=300px,
height=200px
      Rendered into
SVG viewport with
width=150px,
height=200px
Example ViewBox - stretch to fit 300 by 200       Example ViewBox - stretch to fit 150 by 200

View this example as SVG (SVG-enabled browsers only)
 

The effect of the viewBox attribute is that the user agent automatically supplies the appropriate transformation matrix to map the specified rectangle in local coordinate system to the bounds of a designated region (often, the SVG viewport). To achieve the effect of the example on the left, with SVG viewport dimensions of 300 by 200 pixels, the user agent needs to automatically insert a transformation which scales both X and Y by 0.2. The effect is equivalent to having an SVG viewport of size 300px by 200px and the following supplemental transformation in the document, as follows:

<?xml version="1.0" standalone="no"?>
<svg width="300px" height="200px"
     xmlns="http://www.w3.org/2000/svg">
  <g transform="scale(0.2)">
    <!-- Rest of document goes here -->
  </g>
</svg>

To achieve the effect of the example on the right, with SVG viewport dimensions of 150 by 200 pixels, the user agent needs to automatically insert a transformation which scales X by 0.1 and Y by 0.2. The effect is equivalent to having an SVG viewport of size 150px by 200px and the following supplemental transformation in the document, as follows:

<?xml version="1.0" standalone="no"?>
<svg width="150px" height="200px"
     xmlns="http://www.w3.org/2000/svg">
  <g transform="scale(0.1 0.2)">
    <!-- Rest of document goes here -->
  </g>
</svg>

Note that in some cases the user agent will need to supply a translate transformation in addition to a scale transformation. For example, on an outermost svg element, a translate transformation will be needed if the viewBox attributes specifies values other than zero for <min-x> or <min-y>.

If both transform (or patternTransform) and viewBox are applied to an element two new coordinate systems are established. transform establishes the first new coordinate system for the element. viewBox establishes a second coordinate system for all descendants of the element. The first coordinate system is post-multiplied by the second coordinate system.

Unlike the transform property, the automatic transformation that is created due to a viewBox does not affect the ‘x’, ‘y’, ‘width’ and ‘height’ attributes (or in the case of the marker element, the markerWidth and markerHeight attributes) on the element with the viewBox attribute. Thus, in the example above which shows an svg element which has width and height presentation attributes and a viewBox attribute, the width and height represent values in the coordinate system that exists before the viewBox transformation is applied. On the other hand, like the transform property, it does establish a new coordinate system for all other attributes and for descendant elements.

7.7. The ‘preserveAspectRatio’ attribute

Name Value Initial value Animatable
preserveAspectRatio <align> <meetOrSlice>? xMidYMid meet yes
<align> = 
    none
    | xMinYMin | xMidYMin | xMaxYMin
    | xMinYMid | xMidYMid | xMaxYMid
    | xMinYMax | xMidYMax | xMaxYMax
<meetOrSlice> = meet | slice

Indicates whether or not to force uniform scaling. Applies to all elements that establish a new SVG viewport (see elements that establish SVG viewports), plus the image, marker, pattern and view elements

In some cases, typically when using the viewBox attribute, it is desirable that the graphics stretch to fit non-uniformly to take up the entire SVG viewport. In other cases, it is desirable that uniform scaling be used for the purposes of preserving the aspect ratio of the graphics.

For elements that establish a new SVG viewport (see elements that establish SVG viewports), plus the marker, pattern and view elements, preserveAspectRatio only applies when a value has been provided for viewBox on the same element. For these elements, if attribute viewBox is not provided, then preserveAspectRatio is ignored.

For image elements, preserveAspectRatio indicates how referenced images should be fitted with respect to the reference rectangle and whether the aspect ratio of the referenced image should be preserved with respect to the current user coordinate system.

The <align> parameter indicates whether to force uniform scaling and, if so, the alignment method to use in case the aspect ratio of the viewBox doesn't match the aspect ratio of the SVG viewport. The <align> parameter must be one of the following strings:

The <meetOrSlice> parameter is optional and, if provided, is separated from the <align> value by one or more spaces and then must be one of the following strings:

Example PreserveAspectRatio illustrates the various options on preserveAspectRatio. The example creates several new SVG viewports by including svg sub-elements embedded inside the outermost svg element (see Establishing a new SVG viewport).

<svg width="450px" height="300px" xmlns="http://www.w3.org/2000/svg">

  <desc>Example PreserveAspectRatio - illustrates preserveAspectRatio attribute</desc>

  <style type="text/css">
    text { font-size: 9; }
    rect { fill: none; stroke: blue; }
  </style>

  <defs>
    <g id="smile">
      <rect x='.5' y='.5' width='29' height='39' style="fill:black;stroke:red"/>
      <circle cx='15' cy='20' r='10'  fill='yellow'/>
      <circle cx='12' cy='17' r='1.5' fill='black'/>
      <circle cx='17' cy='17' r='1.5' fill='black'/>
      <path d='M 10 24 A 8 8 0 0 0 20 24' stroke='black' stroke-width='2'/>
    </g>
  </defs>

  <rect x="1" y="1" width="448" height="298"/>

  <text x="10" y="30">SVG to fit</text>
  <g transform="translate(20,40)"><use href="#smile" /></g>

  <text x="10" y="110">Viewport 1</text>
  <g transform="translate(10,120)"><rect x='.5' y='.5' width='49' height='29'/></g>

  <text x="10" y="180">Viewport 2</text>
  <g transform="translate(20,190)"><rect x='.5' y='.5' width='29' height='59'/></g>

  <g id="meet-group-1" transform="translate(100, 60)">
    <text x="0" y="-30">--------------- meet ---------------</text>
    <g>
      <text y="-10">xMin*</text>
      <rect x='.5' y='.5' width='49' height='29'/>
      <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" width="50" height="30">
	<use href="#smile" />
      </svg>
    </g>
    <g transform="translate(70,0)">
      <text y="-10">xMid*</text>
      <rect x='.5' y='.5' width='49' height='29'/>
      <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" width="50" height="30">
	<use href="#smile" />
      </svg>
    </g>
    <g transform="translate(0,70)">
      <text y="-10">xMax*</text>
      <rect x='.5' y='.5' width='49' height='29'/>
      <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" width="50" height="30">
        <use href="#smile" />
      </svg>
    </g>
  </g>

  <g id="meet-group-2" transform="translate(250, 60)">
    <text x="0" y="-30">---------- meet ----------</text>
    <g>
      <text y="-10">*YMin</text>
      <rect  x='.5' y='.5' width='29' height='59'/>
      <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" width="30" height="60">
	<use href="#smile" />
      </svg>
    </g>
    <g transform="translate(50, 0)">
      <text y="-10">*YMid</text>
      <rect x='.5' y='.5' width='29' height='59'/>
      <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" width="30" height="60">
	<use href="#smile" />
      </svg>
    </g>
    <g transform="translate(100, 0)">
      <text y="-10">*YMax</text>
      <rect x='.5' y='.5' width='29' height='59'/>
      <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" width="30" height="60">
	<use href="#smile" />
      </svg>
    </g>
  </g>

  <g id="slice-group-1" transform="translate(100, 220)">
    <text x="0" y="-30">---------- slice ----------</text>
    <g>
      <text y="-10">xMin*</text>
      <rect x='.5' y='.5' width='29' height='59'/>
      <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40" width="30" height="60">
	<use href="#smile" />
      </svg>
    </g>
    <g transform="translate(50,0)">
      <text y="-10">xMid*</text>
      <rect x='.5' y='.5' width='29' height='59'/>
      <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" width="30" height="60">
	<use href="#smile" />
      </svg>
    </g>
    <g transform="translate(100,0)">
      <text y="-10">xMax*</text>
      <rect x='.5' y='.5' width='29' height='59'/>
      <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" width="30" height="60">
	<use href="#smile" />
      </svg>
    </g>
  </g>

  <g id="slice-group-2" transform="translate(250, 220)">
    <text x="0" y="-30">--------------- slice ---------------</text>
    <g>
      <text y="-10">*YMin</text>
      <rect x='.5' y='.5' width='49' height='29'/>
      <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40"
           width="50" height="30">
	<use href="#smile" />
      </svg>
    </g>
    <g transform="translate(70,0)">
      <text y="-10">*YMid</text>
      <rect x='.5' y='.5' width='49' height='29'/>
      <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" width="50" height="30">
	<use href="#smile" />
      </svg>
    </g>
    <g transform="translate(140,0)">
      <text y="-10">*YMax</text>
      <rect x='.5' y='.5' width='49' height='29'/>
      <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" width="50" height="30">
	<use href="#smile" />
      </svg>
    </g>
  </g>
</svg>
Example PreserveAspectRatio — demonstrate available options

Example PreserveAspectRatio

7.8. Establishing a new SVG viewport

At any point in an SVG drawing, you can establish a new SVG viewport into which all contained graphics is drawn by including an svg element inside SVG content. By establishing a new SVG viewport, you also implicitly establish a new viewport coordinate system, a new user coordinate system. Additionally, there is a new meaning for percentage units defined to be relative to the current SVG viewport since a new SVG viewport has been established (see Units).

The bounds of the new SVG viewport are defined by the ‘x’, ‘y’, ‘width’ and ‘height’ attributes on the element establishing the new SVG viewport, such as an svg element. Both the new viewport coordinate system and the new user coordinate system have their origins at (‘x’, ‘y’), where ‘x’ and ‘y’ represent the value of the corresponding attributes on the element establishing the SVG viewport. The orientation of the new viewport coordinate system and the new user coordinate system correspond to the orientation of the current user coordinate system for the element establishing the SVG viewport. A single unit in the new viewport coordinate system and the new user coordinate system are the same size as a single unit in the current user coordinate system for the element establishing the SVG viewport.

Here is an example:

<?xml version="1.0" standalone="no"?>
<svg width="4in" height="3in"
     xmlns="http://www.w3.org/2000/svg">
  <desc>This SVG drawing embeds another one,
    thus establishing a new SVG viewport
  </desc>
  <!-- The following statement establishing a new SVG viewport
       and renders SVG drawing B into that SVG viewport -->
  <svg x="25%" y="25%" width="50%" height="50%">
     <!-- drawing B goes here -->
  </svg>
</svg>

For an extensive example of creating new SVG viewports, see Example PreserveAspectRatio.

The following elements establish new SVG viewports:

For historical reasons, the pattern and marker elements do not create a new viewport, despite accepting a viewBox attribute. Neither do the clipPath or mask elements. Percentage lengths within the content of these elements are not proportional to the dimensions of the graphical effect region.

The foreignObject element establishes a new CSS containing block for its child content. The same is true for a video, audio, or canvas element when its fallback content is being rendered. This has some effects similar to a new viewport, resetting the scope of layout for child content. However, in order to render SVG elements that are descendents of foreignObject, a new svg element must establish an SVG document fragment and SVG viewport.

An image or iframe element creates a new document viewport for the referenced document. If the referenced document is a SVG file, it will of course establish its own SVG viewport.

Whether a new SVG viewport also establishes a new additional clipping path is determined by the value of the overflow property on the element that establishes the new SVG viewport.

7.9. Units

SVG follows the description and definition of common values and units from the CSS Values and Units Module [CSS3VALUES] for attributes, presentation attributes and CSS properties. Each attribute and property must specify the used component value type. Subsequent or extending specifications published by the CSS WG or SVG WG may extend basic data types or add new data types.

For <percentage> values that are defined to be relative to the size of SVG viewport:

Example Units below illustrates some of the processing rules for different types of units.

<?xml version="1.0" standalone="no"?>
<svg width="400px" height="200px" viewBox="0 0 4000 2000"
     xmlns="http://www.w3.org/2000/svg">
  <title>Example Units</title>
  <desc>Illustrates various units options</desc>

  <!-- Frame the picture -->
  <rect x="5" y="5" width="3990" height="1990" 
        fill="none" stroke="blue" stroke-width="10"/>

  <g fill="blue" stroke="red" font-family="Verdana" font-size="150">
    <!-- Absolute unit specifiers -->
    <g transform="translate(400,0)">
      <text x="-50" y="300" fill="black" stroke="none">Abs. units:</text>
      <rect x="0" y="400" width="4in" height="2in" stroke-width=".4in"/>
      <rect x="0" y="750" width="384" height="192" stroke-width="38.4"/>
      <g transform="scale(2)">
        <rect x="0" y="600" width="4in" height="2in" stroke-width=".4in"/>
      </g>
    </g>

    <!-- Relative unit specifiers -->
    <g transform="translate(1600,0)">
      <text x="-50" y="300" fill="black" stroke="none">Rel. units:</text>
      <rect x="0" y="400" width="2.5em" height="1.25em" stroke-width=".25em"/>
      <rect x="0" y="750" width="375" height="187.5" stroke-width="37.5"/>
      <g transform="scale(2)">
        <rect x="0" y="600" width="2.5em" height="1.25em" stroke-width=".25em"/>
      </g>
    </g>

    <!-- Percentages -->
    <g transform="translate(2800,0)">
      <text x="-50" y="300" fill="black" stroke="none">Percentages:</text>
      <rect x="0" y="400" width="10%" height="10%" stroke-width="1%"/>
      <rect x="0" y="750" width="400" height="200" stroke-width="31.62"/>
      <g transform="scale(2)">
        <rect x="0" y="600" width="10%" height="10%" stroke-width="1%"/>
      </g>
    </g>
  </g>
</svg>
Example Units — demonstrate available options

Example Units

The three rectangles on the left demonstrate the use of one of the absolute unit identifiers, the "in" unit (inch). CSS defines 1 inch to be equal to 96 pixels. Therefore, the topmost rectangle, which is specified in inches, is exactly the same size as the middle rectangle, which is specified in user units such that there are 96 user units for each corresponding inch in the topmost rectangle. The bottom rectangle of the group illustrates what happens when values specified in inches are scaled.

The three rectangles in the middle demonstrate the use of one of the relative unit identifiers, the "em" unit. Because the font-size property has been set to 150 on the outermost g element, each "em" unit is equal to 150 user units. The topmost rectangle, which is specified in "em" units, is exactly the same size as the middle rectangle, which is specified in user units such that there are 150 user units for each corresponding "em" unit in the topmost rectangle. The bottom rectangle of the group illustrates what happens when values specified in "em" units are scaled.

The three rectangles on the right demonstrate the use of percentages. Note that the width and height of the SVG viewport in the user coordinate system for the SVG viewport element (in this case, the outermost svg element) are 4000 and 2000, respectively, because processing the viewBox attribute results in a transformed user coordinate system. The topmost rectangle, which is specified in percentage units, is exactly the same size as the middle rectangle, which is specified in equivalent user units. In particular, note that the stroke-width property in the middle rectangle is set to 1% of the sqrt((actual-width)**2 + (actual-height)**2) / sqrt(2), which in this case is .01*sqrt(4000*4000+2000*2000)/sqrt(2), or 31.62. The bottom rectangle of the group illustrates what happens when values specified in percentage units are scaled.

7.10. Bounding boxes

bounding box

The bounding box (or "bbox") of an element is the tightest fitting rectangle aligned with the axes of that element's user coordinate system that entirely encloses it and its descendants.

Three kinds of bounding boxes can be computed for an element:

  1. The object bounding box is the bounding box that contains only an element's geometric shape. For basic shapes, this is the area that is filled. Unless otherwise specified, this is what is meant by the unqualified term "bounding box".
  2. The stroke bounding box is the bounding box that contains an element's geometric shape and its stroke shape.
  3. The decorated bounding box is the bounding box that contains an element's geometric shape, its stroke shape and its markers.

Note that the values of the opacity, visibility, fill, fill-opacity, fill-rule, stroke-dasharray and stroke-dashoffset properties on an element have no effect on the bounding box of an element.

For curved shapes, the bounding box must enclose all portions of the shape along the edge, not just end points. Note that control points for a curve which are not defined as lying along the line of the resulting curve (e.g., the second coordinate pair of a Cubic Bézier command) must not contribute to the dimensions of the bounding box (though those points may fall within the area of the bounding box, if they lie within the shape itself, or along or close to the curve). For example, control points of a curve that are at a further distance than the curve edge, from the non-enclosing side of the curve edge, must be excluded from the bounding box.

Image showing the object bounding box of a quadratic Bézier curve.

The path 'M20,50 L35,100 H120 V50 Q70,10 20,50' is shown in light blue. On the left, a correct object bounding box of the path is shown. Note that it does not include the top-most control point of the curve, but it does include all of the blue shape, even the parts that lie outside of the convex hull of the control points.

Even if an element is not in the rendering tree – due to it being 'display: none', within a defs element, not usually rendered like a symbol element or not currently present in the document tree – it still has a bounding box. A call to getBBox on the element will return the same rectangle as if the element were rendered. However, an element that is not in the rendering tree does not contribute to the bounding box of any ancestor element.

The following example defines a number of elements. The expected object bounding box for each element with an ID is shown below.

<svg xmlns="http://www.w3.org/2000/svg">

  <title>Bounding Box Calculation</title>
  <desc>Examples of elements with different bounding box results based on context.</desc>

  <defs id="defs-1">
     <rect id="rect-1" x="20" y="20" width="40" height="40" fill="blue" />
  </defs>

  <g id="group-1">
    <use id="use-1" href="#rect-1" x="10" y="10" />

    <g id="group-2" display="none">
      <rect id="rect-2" x="10" y="10" width="100" height="100" fill="red" />
    </g>
  </g>
</svg>
Element ID Bounding Box Result
"defs-1" {0, 0, 0, 0}
"rect-1" {20, 20, 40, 40}
"group-1" {30, 30, 40, 40}
"use-1" {30, 30, 40, 40}
"group-2" {10, 10, 100, 100}
"rect-2" {10, 10, 100, 100}

For text content elements, for the purposes of the bounding box calculation, each glyph must be treated as a separate graphics element. The calculations must assume that all glyphs occupy the full glyph cell. The full glyph cell must have width equal to the horizontal advance and height equal to the EM box for horizontal text. For vertical text that is typeset sideways, the full glyph cell must have width equal to the EM box and height equal to the horizontal advance. For other vertical text, the full glyph cell must have width equal to the EM box and height equal to the vertical advance, or height equal to the height of the EM box if no vertical advance is defined in the font. For example, for horizontal text, the calculations must assume that each glyph extends vertically to the full ascent and descent values for the font.

nikos

Because declarative or scripted animation can change the shape, size, and position of an element, the bounding box is mutable. Thus, the bounding box for an element shall reflect the current values for the element at the snapshot in time at which the bounding box is requested, whether through a script call or as part of a declarative or linking syntax.

An element which has zero width, zero height, or both (such as a vertical or horizontal line, or a rect element with a zero width or height) still has a bounding box, with a positive value for the positive dimension, or with '0' for both the width and height if no positive dimension is specified. Similarly, subpaths segments of a path element with zero width and height must be included in that element's geometry for the sake of the bounding box.

An element with no position specified (such as a path element with a value of none for the d property) is positioned at the point (0,0) for the purposes of calculating a bounding box.

Note that elements whose DOM object does not derive from SVGGraphicsElement (such as gradient elements) do not have a bounding box, and thus have no interface to request a bounding box.

Elements in the rendering tree which reference unresolved resources shall still have a bounding box, defined by the position and dimensions specified in their attributes, or by the initial value for those attributes if no values are supplied. For example, the element <use href="#bad" x="10" y="10"/> would have a bounding box with an x and y of 10 and a width and height of 0.

The following algorithm defines how to compute a bounding box for a given element. The inputs to the algorithm are:

The algorithm to compute the bounding box is as follows, depending on the type of element:

a shape
a text content element
an a element within a text content element
  1. Let box be a rectangle initialized to (0, 0, 0, 0).
  2. Let fill-shape be the equivalent path of element if it is a shape, or a shape that includes each of the glyph cells corresponding to the text within the elements otherwise.
  3. If fill is true, then set box to the tightest rectangle in the coordinate system space that contains fill-shape.

    The values of the fill, fill-opacity and fill-rule properties do not affect fill-shape.

  4. If stroke is true and the element's stroke is anything other than none, then set box to be the union of box and the tightest rectangle in coordinate system space that contains the stroke shape of the element, with the assumption that the element has no dash pattern.

    The values of the stroke-opacity, stroke-dasharray and stroke-dashoffset do not affect the calculation of the stroke shape.

  5. If markers is true, then for each marker marker rendered on the element:
    1. For each descendant graphics element child of the marker element that defines marker's content:
      1. If child has an ancestor element within the marker that is 'display: none', has a failing conditional processing attribute, or is not an a, g, svg or switch element, then continue to the next descendant graphics element.
      2. Otherwise, set box to be the union of box and the result of invoking the algorithm to compute a bounding box with child as the element, space as the target coordinate space, true for fill, stroke and markers, and clipped for clipped.
  6. If clipped is true and the value of clip-path on element is not none, then set box to be the tighest rectangle in coordinate system space that contains the intersection of box and the clipping path.
  7. Return box.
a container element
use
  1. Let box be a rectangle initialized to (0, 0, 0, 0).
  2. Let parent be the container element if it is one, or the root of the use element's shadow tree otherwise.
  3. For each descendant graphics element child of parent:
    1. If child has an ancestor element within parent that is 'display: none', has a failing conditional processing attribute, or is not an a, g, svg or switch element, then continue to the next descendant graphics element.
    2. Otherwise, set box to be the union of box and the result of invoking the algorithm to compute a bounding box with child as the element and the same values for space, fill, stroke, markers and clipped as the corresponding algorithm input values.
  4. Return box.
canvas
foreignObject
iframe
image
video
  1. Return the tightest rectangle in coordinate space space that contains the rectangle defined by the ‘x’, ‘y’, ‘width’ and ‘height’ attributes of the element.

    The fill, stroke and markers input arguments to this algorithm do not affect the bounding box returned for these elements.

The union box with a value of (0, 0, 0, 0) and an empty shape is box.

The object bounding box, stroke bounding box or decorated bounding box of an element is the result of invoking the bounding box computation algorithm above with the following arguments: element is the element itself; space is the element's user coordinate system; fill is true; stroke is true if we are computing the stroke bounding box or decorated bounding box, and false othwerise; markers is true if we are computing the decorated bounding box, and false otherwise; and clipped is false.

7.11. Object bounding box units

The following elements offer the option of expressing coordinate values and lengths as fractions (and, in some cases, percentages) of the object bounding box, by setting a specified attribute to 'objectBoundingBox' on the given element:

Element Attribute Effect
linearGradient gradientUnits Indicates that the attributes which specify the gradient vector (x1, y1, x2, y2) represent fractions or percentages of the bounding box of the element to which the gradient is applied.
radialGradient gradientUnits Indicates that the attributes which specify the center (cx, cy), the radius (r) and focus (fx, fy) represent fractions or percentages of the bounding box of the element to which the gradient is applied.
meshgradient gradientUnits Indicates that the attributes which specify the paint server mesh starting point (x, y) represent fractions or percentages and that mesh path data represents fractions of the bounding box of the element to which the mesh is applied. If the mesh is rendered inside a mesh element the current SVG viewport is used in place of a bounding box.
pattern patternUnits Indicates that the attributes which define how to tile the pattern (x, y, width, height) are established using the bounding box of the element to which the pattern is applied.
pattern patternContentUnits Indicates that the user coordinate system for the contents of the pattern is established using the bounding box of the element to which the pattern is applied.
clipPath clipPathUnits Indicates that the user coordinate system for the contents of the clipPath element is established using the bounding box of the element to which the clipping path is applied.
mask maskUnits Indicates that the attributes which define the masking region (x, y, width, height) is established using the bounding box of the element to which the mask is applied.
mask maskContentUnits Indicates that the user coordinate system for the contents of the mask element are established using the bounding box of the element to which the mask is applied.
filter filterUnits Indicates that the attributes which define the filter effects region (x, y, width, height) represent fractions or percentages of the bounding box of the element to which the filter is applied.
filter primitiveUnits Indicates that the various length values within the filter primitives represent fractions or percentages of the bounding box of the element to which the filter is applied.

In the discussion that follows, the term applicable element is the element to which the given effect applies. For gradients and patterns, the applicable element is the graphics element which has its fill or stroke property referencing the given gradient or pattern. (For special rules concerning text elements, see the discussion of object bounding box units and text elements.) For clipping paths, masks and filters, the applicable element can be either a container element or a graphics element.

When keyword objectBoundingBox is used, then the effect is as if a supplemental transformation matrix were inserted into the list of nested transformation matrices to create a new user coordinate system.

First, the (minx,miny) and (maxx,maxy) coordinates are determined by the extends of the object bounding box of the applicable element.

Then, coordinate (0,0) in the new user coordinate system is mapped to the (minx,miny) corner of the tight bounding box within the user coordinate system of the applicable element and coordinate (1,1) in the new user coordinate system is mapped to the (maxx,maxy) corner of the tight bounding box of the applicable element. In most situations, the following transformation matrix produces the correct effect:

[ (maxx-minx) 0 0 (maxy-miny) minx miny ]

When percentages are used with attributes that define the gradient vector, the pattern tile, the filter region or the masking region, a percentage represents the same value as the corresponding decimal value (e.g., 50% means the same as 0.5). If percentages are used within the content of a pattern, clipPath, mask or filter element, these values are treated according to the processing rules for percentages as defined in Units.

Any numeric value can be specified for values expressed as a fraction or percentage of object bounding box units. In particular, fractions less are zero or greater than one and percentages less than 0% or greater than 100% can be specified.

Keyword objectBoundingBox should not be used when the geometry of the applicable element has no width or no height, such as the case of a horizontal or vertical line, even when the line has actual thickness when viewed due to having a non-zero stroke width since stroke width is ignored for bounding box calculations. When the geometry of the applicable element has no width or height and objectBoundingBox is specified, then the given effect (e.g., a gradient or a filter) will be ignored.

7.12. Intrinsic sizing properties of SVG content

To enable inclusion of SVG in host documents formatted with CSS, a concrete object size must be calculated. The concrete object size must be calculated using the Default Sizing Algorithm defined in CSS Images 3 [CSS3IMAGES], with the following inputs:

The specified size must be determined from the used values for the width and height sizing properties of the svg element.

The intrinsic dimensions must also be determined from the width and height sizing properties. If either width or height are not specified, the used value is the initial value 'auto'. 'auto' and percentage lengths must not be used to determine an intrinsic width or intrinsic height.

With bitmap image formats, the intrinsic dimensions are fixed in the image file, and the specified size is defined in the host document as needed to scale the image. SVG, being inherently scalable, adapts the intrinsic width and intrinsic height to be the width and height of the specified size. Therefore, when specified as a length, the width and height sizing properties of the svg element control the intrinsic dimensions of the SVG image and the specified size that is used when placing the SVG image in a host document.

The intrinsic aspect ratio must be calculated using the following algorithm. If the algorithm returns null, then there is no intrinsic aspect ratio.

  1. If the width and height sizing properties on the svg element are both absolute values:
    1. return width / height
  2. If an SVG View is active:
    1. let viewbox be the viewbox defined by the active SVG View
    2. return viewbox.width / viewbox.height
  3. If the viewBox on the svg element is correctly specified:
    1. let viewbox be the viewbox defined by the viewBox attribute on the svg element
    2. return viewbox.width / viewbox.height
  4. return null

The behaviour defined in this section is specific to CSS, but may be adapted to other host contexts. In all host contexts, the intrinsic aspect ratio, where available, must be respected when sizing the SVG viewport.

Examples:

Example: Intrinsic Aspect Ratio 1
<svg xmlns="http://www.w3.org/2000/svg"
     width="10cm" height="5cm">
  ...
</svg>

In this example the intrinsic aspect ratio of the SVG viewport is 2:1. The intrinsic width is 10cm and the intrinsic height is 5cm.

Example: Intrinsic Aspect Ratio 2
<svg xmlns="http://www.w3.org/2000/svg"
     width="100%" height="50%" viewBox="0 0 200 200">
  ...
</svg>

In this example the intrinsic aspect ratio of the outermost SVG viewport is 1:1. An aspect ratio calculation in this case allows embedding in an object within a containing block that is only constrained in one direction.

Example: Intrinsic Aspect Ratio 3
<svg xmlns="http://www.w3.org/2000/svg"
     width="10cm" viewBox="0 0 200 200">
  ...
</svg>

In this case the intrinsic aspect ratio is 1:1.

Example: Intrinsic Aspect Ratio 4
<svg xmlns="http://www.w3.org/2000/svg"
     width="75%" height="10cm" viewBox="0 0 200 200">
  ...
</svg>

In this example, the intrinsic aspect ratio is 1:1.

Add more examples for the new auto value? E.g some of the examples provided by David Vest.

7.13. Vector effects

SVG 2 Requirement: SVG 2 will have constrained transformations based on SVG 1.2 Tiny.
Resolution: Add vector effects extension proposal to SVG 2 specification.
Purpose: To include non-scaling features (non-scaling part of the object, and non-scaling entire object
Owner: Satoru Takagi (ACTION-3619)

Sometimes it is of interest to let the outline of an object keep its original width or to let the position of an object fix no matter which transforms are applied to it. For example, in a map with a 2px wide line representing roads it is of interest to keep the roads 2px wide even when the user zooms into the map, or introductory notes on the graphic chart in which panning is possible.

To offer such effects regarding special coordinate transformations and graphic drawings, SVG Tiny 1.2 introduces the vector-effect property. Although SVG Tiny 1.2 introduced only non-scaling stroke behavior, this version introduces a number of additional effects. Furthermore, since these effects can be specified in combination, they show more various effects. And, future versions of the SVG language will allow for more powerful vector effects through this property.

Name: vector-effect
Value: none | [ non-scaling-stroke | non-scaling-size | non-rotation | fixed-position ]+ [ viewport | screen ]?
Initial: none
Applies to: graphics elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes
none
Specifies that no vector effect shall be applied, i.e. the default rendering behaviour from SVG 1.1 is used which is to first fill the geometry of a shape with a specified paint, then stroke the outline with a specified paint.
non-scaling-stroke
Please refer to this description of vector effect on painting.
non-scaling-size
Specifies special local coordinate system toward this element and its descendant by constrained transformations with the following characteristics. The scale of the local coordinate system do not change in spite of change of CTMs from a host coordinate space. However, it does not specify the suppression of rotation and skew. Also, it does not specify the fixation of placement of local coordinate system. Since non-scaling-size suppresses scaling of local coordinate system, it also has the characteristic of non-scaling-stroke. The transformation formula and the example behavior are indicated to the following chapter.
non-rotation
Specifies special local coordinate system toward this element and its descendant by constrained transformations with the following characteristics. The rotation and skew of the local coordinate system is suppressd in spite of change of CTMs from a host coordinate space. However, it does not specify the suppression of scaling. Also, it does not specify the fixation of placement of local coordinate system. The transformation formula and the example behavior are indicated to the following chapter.
fixed-position
Specifies special local coordinate system toward this element and its descendant by constrained transformations with the following characteristics. The placement of local coordinate system is fixed in spite of change of CTMs from a host coordinate space. However, it does not specify the suppression of rotation, skew and scaling. When the element that has fixed-position effect and also has transform property, that property is consumed for this effect. The shift components e and f of matrix of transform property are used to transfer the origin of fixed local coordinate system. The transformation formula and the example behavior are indicated to the following chapter.

These values can be enumerated. Thereby, the effect which has these characteristics simultaneously can be specified.

The following two values assists the above-mentioned values. They show the host coordinate space of constrained transformations. Especially it has effective for the element belonging to nested viewport coordinate system such as nested contents or nested svg elements. An initial value in case it is not specified is viewport.

viewport
Specifies immediate viewport coordinate system as the host coordinate space. When that element belongs to nested viewport coordinate system, vector effects are applied toward viewport coordinate system to which that element belongs directly. That is, that vector effect is not effective for change of CTM on ancestral viewport coordinate system.
screen
It specifies the coordinate system of content which under the immediate control of user agent. So to speak, it is "scrren" which user agent has. ("screen coordinate space" in SVGT1.2) Even if that element belongs to nested viewport coordinate system, that vector effect is always effective for change of CTM of the any hierarchy. If the SVG implementation is part of a user agent which supports CSS compatible px units, it is a coordinate system on CSS pixel of rootmost content. Generally, the pixel (or dot) of a device and pixel of CSS are not always equal by influences of the zoom function which user agent itself has, and variation of dpi. (see resolution [CSS Values and Units Module Level 3]) Accordingly, this value does not specify constrained transformations toward the such a device coordinate system.

Note: Future versions of SVG may allow ways to specify the device coordinate system.

7.13.1. Computing the vector effects

This section shows the list of transformation formulas regarding combinations of the values for clarification of the behavior of vector effects excluding non-scaling-stroke which has clear implications.

The vector-effect property has no effect on transformations performed in a 3d rendering context.

The normal coordinate transformation formula from local coordinate system to viewport coordinate system is as follows.

x viewport y viewport 1 = CTM x userspace y userspace 1 CTM = a ctm c ctm e ctm b ctm d ctm f ctm 0 0 1
<circle vector-effect="veValue" transform="translate(xo yo)" cx="xf" cy="yf" r=".."/>

When the vector-effect is added to an element like the above, the transformation formula for user coordinate to the device coordinate changes as follows. Here, xf and yf are user coordinate of the corresponding element and its descendant. And, xo and yo are matrix element e and f of the transform attribute which the corresponding element has. In addition, |det(CTM)| is absolute value of the determinants of CTM. When this value becomes 0 and non-scaling-size is appointed, vector-effect becomes invalidity namely none.

det CTM = a ctm d ctm - b ctm c ctm
veValue Formula
non-scaling-size
x viewport y viewport 1 = CTM 0 0 1 + CTM det CTM 1 0 0 0 1 0 0 0 0 x f y f 1
non-rotation
x viewport y viewport 1 = CTM 0 0 1 + det CTM 1 0 0 0 1 0 0 0 0 x f y f 1
non-scaling-size non-rotation
x viewport y viewport 1 = CTM 0 0 1 + 1 0 0 0 1 0 0 0 0 x f y f 1
fixed-position
x viewport y viewport 1 = x o y o 1 + CTM 1 0 0 0 1 0 0 0 0 x f y f 1
fixed-position non-scaling-size
x viewport y viewport 1 = x o y o 1 + CTM det CTM 1 0 0 0 1 0 0 0 0 x f y f 1
fixed-position non-rotation
x viewport y viewport 1 = x o y o 1 + det CTM 1 0 0 0 1 0 0 0 0 x f y f 1
fixed-position non-scaling-size non-rotation
x viewport y viewport 1 = x o y o 1 + 1 0 0 0 1 0 0 0 0 x f y f 1

7.13.2. Computing the vector effects for nested viewport coordinate systems

Below is normal coordinate transformation formula for nested viewport coordinate systems without vector effects. xviewport(UA) and yviewport(UA) are coordinates which under the immediate control of user agent. CTMthis is CTM for the transformation matrix from local coordinate system of an target graphic to viewport coordinate system to which it belongs. CTMparent is CTM for the transformation matrix from aforementioned viewport coordinate system to viewport coordinate system of the parent of that. And, CTMroot is CTM for rootmost viewport coordinate system (UA).

x viewport(UA) y viewport(UA) 1 = CTM root ... CTM parent CTM this x userspace y userspace 1

When applying seven formulas of the preceding section to nested viewport coordinate systems, the application way of those formulas changes as follows by whether viewport or screen is specified as the additional value of vector-effect.

When viewport value is specified, user agent computes coordinates combining either of seven formulas of the preceding chapter, and the following formulas.

x viewport ( UA ) y viewport ( UA ) 1 = CTM root ... CTM parent x viewport y viewport 1 CTM = CTM this

When screen value is specified, user agent computes coordinates combining either of seven formulas of the preceding chapter, and the following formulas.

x viewport ( UA ) y viewport ( UA ) 1 = x viewport y viewport 1 CTM = CTM root ... CTM parent CTM this

7.13.3. Examples of vector effects

Below is an example of the non-scaling-stroke vector-effect.

<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg"
     width="6cm" height="4cm" viewBox="0 0 600 400" 
     viewport-fill="rgb(255,150,200)">

  <desc>Example non-scaling stroke</desc>
  <rect x="1" y="1" width="598" height="398" fill="none" stroke="black"/>
  
  <g transform="scale(9,1)">
    <line stroke="black" stroke-width="5" x1="10" y1="50" x2="10" y2="350"/>
    <line vector-effect="non-scaling-stroke" stroke="black" stroke-width="5" 
        x1="32" y1="50" x2="32" y2="350"/>
    <line vector-effect="none" stroke="black" stroke-width="5" 
        x1="55" y1="50" x2="55" y2="350"/>
  </g>

</svg>

Below is an example of the none vector-effect (no vector effect).

Before changing CTMAfter changing CTM
Image showing none vector effect Image showing none vector effect

Source code

<svg xmlns="http://www.w3.org/2000/svg" viewBox="-50,-50,500,500" height="500" width="500">

  <rect x="-50" y="-50" width="500" height="500" stroke="orange" stroke-width="3" fill="none"/>

  <!-- Nested local coordinate system is transformed by this transform attribute -->
  <g transform="matrix(2.1169438081370817,0.3576047954311102,-0.3576047954311102,1.4700998667618626,0,0)
                translate(-50,-50)">
    <svg viewBox="-50,-50,500,500" height="500" width="500">
      <!-- Graph paper on the this svg's base local coordinate system -->
      <g stroke="green" stroke-width="1" fill="none">
        <circle cx="0" cy="0" r="10"/>
        <circle cx="150" cy="150" r="7"/>
        <path fill="green" stroke="none" d="M0,-3 L30,-3 25,-10 50,0 25,10 30,3 0,3z"/>

        <line x1="-100" y1="-100" x2="600" y2="-100" stroke-dasharray="5,5"/>
        <line x1="-100" y1="000" x2="600" y2="000"/>
        <line x1="-100" y1="100" x2="600" y2="100" stroke-dasharray="5,5"/>
        <line x1="-100" y1="200" x2="600" y2="200" stroke-dasharray="5,5"/>
        <line x1="-100" y1="300" x2="600" y2="300" stroke-dasharray="5,5"/>
        <line x1="-100" y1="400" x2="600" y2="400" stroke-dasharray="5,5"/>
        <line x1="-100" y1="500" x2="600" y2="500" stroke-dasharray="5,5"/>

        <line y1="-100" x1="-100" y2="600" x2="-100" stroke-dasharray="5,5"/>
        <line y1="-100" x1="000" y2="600" x2="000"/>
        <line y1="-100" x1="100" y2="600" x2="100" stroke-dasharray="5,5"/>
        <line y1="-100" x1="200" y2="600" x2="200" stroke-dasharray="5,5"/>
        <line y1="-100" x1="300" y2="600" x2="300" stroke-dasharray="5,5"/>
        <line y1="-100" x1="400" y2="600" x2="400" stroke-dasharray="5,5"/>
        <line y1="-100" x1="500" y2="600" x2="500" stroke-dasharray="5,5"/>
      </g>

      <!-- Figure having vector effect -->
      <!-- A thick red right arrow and small rectangle on this figure's nested
           local coordinate system origin -->
      <path id="ve" vector-effect="none"
            stroke="red" stroke-width="3" fill="none"
            transform="matrix(1,0,0,1,150,150)"
            d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
    </svg>
  </g>
</svg>

Below is an example of the non-scaling-size.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-scaling-size vector effect
<path id="ve" vector-effect="non-scaling-size"
      stroke="red" stroke-width="3" fill="none"
      transform="matrix(1,0,0,1,150,150)"
      d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>

Below is an example of the non-rotation.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-rotation vector effect
<path id="ve" vector-effect="non-rotation"
      stroke="red" stroke-width="3" fill="none"
      transform="matrix(1,0,0,1,150,150)"
      d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>

Below is an example of the non-scaling-size non-rotation.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-scaling-size non-rotation vector effect
<path id="ve" vector-effect="non-scaling-size non-rotation"
      stroke="red" stroke-width="3" fill="none"
      transform="matrix(1,0,0,1,150,150)"
      d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>

Below is an example of the fixed-position.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing fixed-position vector effect
<path id="ve" vector-effect="fixed-position"
      stroke="red" stroke-width="3" fill="none"
      transform="matrix(1,0,0,1,150,150)"
      d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>

Below is an example of the non-scaling-size fixed-position.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-scaling-size fixed-position vector effect
<path id="ve" vector-effect="non-scaling-size fixed-position"
      stroke="red" stroke-width="3" fill="none"
      transform="matrix(1,0,0,1,150,150)"
      d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>

Below is an example of the non-rotation fixed-position.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-rotation fixed-position vector effect
<path id="ve" vector-effect="non-rotation fixed-position"
      stroke="red" stroke-width="3" fill="none"
      transform="matrix(1,0,0,1,150,150)"
      d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>

Below is an example of the non-scaling-size non-rotation fixed-position.

Before changing CTMAfter changing CTM
Image showing appearance before the effect of the vector effect showing up Image showing non-scaling-size non-rotation fixed-position vector effect
<path id="ve" vector-effect="non-scaling-size non-rotation fixed-position"
      stroke="red" stroke-width="3" fill="none"
      transform="matrix(1,0,0,1,150,150)"
      d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>

7.14. DOM interfaces

7.14.1. Interface SVGTransform

The SVGTransform interface is used to represent <transform-function> values that appear in the transform property and its presentation attributes ‘transform’, gradientTransform and patternTransform. An SVGTransform represents a single component in a transform list, such as a single scale(…) or matrix(…) value.

An SVGTransform object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.

An SVGTransform object can be associated with a particular element. The associated element is used to determine which element's ‘transform’ presentation attribute to update if the object reflects that attribute. Unless otherwise described, an SVGTransform object is not associated with any element.

Every SVGTransform object operates in one of two modes. It can:

  1. reflect an element of a presentation attribute value (being exposed through the methods on the baseVal member of an SVGAnimatedTransformList),
  2. be detached, which is the case for SVGTransform objects created with createSVGTransform and createSVGTransformFromMatrix.

An SVGTransform object maintains an internal <transform-function> value, which is called its value. It also maintains a DOMMatrix object, which is called its matrix object, which is the object returned from the matrix IDL attribute. An SVGTransform object's matrix object is always kept synchronized with it its value.

interface SVGTransform {

  // Transform Types
  const unsigned short SVG_TRANSFORM_UNKNOWN = 0;
  const unsigned short SVG_TRANSFORM_MATRIX = 1;
  const unsigned short SVG_TRANSFORM_TRANSLATE = 2;
  const unsigned short SVG_TRANSFORM_SCALE = 3;
  const unsigned short SVG_TRANSFORM_ROTATE = 4;
  const unsigned short SVG_TRANSFORM_SKEWX = 5;
  const unsigned short SVG_TRANSFORM_SKEWY = 6;

  readonly attribute unsigned short type;
  [SameObject] readonly attribute DOMMatrix matrix;
  readonly attribute float angle;

  void setMatrix(DOMMatrixReadOnly matrix);
  void setTranslate(float tx, float ty);
  void setScale(float sx, float sy);
  void setRotate(float angle, float cx, float cy);
  void setSkewX(float angle);
  void setSkewY(float angle);
};

The numeric transform type constants defined on SVGTransform are used to represent the type of an SVGTransform's value. Their meanings are as follows:

ConstantMeaning
SVG_TRANSFORM_MATRIXA matrix(…) value.
SVG_TRANSFORM_TRANSLATEA translate(…) value.
SVG_TRANSFORM_SCALEA scale(…) value.
SVG_TRANSFORM_ROTATEA rotate(…) value.
SVG_TRANSFORM_SKEWXA skewX(…) value.
SVG_TRANSFORM_SKEWYA skewY(…) value.
SVG_TRANSFORM_UNKNOWNSome other type of value.

The use of numeric transform type constants is an anti-pattern and new constant values will not be introduced for any transform types supported by SVGTransform. If other types of transforms are supported and used, the SVGTransform uses the SVG_TRANSFORM_UNKNOWN type. See below for details on how the other properties of an SVGTransform operate with these types of transforms.

The type IDL attribute represents the type of transform item that the SVGTransform's value is. On getting type, the following steps are run:

  1. If the SVGTransform's value is a matrix(…), translate(…), scale(…), rotate(…), skewX(…) or skewY(…) function, then return the corresponding constant value from the transform type table above.
  2. Otherwise, return SVG_TRANSFORM_UNKNOWN.

    For example, for a scaleX(…) or translate3d(…) transform, SVG_TRANSFORM_UNKNOWN would be returned.

The matrix IDL attribute represents the transform as a 4x4 homogeneous matrix, and on getting returns the SVGTransform's matrix object. When the matrix object is first created, its values are set to match the SVGTransform's transform function value, and is set to reflects the SVGTransform.

See the CSS Transforms specification for a description of how the different transform function types correspond to particular matrix values.

The angle IDL attribute represents the angle parameter of a rotate(…), skewX(…) or skewY(…) transform function. On getting, the following steps are run:

  1. If the SVGTransform object's value is a rotate(…), skewX(…) or skewY(…) function, return its angle argument in degrees.
  2. Otherwise, return 0.

The setMatrix method is used to set the SVGTransform to a given matrix value. When setMatrix(matrix) is called, the following steps are run:

  1. If the SVGTransform object is read only, then throw a NoModificationAllowedError.
  2. If matrix would return true from its is2d method, then set the SVGTransform object's value to a matrix(…) value that represents the same matrix as matrix.
  3. Otherwise, set the SVGTransform object's value to a matrix3d(…) value that represents the same matrix as matrix.
  4. Copy the matrix component values from matrix into the SVGTransform object's matrix object.
  5. If the SVGTransform object reflects an element of a presentation attribute value, then reserialize the reflected attribute.

The setTranslate, setScale, setRotate, setSkewX and setSkewY methods are used to set the SVGTransform to a new transform function value. When one of these methods is called, the following steps are run:

  1. If the SVGTransform object is read only, then throw a NoModificationAllowedError.
  2. Set the SVGTransform object's value to a new transform function value, depending on which method was called:
    setTranslate(tx, ty)
    the new transform function value is translate(tx, ty)
    setScale(sx, sy)
    the new transform function value is scale(sx, sy)
    setRotate(angle, cx, cy)
    the new transform function value is rotate(angle, cx, cy)
    setSkewX(angle)
    the new transform function value is skewX(angle)
    setSkewY(angle)
    the new transform function value is skewY(angle)
  3. Set the components of the SVGTransform object's matrix object to match the new transform function value.
  4. If the SVGTransform object reflects an element of a presentation attribute value, then reserialize the reflected attribute.

This specification imposes additional requirements on the behavior of DOMMatrix objects beyond those described in the the Geometry Interfaces specification, so that they can be used to reflect presentation attributes that take transform values.

Every DOMMatrix object operates in one of two modes. It can:

  1. reflect an SVGTransform (being exposed through the matrix IDL attribute on an SVGTransform), or
  2. be detached, which is the case for DOMMatrix objects created using their constructor or with createSVGMatrix.

A DOMMatrix can be designated as read only, which means that attempts to modify the object will result in an exception being thrown. When assigning to any of a read only DOMMatrix's IDL attributes, or when invoking any of its mutable transform methods, a NoModificationAllowedError exception will be thrown instead of updating the internal value.

Note that this applies only to the read-write DOMMatrix interface; the DOMMatrixReadOnly interface, which is not used for reflecting transform, will already throw an exception if an attempt is made to modify it.

When assigning to any of a writable DOMMatrix's IDL attributes, or when invoking any of its mutable transform methods, the following steps are run after updating the internal matrix value:

  1. If the DOMMatrix reflects an SVGTransform, then:
    1. If the DOMMatrix would return true from its is2d method, then set the SVGTransform object's value to a matrix(…) value that represents the same matrix as the DOMMatrix.
    2. Otherwise, set the SVGTransform object's value to a matrix3d(…) value that represents the same matrix as the DOMMatrix.
    3. If the SVGTransform object reflects an element of a presentation attribute value, then reserialize the reflected attribute.

7.14.2. Interface SVGTransformList

The SVGTransformList interface is a list interface whose elements are SVGTransform objects. An SVGTransformList represents a value that the transform property can take, namely either a <transform-list> or the keyword none.

interface SVGTransformList {

  readonly attribute unsigned long length;
  readonly attribute unsigned long numberOfItems;

  void clear();
  SVGTransform initialize(SVGTransform newItem);
  getter SVGTransform getItem(unsigned long index);
  SVGTransform insertItemBefore(SVGTransform newItem, unsigned long index);
  SVGTransform replaceItem(SVGTransform newItem, unsigned long index);
  SVGTransform removeItem(unsigned long index);
  SVGTransform appendItem(SVGTransform newItem);
  setter void (unsigned long index, SVGTransform newItem);

  // Additional methods not common to other list interfaces.
  SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix);
  SVGTransform? consolidate();
};

The createSVGTransformFromMatrix method is used to create a new SVGTransform object from a matrix object. When the createSVGTransformFromMatrix(matrix) method is called, the following steps are run:

  1. Let transform be a newly created SVGTransform object that is detached.
  2. Follow the steps that would be run if the setMatrix method on transform were called, passing matrix as its argument.
  3. Return transform.

The consolidate method is used to convert the transform list into an equivalent transformation using a single transform function. When the consolidate() method is called, the following steps are run:

  1. If the SVGTransformList object is read only, then throw a NoModificationAllowedError.
  2. If the list is empty, return null.
  3. Detach and then remove all elements in the list.
  4. Let transform be a newly created SVGTransform object.
  5. Let matrix be the matrix value obtained by beginning with an identity matrix, and then post-multiplying the value of the matrix object for each SVGTransform in the list, in order.
  6. Set the components of transform's matrix object to the component values in matrix.
  7. If transform's matrix object would return true from its is2d method, then set transform's value to a matrix(…) value that represents the same matrix as the matrix object.
  8. Otherwise, set transform's value to a matrix3d(…) value that represents the same matrix as the matrix object.
  9. Attach transform to this SVGTransformList.
  10. Append transform to this list.
  11. If the list reflects a presentation attribute, then reserialize the reflected attribute.
  12. Return transform.

The behavior of all other interface members of SVGLengthList are defined in List interfaces.

7.14.3. Interface SVGAnimatedTransformList

An SVGAnimatedTransformList object is used to reflect the transform property and its corresponding presentation attribute (which, depending on the element, is ‘transform’, gradientTransform or patternTransform).

interface SVGAnimatedTransformList {
  [SameObject] readonly attribute SVGTransformList baseVal;
  [SameObject] readonly attribute SVGTransformList animVal;
};

The baseVal and animVal IDL attributes represent the value of the reflected presentation attribute. On getting baseVal or animVal, an SVGTransformList object is returned that reflects the given presentation attribute.

7.14.4. Interface SVGPreserveAspectRatio

The SVGPreserveAspectRatio interface is used to represent values for the preserveAspectRatio attribute.

An SVGPreserveAspectRatio object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.

Every SVGPreserveAspectRatio object reflects the base value of a reflected preserveAspectRatio attribute (being exposed through the methods on the baseVal or animVal member of an SVGAnimatedPreserveAspectRatio).

interface SVGPreserveAspectRatio {

  // Alignment Types
  const unsigned short SVG_PRESERVEASPECTRATIO_UNKNOWN = 0;
  const unsigned short SVG_PRESERVEASPECTRATIO_NONE = 1;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMIN = 2;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMIN = 3;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMIN = 4;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMID = 5;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMID = 6;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMID = 7;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMAX = 8;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMAX = 9;
  const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMAX = 10;

  // Meet-or-slice Types
  const unsigned short SVG_MEETORSLICE_UNKNOWN = 0;
  const unsigned short SVG_MEETORSLICE_MEET = 1;
  const unsigned short SVG_MEETORSLICE_SLICE = 2;

  attribute unsigned short align;
  attribute unsigned short meetOrSlice;
};

The numeric alignment type constants defined on SVGPreserveAspectRatio are used to represent the alignment keyword values that preserveAspectRatio can take. Their meanings are as follows:

ConstantMeaning
SVG_PRESERVEASPECTRATIO_NONEThe none keyword.
SVG_PRESERVEASPECTRATIO_XMINYMINThe xMinYMin keyword.
SVG_PRESERVEASPECTRATIO_XMIDYMINThe xMidYMin keyword.
SVG_PRESERVEASPECTRATIO_XMAXYMINThe xMaxYMin keyword.
SVG_PRESERVEASPECTRATIO_XMINYMIDThe xMinYMid keyword.
SVG_PRESERVEASPECTRATIO_XMIDYMIDThe xMidYMid keyword.
SVG_PRESERVEASPECTRATIO_XMAXYMIDThe xMaxYMid keyword.
SVG_PRESERVEASPECTRATIO_XMINYMAXThe xMinYMax keyword.
SVG_PRESERVEASPECTRATIO_XMIDYMAXThe xMidYMax keyword.
SVG_PRESERVEASPECTRATIO_XMAXYMAXThe xMaxYMax keyword.
SVG_PRESERVEASPECTRATIO_UNKNOWNSome other type of value.

Similarly, the numeric meet-or-slice type constants defined on SVGPreserveAspectRatio are used to represent the meet-or-slice keyword values that preserveAspectRatio can take. Their meanings are as follows:

ConstantMeaning
SVG_MEETORSLICE_MEETThe meet keyword.
SVG_MEETORSLICE_SLICEThe slice keyword.
SVG_MEETORSLICE_UNKNOWNSome other type of value.

The align IDL attribute represents the alignment keyword part of the preserveAspectRatio value. On getting, the following steps are run:

  1. Let value reflect the base value of a preserveAspectRatio attribute. value is the current non-animated value of the attribute (using the attribute's initial value if it is not present or invalid).
  2. Return the constant value as specified in the alignment constant table above for the alignment keyword in value.

On setting align, the following steps are run:

  1. If the SVGPreserveAspectRatio is read only, then throw a NoModificationAllowedError.
  2. If value is SVG_PRESERVEASPECTRATIO_UNKNOWN or does not have a corresponding entry in the alignment keyword table above, then return.
  3. Let string be the corresponding keyword in the alignment keyword table above for value.
  4. Append a single U+0020 SPACE character to string.
  5. Let meet or slice be the value that would be returned from the meetOrSlice member on this SVGPreserveAspectRatio.
  6. Append to string the corresponding keyword in the meet-or-slice keyword table above for meet or slice.
  7. Set the reflected preserveAspectRatio attribute to string.

The meetOrSlice IDL attribute represents the alignment keyword part of the preserveAspectRatio value. On getting, the following steps are run:

  1. Let value be a preserveAspectRatio value that reflects the base value of a preserveAspectRatio attribute value is the current non-animated value of the attribute.
  2. If the meet-or-slice value is not present in value, then return SVG_MEETORSLICE_MEET.
  3. Otherwise, the meet-or-slice value is present. Return the constant value as specified in the meet-or-slice constant table above for the meet-or-slice keyword in value.

On setting meetOrSlice, the following steps are run:

  1. If the SVGPreserveAspectRatio is read only, then throw a NoModificationAllowedError.
  2. If value is SVG_MEETORSLICE_UNKNOWN or does not have a corresponding entry in the meet-or-slice keyword table above, then return.
  3. Let align be the value that would be returned from the align member on this SVGPreserveAspectRatio.
  4. Let string be the corresponding keyword in the alignment keyword table above for align.
  5. Append a single U+0020 SPACE character to string.
  6. Append to string the corresponding keyword in the meet-or-slice keyword table above for value.
  7. Set the reflected preserveAspectRatio attribute to string.

7.14.5. Interface SVGAnimatedPreserveAspectRatio

An SVGAnimatedPreserveAspectRatio object is used to reflect the preserveAspectRatio attribute.

interface SVGAnimatedPreserveAspectRatio {
  [SameObject] readonly attribute SVGPreserveAspectRatio baseVal;
  [SameObject] readonly attribute SVGPreserveAspectRatio animVal;
};

The baseVal and animVal IDL attributes represent the current non-animated value of the reflected preserveAspectRatio attribute. On getting baseVal or animVal, an SVGPreserveAspectRatio object is returned that reflects the base value of the preserveAspectRatio attribute on the SVG element that the object with the reflcting IDL attribute of type SVGAnimatedPreserveAspectRatio was obtained from.

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 8: Paths

8.1. Introduction

A path represents the outline of a shape which can be filled or stroked. A path can also be used as a clipping path, to describe animation, or position text. A path can be used for more than one of these functions at the same time. (See Filling, Stroking and Paint Servers, Clipping and Masking, Animation ('animateMotion'), and Text on a Path.)

A path is described using the concept of a current point. In an analogy with drawing on paper, the current point can be thought of as the location of the pen. The position of the pen can be changed, and the outline of a shape (open or closed) can be traced by dragging the pen in either straight lines or curves.

Paths represent the geometry of the outline of an object, defined in terms of moveto (set a new current point), bearing (set a new orientation), lineto (draw a straight line), curveto (draw a curve using a cubic Bézier), arc (elliptical or circular arc) and closepath (close the current shape by connecting to the last moveto) commands. Compound paths (i.e., a path with multiple subpaths) are possible to allow effects such as "donut holes" in objects.

This chapter describes the syntax, behavior and DOM interfaces for SVG paths. Various implementation notes for SVG paths can be found in ‘path’ element implementation Notes and Elliptical arc implementation notes.

A path is defined in SVG using the path element.

The basic shapes are all described in terms of what their equivalent path is, which is what their shape is as a path. (The equivalent path of a path element is simply the path itself.)

8.2. The ‘path’ element

path
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script, style
Attributes:
Geometry properties:
DOM Interfaces:

The outline of a shape for a path element is specified using the d property. See Path data below.

8.3. Path data

SVG 2 Requirement: Support turtle-graphics-like current rotation in path syntax.
Resolution: We will add a path rotation command.
Purpose: Make path rotations easier to animate and pie charts easier to draw.
Owner: Cameron (ACTION-3125)
Status: Done

8.3.1. General information about path data

A path is defined by including a path element on which the d property specifies the path data. The path data contains the moveto, bearing, lineto, curveto (both cubic and quadratic Béziers), arc and closepath instructions.

Example triangle01 specifies a path in the shape of a triangle. (The M indicates a moveto, the Ls indicate linetos, and the z indicates a closepath).

<?xml version="1.0" standalone="no"?>
<svg width="4cm" height="4cm" viewBox="0 0 400 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <title>Example triangle01- simple example of a 'path'</title>
  <desc>A path that draws a triangle</desc>
  <rect x="1" y="1" width="398" height="398"
        fill="none" stroke="blue" />
  <path d="M 100 100 L 300 100 L 200 300 z"
        fill="red" stroke="blue" stroke-width="3" />
</svg>
Example triangle01 — simple example of a 'path'

Example triangle01

View this example as SVG (SVG-enabled browsers only)

Path data can contain newline characters and thus can be broken up into multiple lines to improve readability. Newlines inside attributes in markup will be normalized to space characters while parsing.

The syntax of path data is concise in order to allow for minimal file size and efficient downloads, since many SVG files will be dominated by their path data. Some of the ways that SVG attempts to minimize the size of path data are as follows:

The path data syntax is a prefix notation (i.e., commands followed by parameters). The only allowable decimal point is a Unicode U+0046 FULL STOP (".") character (also referred to in Unicode as PERIOD, dot and decimal point) and no other delimiter characters are allowed [UNICODE]. (For example, the following is an invalid numeric value in a path data stream: "13,000.56". Instead, say: "13000.56".)

For the relative versions of the commands, all coordinate values are relative to the current point at the start of the command.

Relative path commands are also influenced by the current bearing, which is an angle set by the bearing commands. This allows for paths to be specified using a style of "turtle graphics", where straight line and curved path segments are placed with their starting point at a tangent (or at some other angle) to the current bearing.

In the tables below, the following notation is used to describe the syntax of a given path command:

In the description of the path commands, cpx and cpy represent the coordinates of the current point, and cb represents the current bearing.

8.3.2. Specifying path data: the ‘d’ property

Name: d
Value: none | <string>
Initial: none
Applies to: path
Inherited: no
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

The d property is used to specify the shape of a path element.

The value none indicates that there is no path data for the element. For path elements, this means that the element does not render or contribute to the bounding box of ancestor container elements.

A path is made up of multiple segments, and every command, either explicit or implicit, other than moveto or closepath, defines one path segment.

All coordinates and lengths specified within path data must be treated as being in user units in the current user coordinate system.

The <string> value specifies a shape using a path data string. The contents of the <string> value must match the svg-path EBNF grammar defined below, and errors within the string are handled according to the rules in the Path Data Error Handling section. If the path data string contains no valid commands, then the behavior is the same as the none value.

For animation, two d property values can only be interpolated smoothly when the path data strings contain have the same structure, (i.e. exactly the same number and types of path data commands which are in the same order). If an animation is specified and the lists of path data commands do not have the same structure, then the values must be interpolated using the discrete animation type.

If the list of path data commands have the same structure, then each parameter to each path data command must be interpolated separately as real numbers. Flags and booleans must be interpolated as fractions between zero and one, with any non-zero value considered to be a value of one/true.

Resolved that "d will become a presentation attribute (no name change) with path data string as value" at London Editor's Meeting.

The following sections list the commands that canbe used in path data strings. Those that draw straight line segments include the lineto commands (L, l, H, h, V and v) and the close path commands (Z and z). These three groups of commands draw curves:

8.3.3. The "moveto" commands

The "moveto" commands (M or m) must establish a new initial point and a new current point. The effect is as if the "pen" were lifted and moved to a new location. A path data segment (if there is one) must begin with a "moveto" command. Subsequent "moveto" commands (i.e., when the "moveto" is not the first command) represent the start of a new subpath:

Command Name Parameters Description
M (absolute)
m (relative)
moveto (x y)+ Start a new sub-path at the given (x,y) coordinates. M (uppercase) indicates that absolute coordinates will follow; m (lowercase) indicates that relative coordinates will follow. If a moveto is followed by multiple pairs of coordinates, the subsequent pairs are treated as implicit lineto commands. Hence, implicit lineto commands will be relative if the moveto is relative, and absolute if the moveto is absolute. If a relative moveto (m) appears as the first element of the path, then it is treated as a pair of absolute coordinates. In this case, subsequent pairs of coordinates are treated as relative even though the initial moveto is interpreted as an absolute moveto.

When a relative m command is used, the position moved to is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb).

8.3.4. The "closepath" command

The "closepath" (Z or z) must end the current subpath by connecting it back to its initial point in either of two ways:

  1. If the previous command is complete, that is that all the required coordinate data has been supplied, then an automatic straight line must be drawn from the current point to the initial point of the current subpath. This path segment may be of zero length.
  2. If the previous command is a "lineto", "curveto", "smooth curveto", "quadratic Bézier curveto", "smooth quadratic Bézier curveto", or "elliptical arc", that is missing required coordinate data, then this is a segment-completing close path command. No additional path segment is generated by the command; instead, the initial point for this subpath must be used in place of each missing (x,y) coordinate to complete the previous segment.
Command Name Parameters Description
Z or
z
closepath (none) Close the current subpath by connecting it back to the current subpath's initial point (see prose above). Since the Z and z commands take no parameters, they have an identical effect.

SVG 2 adds the ability to fill in missing coordinate data with the Z or z command to avoid the need to add a zero length (or very short in the case of relative paths with rounding errors) path segment to close a subpath. This can effect the number of markers drawn and their orientation at the beginning/end of a closed subpath.

The use of Z or z to replace missing coordinate data with the coordinate of the initial point in a subpath was resolved at the Sydney (2015) meeting.

A closed subpath must be closed with a "closepath" command, this "joins" the first and last path segments. Any other path is an open subpath.

A closed subpath differs in behavior from an open subpath whose final coordinate is the initial point of the subpath. The first and last path segments of an open subpath will not be joined, even when the final coordinate of the last path segment is the initial point of the subpath. This will result in the first and last path segments being capped using the current value of stroke-linecap rather than joined using the current value of stroke-linejoin.

If a "closepath" is followed immediately by a "moveto", then the "moveto" identifies the start point of the next subpath. If a "closepath" is followed immediately by any other command, then the next subpath must start at the same initial point as the current subpath.

The current bearing does not affect a z command.

Examples:

8.3.5. The "lineto" commands

The various "lineto" commands draw straight lines from the current point to a new point:

Command Name Parameters Description
L (absolute)
l (relative)
lineto (x y)+ Draw a line from the current point to the given (x,y) coordinate which becomes the new current point. L (uppercase) indicates that absolute coordinates will follow; l (lowercase) indicates that relative coordinates will follow. A number of coordinates pairs may be specified to draw a polyline. At the end of the command, the new current point is set to the final set of coordinates provided.
H (absolute)
h (relative)
horizontal lineto x+ Draws a horizontal line from the current point. H (uppercase) indicates that absolute coordinates will follow; h (lowercase) indicates that relative coordinates will follow. Multiple x values can be provided (although usually this doesn't make sense). An H or h command is equivalent to an L or l command with 0 specified for the y coordinate. At the end of the command, the new current point is taken from the final coordinate value.
V (absolute)
v (relative)
vertical lineto y+ Draws a vertical line from the current point. V (uppercase) indicates that absolute coordinates will follow; v (lowercase) indicates that relative coordinates will follow. Multiple y values can be provided (although usually this doesn't make sense). A V or v command is equivalent to an L or l command with 0 specified for the x coordinate. At the end of the command, the new current point is taken from the final coordinate value.

When a relative l command is used, the end point of the line is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb).

When a relative h command is used, the end point of the line is (cpx + x cos cb, cpy + x sin cb). This means that an h command with a positive x value draws a line in the direction of the current bearing. When the current bearing is 0, this is a horizontal line in the direction of the positive x-axis.

When there is a non-zero bearing, a mnemonic for the h command could be "head this distance at the current bearing", rather than "draw a horizontal line".

When a relative v command is used, the end point of the line is (cpx + y sin cb, cpy + y cos cb).

8.3.6. The cubic Bézier curve commands

The cubic Bézier commands are as follows:

Command Name Parameters Description
C (absolute)
c (relative)
curveto (x1 y1 x2 y2 x y)+ Draws a cubic Bézier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve. C (uppercase) indicates that absolute coordinates will follow; c (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier.
S (absolute)
s (relative)
shorthand/smooth curveto (x2 y2 x y)+ Draws a cubic Bézier curve from the current point to (x,y). The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not an C, c, S or s, assume the first control point is coincident with the current point.) (x2,y2) is the second control point (i.e., the control point at the end of the curve). S (uppercase) indicates that absolute coordinates will follow; s (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier.

When a relative c or s command is used, each of the relative coordinate pairs is computed as for those in an m command. For example, the final control point of the curve of both commands is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb).

Example cubic01 shows some simple uses of cubic Bézier commands within a path. The example uses an internal CSS style sheet to assign styling properties. Note that the control point for the "S" command is computed automatically as the reflection of the control point for the previous "C" command relative to the start point of the "S" command.

<?xml version="1.0" standalone="no"?>
<svg width="5cm" height="4cm" viewBox="0 0 500 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <title>Example cubic01- cubic Bézier commands in path data</title>
  <desc>Picture showing a simple example of path data
        using both a "C" and an "S" command,
        along with annotations showing the control points
        and end points</desc>
  <style type="text/css"><![CDATA[
    .Border { fill:none; stroke:blue; stroke-width:1 }
    .Connect { fill:none; stroke:#888888; stroke-width:2 }
    .SamplePath { fill:none; stroke:red; stroke-width:5 }
    .EndPoint { fill:none; stroke:#888888; stroke-width:2 }
    .CtlPoint { fill:#888888; stroke:none }
    .AutoCtlPoint { fill:none; stroke:blue; stroke-width:4 }
    .Label { font-size:22; font-family:Verdana }
  ]]></style>

  <rect class="Border" x="1" y="1" width="498" height="398" />

  <polyline class="Connect" points="100,200 100,100" />
  <polyline class="Connect" points="250,100 250,200" />
  <polyline class="Connect" points="250,200 250,300" />
  <polyline class="Connect" points="400,300 400,200" />
  <path class="SamplePath" d="M100,200 C100,100 250,100 250,200
                                       S400,300 400,200" />
  <circle class="EndPoint" cx="100" cy="200" r="10" />
  <circle class="EndPoint" cx="250" cy="200" r="10" />
  <circle class="EndPoint" cx="400" cy="200" r="10" />
  <circle class="CtlPoint" cx="100" cy="100" r="10" />
  <circle class="CtlPoint" cx="250" cy="100" r="10" />
  <circle class="CtlPoint" cx="400" cy="300" r="10" />
  <circle class="AutoCtlPoint" cx="250" cy="300" r="9" />
  <text class="Label" x="25" y="70">M100,200 C100,100 250,100 250,200</text>
  <text class="Label" x="325" y="350"
        style="text-anchor:middle">S400,300 400,200</text>
</svg>
Example cubic01 — cubic Bézier comamnds in path data

Example cubic01

View this example as SVG (SVG-enabled browsers only)

The following picture shows some how cubic Bézier curves change their shape depending on the position of the control points. The first five examples illustrate a single cubic Bézier path segment. The example at the lower right shows a "C" command followed by an "S" command.

Example cubic02 - cubic Bézier commands in path data

View this example as SVG (SVG-enabled browsers only)
 

8.3.7. The quadratic Bézier curve commands

The quadratic Bézier commands are as follows:

Command Name Parameters Description
Q (absolute)
q (relative)
quadratic Bézier curveto (x1 y1 x y)+ Draws a quadratic Bézier curve from the current point to (x,y) using (x1,y1) as the control point. Q (uppercase) indicates that absolute coordinates will follow; q (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier.
T (absolute)
t (relative)
Shorthand/smooth quadratic Bézier curveto (x y)+ Draws a quadratic Bézier curve from the current point to (x,y). The control point is assumed to be the reflection of the control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not a Q, q, T or t, assume the control point is coincident with the current point.) T (uppercase) indicates that absolute coordinates will follow; t (lowercase) indicates that relative coordinates will follow. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier.

When a relative q or t command is used, each of the relative coordinate pairs is computed as for those in an m command. For example, the final control point of the curve of both commands is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb).

Example quad01 shows some simple uses of quadratic Bézier commands within a path. Note that the control point for the "T" command is computed automatically as the reflection of the control point for the previous "Q" command relative to the start point of the "T" command.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="6cm" viewBox="0 0 1200 600"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <title>Example quad01 - quadratic Bézier commands in path data</title>
  <desc>Picture showing a "Q" a "T" command,
        along with annotations showing the control points
        and end points</desc>
  <rect x="1" y="1" width="1198" height="598"
        fill="none" stroke="blue" stroke-width="1" />

  <path d="M200,300 Q400,50 600,300 T1000,300"
        fill="none" stroke="red" stroke-width="5"  />
  <!-- End points -->
  <g fill="black" >
    <circle cx="200" cy="300" r="10"/>
    <circle cx="600" cy="300" r="10"/>
    <circle cx="1000" cy="300" r="10"/>
  </g>
  <!-- Control points and lines from end points to control points -->
  <g fill="#888888" >
    <circle cx="400" cy="50" r="10"/>
    <circle cx="800" cy="550" r="10"/>
  </g>
  <path d="M200,300 L400,50 L600,300 
           L800,550 L1000,300"
        fill="none" stroke="#888888" stroke-width="2" />
</svg>
Example quad01 — quadratic Bézier commands in path data

Example quad01

View this example as SVG (SVG-enabled browsers only)

8.3.8. The elliptical arc curve commands

SVG 2 Requirement: Make it simpler to draw arcs in SVG path syntax.
Resolution: Make arcs in paths easier.
Purpose: To make it easier for authors to write path data with arcs by hand.
Owner: Cameron (ACTION-3151)

The elliptical arc commands are as follows:

Command Name Parameters Description
A (absolute)
a (relative)
elliptical arc (rx ry x-axis-rotation large-arc-flag sweep-flag x y)+ Draws an elliptical arc from the current point to (x, y). The size and orientation of the ellipse are defined by two radii (rx, ry) and an x-axis-rotation, which indicates how the ellipse as a whole is rotated, in degrees, relative to the current coordinate system. The center (cx, cy) of the ellipse is calculated automatically to satisfy the constraints imposed by the other parameters. large-arc-flag and sweep-flag contribute to the automatic calculations and help determine how the arc is drawn.

When a relative a command is used, the end point of the arc is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb). The effective value of the x-axis-rotation parameter is also affected by the current bearing: it is computed as x-axis-rotation + cb.

Example arcs01 shows some simple uses of arc commands within a path.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="5.25cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <title>Example arcs01 - arc commands in path data</title>
  <desc>Picture of a pie chart with two pie wedges and
        a picture of a line with arc blips</desc>
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="1" />

  <path d="M300,200 h-150 a150,150 0 1,0 150,-150 z"
        fill="red" stroke="blue" stroke-width="5" />
  <path d="M275,175 v-150 a150,150 0 0,0 -150,150 z"
        fill="yellow" stroke="blue" stroke-width="5" />

  <path d="M600,350 l 50,-25 
           a25,25 -30 0,1 50,-25 l 50,-25 
           a25,50 -30 0,1 50,-25 l 50,-25 
           a25,75 -30 0,1 50,-25 l 50,-25 
           a25,100 -30 0,1 50,-25 l 50,-25"
        fill="none" stroke="red" stroke-width="5"  />
</svg>
Example arcs01 — arc commands in path data

Example arcs01

View this example as SVG (SVG-enabled browsers only)

The elliptical arc command draws a section of an ellipse which must meet the following constraints:

For most situations, there are actually four different arcs (two different ellipses, each with two different arc sweeps) that satisfy these constraints. large-arc-flag and sweep-flag indicate which one of the four arcs are drawn, as follows:

The following illustrates the four combinations of large-arc-flag and sweep-flag and the four different arcs that will be drawn based on the values of these flags. For each case, the following path data command was used:

<path d="M 125,75 a100,50 0 ?,? 100,50"
      style="fill:none; stroke:red; stroke-width:6"/>

where "?,?" is replaced by "0,0" "0,1" "1,0" and "1,1" to generate the four possible cases.

Illustration of flags in arc commands

View this example as SVG (SVG-enabled browsers only)

Refer to Elliptical arc implementation notes for detailed implementation notes for the path data elliptical arc commands.

8.3.9. The bearing commands

The bearing commands are at risk, with no known implementations.

The bearing commands (B or b) set the current bearing, which influences the orientation of subsequent relative path commands:

Command Name Parameters Description
B (absolute)
b (relative)
bearing angle+ Sets the current bearing. The parameter is an angle in degrees, where 0 indicates the direction of the positive x-axis. B (uppercase) sets the current bearing to the specified angle; b (lowercase) sets the current bearing to be the angle of the tangent at the end of the preceding path command plus the specified angle. The current point is unaffected. Although multiple parameters may be specified, this usually will not be useful, as they could be combined into a single angle value.

At the beginning of a path, the current bearing is 0, which points in the direction of the positive x-axis. The current bearing remains unchanged until a B or b command is encountered. Since the relative b command sets the current bearing relative to the tangent at the end of the preceding path command, it is possible to set the bearing to that tangent by using "b 0".

The example below shows how bearing commands can be used to draw a regular pentagon.

<svg xmlns="http://www.w3.org/2000/svg"
     width="300" height="100" viewBox="0 0 300 100">

  <path fill="#eee"
        stroke="deeppink" stroke-width="8px" stroke-linejoin="round"
        d="M 150,10
           B 36 h 47
           b 72 h 47
           b 72 h 47
           b 72 h 47 z"/>

</svg>
Image showing the use of the bearing command.

Bearing commands can be used to position the end points of the sides of a regular polygon without having to use trigonometry to calculate them based on the polygon's interior angles.

8.3.10. The grammar for path data

SVG path data matches the following EBNF grammar.

svg_path::= wsp* moveto? (moveto drawto_command*)?

drawto_command::=
    moveto
    | closepath
    | lineto
    | horizontal_lineto
    | vertical_lineto
    | curveto
    | smooth_curveto
    | quadratic_bezier_curveto
    | smooth_quadratic_bezier_curveto
    | elliptical_arc
    | bearing

moveto::=
    ( "M" | "m" ) wsp* coordinate_pair_sequence wsp* closepath?

closepath::= 
    ("Z" | "z")

lineto::=
    ("L"|"l") wsp* (coordinate_pair_sequence | closepath)

horizontal_lineto::=
    ("H"|"h") wsp* coordinate_sequence

vertical_lineto::=
    ("V"|"v") wsp* coordinate_sequence

curveto::=
    ("C"|"c") wsp* (curveto_coordinate_sequence | (coordinate_pair_sequence? closepath))

curveto_coordinate_sequence::=
    coordinate_pair_triplet
    | (coordinate_pair_triplet comma_wsp? curveto_coordinate_sequence)

smooth_curveto::=
    ("S"|"s") wsp* (smooth_curveto_coordinate_sequence
    | (coordinate_pair_sequence? closepath))

smooth_curveto_coordinate_sequence::=
    coordinate_pair_double
    | (coordinate_pair_double comma_wsp? smooth_curveto_coordinate_sequence)

quadratic_bezier_curveto::=
    ("Q"|"q") wsp*
    (quadratic_bezier_curveto_coordinate_sequence | (coordinate_pair_sequence? closepath))

quadratic_bezier_curveto_coordinate_sequence::=
    coordinate_pair_double
    | (coordinate_pair_double comma_wsp? quadratic_bezier_curveto_coordinate_sequence)

smooth_quadratic_bezier_curveto::=
    ("T"|"t") wsp* (coordinate_pair_sequence | closepath)

elliptical_arc::=
    ( "A" | "a" ) wsp*
    (elliptical_arc_argument_sequence
    | (elliptical_arc_argument_sequence? elliptical_arc_closing_argument))

elliptical_arc_argument_sequence::=
    elliptical_arc_argument
    | (elliptical_arc_argument comma_wsp? elliptical_arc_argument_sequence)

elliptical_arc_argument::=
    number comma_wsp? number comma_wsp? number comma_wsp
    flag comma_wsp? flag comma_wsp? coordinate_pair

elliptical_arc_closing_argument::=
    number comma_wsp? number comma_wsp? number comma_wsp
    flag comma_wsp? flag comma_wsp? closepath

bearing::=
    ( "B" | "b" ) wsp* bearing_argument_sequence

bearing_argument_sequence::=
    number | (number comma_wsp? bearing_argument_sequence)

coordinate_pair_double::=
    coordinate_pair comma_wsp? coordinate_pair

coordinate_pair_triplet::=
    coordinate_pair comma_wsp? coordinate_pair comma_wsp? coordinate_pair

coordinate_pair_sequence::=
    coordinate_pair | (coordinate_pair comma_wsp? coordinate_pair_sequence)

coordinate_sequence::=
    coordinate | (coordinate comma_wsp? coordinate_sequence)

coordinate_pair::= coordinate comma_wsp? coordinate

coordinate::= sign? number

sign::= "+"|"-"
number ::= ([0-9])+
flag::=("0"|"1")
comma_wsp::=(wsp+ ","? wsp*) | ("," wsp*)
wsp ::= (#x9 | #x20 | #xA | #xC | #xD)

The processing of the EBNF must consume as much of a given EBNF production as possible, stopping at the point when a character is encountered which no longer satisfies the production. Thus, in the string "M 100-200", the first coordinate for the "moveto" consumes the characters "100" and stops upon encountering the minus sign because the minus sign cannot follow a digit in the production of a "coordinate". The result is that the first coordinate will be "100" and the second coordinate will be "-200".

Similarly, for the string "M 0.6.5", the first coordinate of the "moveto" consumes the characters "0.6" and stops upon encountering the second decimal point because the production of a "coordinate" only allows one decimal point. The result is that the first coordinate will be "0.6" and the second coordinate will be ".5".

Note that the EBNF allows the path data string in the d property to be empty. This is not an error, instead it disables rendering of the path. Rendering is also disabled when the d property has the value none.

If path data not matching the grammar is encountered, then the path data is in error (see Error Handling).

8.4. Path directionality

Some features, such as the orientation of markers and the shapes of line caps, are defined in terms of the direction of the path at a given distance along the path or at the start or end of an individual segment.

The direction of a path at a specified distance along the path is defined as follows:

The direction at the start of a path segment is defined as follows:

The direction at the end of a path segment is defined as follows:

8.5. Implementation notes

8.5.1. Error handling in path data

A conforming SVG user agent must implement path rendering as follows:

8.6. Distance along a path

Various operations, including text on a path and motion animation and various stroke operations, require that the user agent compute the distance along the geometry of a graphics element, such as a path.

Exact mathematics exist for computing distance along a path, but the formulas are highly complex and require substantial computation. It is recommended that authoring products and user agents employ algorithms that produce as precise results as possible; however, to accommodate implementation differences and to help distance calculations produce results that approximate author intent, the pathLength attribute can be used to provide the author's computation of the total length of the path so that the user agent can scale distance-along-a-path computations by the ratio of pathLength to the user agent's own computed value for total path length.

A "moveto" or "bearing" operation within a path element is defined to have zero length. Only the various "lineto", "curveto" and "arcto" commands contribute to path length calculations.

8.6.1. The ‘pathLength’ attribute

Name Value Initial value Animatable
pathLength <number> (none) yes

The author's computation of the total length of the path, in user units. This value is used to calibrate the user agent's own distance-along-a-path calculations with that of the author. The user agent will scale all distance-along-a-path computations by the ratio of pathLength to the user agent's own computed value for total path length. pathLength potentially affects calculations for text on a path, motion animation and various stroke operations.

A value of zero is valid and must be treated as a scaling factor of infinity. A value of zero scaled infinitely must remain zero, while any value greater than zero must become +Infinity.

A negative value is an error (see Error handling).

8.7. DOM interfaces

8.7.1. Interface SVGPathElement

An SVGPathElement object represents a path in the DOM.

interface SVGPathElement : SVGGeometryElement {

};
SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 9: Basic Shapes

9.1. Introduction and definitions

basic shape
shape
shape elements
A graphics element that is defined by some combination of straight lines and curves. Specifically: circle, ellipse, line, mesh, path, polygon, polyline and rect.

SVG contains the following set of basic shape elements:

Mathematically, these shape elements are equivalent to a path element that would construct the same shape. The basic shapes may be stroked, filled and used as clip paths. All of the properties available for path elements also apply to the basic shapes.

The equivalent path and algorithm to compute the stroke for each shape are defined in the shape sections below.

9.2. The ‘rect’ element

The rect element defines a rectangle which is axis-aligned with the current local coordinate system. Rounded rectangles can be achieved by setting non-zero values for the rx and ry geometric properties.

rect
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script, style
Attributes:
Geometry properties:
DOM Interfaces:

The x and y coordinates refer to the left and top edges of the rectangle, in the current user coordinate system.

The width and height properties define the overall width and height of the rectangle. A negative value for either property is illegal and must be ignored as a parsing error. A computed value of zero for either dimension disables rendering of the element.

For rounded rectangles, the computed values of the rx and ry properties define the x- and y-axis radii of elliptical arcs used to round off the corners of the rectangle. The arc are always symmetrical along both horizontal and vertical axis; to create a rectangle with uneven corner rounding, define the shape explicitly with a path. A negative value for either property is illegal and must be ignored as a parsing error. A computed value of zero for either dimension, or a computed value of auto for both dimensions, results in a rectangle without corner rounding.

The used values for the x- and y-axis rounded corner radii may be determined implicitly from the other dimension (using the auto value), and are also subject to clamping so that the lengths of the straight segments of the rectangle are never negative. The used values for rx and ry are determined from the computed values by following these steps in order:

  1. If both rx and ry have a computed value of auto (since auto is the initial value for both properties, this will also occur if neither are specified by the author or if all author-supplied values are invalid), then the used value of both rx and ry is 0. (This will result in square corners.)
  2. Otherwise, convert specified values to absolute values as follows:
    1. If rx is set to a length value or a percentage, but ry is auto, calculate an absolute length equivalent for rx, resolving percentages against the used width of the rectangle; the absolute value for ry is the same.
    2. If ry is set to a length value or a percentage, but rx is auto, calculate the absolute length equivalent for ry, resolving percentages against the used height of the rectangle; the absolute value for rx is the same.
    3. If both rx and ry were set to lengths or percentages, absolute values are generated individually, resolving rx percentages against the used width, and resolving ry percentages against the used height.
  3. Finally, apply clamping to generate the used values:
    1. If the absolute rx (after the above steps) is greater than half of the used width, then the used value of rx is half of the used width.
    2. If the absolute ry (after the above steps) is greater than half of the used height, then the used value of ry is half of the used height.
    3. Otherwise, the used values of rx and ry are the absolute values computed previously.

Mathematically, a rect element is mapped to an equivalent path element as follows, after generating absolute used values x, y, width, height, rx, and rx in user units for the local coordinate system, for each of the equivalent geometric properties following the rules specified above and in Units:

  1. perform an absolute moveto operation to location (x+rx,y);
  2. perform an absolute horizontal lineto with parameter x+width-rx;
  3. if both rx and ry are greater than zero, perform an absolute elliptical arc operation to coordinate (x+width,y+ry), where rx and ry are used as the equivalent parameters to the elliptical arc command, the x-axis-rotation and large-arc-flag are set to zero, the sweep-flag is set to one;
  4. perform an absolute vertical lineto parameter y+height-ry;
  5. if both rx and ry are greater than zero, perform an absolute elliptical arc operation to coordinate (x+width-rx,y+height), using the same parameters as previously;
  6. perform an absolute horizontal lineto parameter x+rx;
  7. if both rx and ry are greater than zero, perform an absolute elliptical arc operation to coordinate (x,y+height-ry), using the same parameters as previously;
  8. perform an absolute vertical lineto parameter y+ry
  9. if both rx and ry are greater than zero, perform an absolute elliptical arc operation with a segment-completing close path command, using the same parameters as previously.

Path decomposition resolved during teleconference on June 3rd, 2013.

Example rect01 shows a rectangle with sharp corners. The rect element is filled with yellow and stroked with navy.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example rect01 - rectangle with sharp corners</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2"/>

  <rect x="400" y="100" width="400" height="200"
        fill="yellow" stroke="navy" stroke-width="10"  />
</svg>
Example rect01 — rectangle with sharp corners

Example rect01

View this example as SVG (SVG-enabled browsers only)

Example rect02 shows two rounded rectangles. The rx specifies how to round the corners of the rectangles. Note that since no value has been specified for the ry attribute, the used value will be derived from the rx attribute.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example rect02 - rounded rectangles</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2"/>

  <rect x="100" y="100" width="400" height="200" rx="50"
        fill="green" />

  <g transform="translate(700 210) rotate(-30)">
    <rect x="0" y="0" width="400" height="200" rx="50"
          fill="none" stroke="purple" stroke-width="30" />
  </g>
</svg>
Example rect02 — rounded rectangles expressed in user coordinates

Example rect02

View this example as SVG (SVG-enabled browsers only)

9.3. The ‘circle’ element

The circle element defines a circle based on a center point and a radius.

circle
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script, style
Attributes:
Geometry properties:
DOM Interfaces:

The cx and cy attributes define the coordinates of the center of the circle.

The r attribute defines the radius of the circle. A negative value for either property is illegal and must be ignored as a parsing error.

Mathematically, a circle element is mapped to an equivalent path element that consists of four elliptical arc segments, each covering a quarter of the circle. The path begins at the "3 o'clock" point on the radius and proceeds in a clock-wise direction (before any transformations). The rx and ry parameters to the arc commands are both equal to the used value of the r property, after conversion to local user units, while the x-axis-rotation, the large-arc-flag, and the sweep-flag are all set to zero. The coordinates are computed as follows, where cx, cy, and r are the used values of the equivalent properties, converted to user units:

  1. A move-to command to the point cx+r,cy;
  2. arc to cx,cy+r;
  3. arc to cx-r,cy;
  4. arc to cx,cy-r;
  5. arc with a segment-completing close path command.

Path decomposition resolved during teleconference on June 3rd, 2013.

Example circle01 consists of a circle element that is filled with red and stroked with blue.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example circle01 - circle filled with red and stroked with blue</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2"/>

  <circle cx="600" cy="200" r="100"
        fill="red" stroke="blue" stroke-width="10"  />
</svg>
Example circle01 — circle filled with red and stroked with blue

Example circle01

View this example as SVG (SVG-enabled browsers only)

9.4. The ‘ellipse’ element

The ellipse element defines an ellipse which is axis-aligned with the current local coordinate system based on a center point and two radii.

ellipse
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script, style
Attributes:
Geometry properties:
DOM Interfaces:

The cx and cy coordinates define the center of the ellipse.

The rx and ry properties define the x- and y-axis radii of the ellipse. A negative value for either property is illegal and must be ignored as a parsing error. A computed value of zero for either dimension, or a computed value of auto for both dimensions, disables rendering of the element.

An auto value for either rx or ry is converted to a used value following the rules given above for rectangles, except without any clamping based on width and height. Effectively, an auto value creates a circular shape whose radius is defined by a value expressed solely in one dimension, allowing you to create circles with radii defined as a percentage of the coordinate system width (a percantage value for rx and an auto value for ry) or height (an auto value for rx and a percantage value for ry).

New in SVG 2. The auto value for rx and ry was added to allow consistent parsing of these properties for both ellipses and rectangles. Previously, if either rx or ry was unspecified, the ellipse would not render.

Mathematically, an ellipse element is mapped to an equivalent path element that consists of four elliptical arc segments, each covering a quarter of the ellipse. The path begins at the "3 o'clock" point on the radius and proceeds in a clock-wise direction (before any transformation). The rx and ry parameters to the arc commands are the used values of the equivalent properties after conversion to local user units, while the x-axis-rotation, the large-arc-flag, and the sweep-flag are all set to zero. The coordinates are computed as follows, where cx, cy, rx, and ry are the used values of the equivalent properties, converted to user units:

  1. A move-to command to the point cx+rx,cy;
  2. arc to cx,cy+ry;
  3. arc to cx-rx,cy;
  4. arc to cx,cy-ry;
  5. arc with a segment-completing close path command.

Path decomposition resolved during teleconference on June 3rd, 2013.

Example ellipse01 below specifies the coordinates of the two ellipses in the user coordinate system established by the viewBox attribute on the svg element and the transform property on the g and ellipse elements. Both ellipses use the default values of zero for the cx and cy attributes (the center of the ellipse). The second ellipse is rotated.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example ellipse01 - examples of ellipses</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2" />

  <g transform="translate(300 200)">
    <ellipse rx="250" ry="100"
          fill="red"  />
  </g>

  <ellipse transform="translate(900 200) rotate(-30)" 
        rx="250" ry="100"
        fill="none" stroke="blue" stroke-width="20"  />

</svg>
Example ellipse01 — ellipses expressed in user coordinates

Example ellipse01

View this example as SVG (SVG-enabled browsers only)

9.5. The ‘line’ element

The line element defines a line segment that starts at one point and ends at another.

line
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script, style
Attributes:
DOM Interfaces:

Attribute definitions:

Name Value Initial value Animatable
x1, y1 <length> | <percentage> | <number> 0 yes
The x- and y-axis coordinates of the start of the line.
Name Value Initial value Animatable
x2, y2 <length> | <percentage> | <number> 0 yes
The x- and y-axis coordinates of the end of the line.

A future specification may convert the x1, y1, x2, and y2 attributes to geometric properties. Currently, they can only be specified via element attributes, and not CSS.

Mathematically, a line element can be mapped to an equivalent path element as follows, after converting coordinates into local coordinate system user units according to Units to generate values x1, y1, x2, and y2:

Because line elements are single lines and thus are geometrically one-dimensional, they have no interior; thus, line elements are never filled (see the fill property).

Example line01 below specifies the coordinates of the five lines in the user coordinate system established by the viewBox attribute on the svg element. The lines have different thicknesses.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example line01 - lines expressed in user coordinates</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2" />

  <g stroke="green" >
    <line x1="100" y1="300" x2="300" y2="100"
            stroke-width="5"  />
    <line x1="300" y1="300" x2="500" y2="100"
            stroke-width="10"  />
    <line x1="500" y1="300" x2="700" y2="100"
            stroke-width="15"  />
    <line x1="700" y1="300" x2="900" y2="100"
            stroke-width="20"  />
    <line x1="900" y1="300" x2="1100" y2="100"
            stroke-width="25"  />
  </g>
</svg>
Example line01 — lines expressed in user coordinates

Example line01

View this example as SVG (SVG-enabled browsers only)

9.6. The ‘polyline’ element

The polyline element defines a set of connected straight line segments. Typically, polyline elements define open shapes.

polyline
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script, style
Attributes:
DOM Interfaces:

Attribute definitions:

Name Value Initial value Animatable
points <points> (none) yes

where:

<points> =
[[<number> ,? <number> ]# ]+

The points that make up the polyline. All coordinate values are in the user coordinate system.

If an odd number of coordinates is provided, then the element is in error, with the same user agent behavior as occurs with an incorrectly specified path element. In such error cases the user agent will drop the last, odd coordinate and otherwise render the shape.

The initial value, (none), indicates that the polyline element is valid but does not render.

A future specification may convert the points attribute to a geometric property. Currently, it can only be specified via an element attribute, and not CSS.

Mathematically, a polyline element can be mapped to an equivalent path element as follows:

Example polyline01 below specifies a polyline in the user coordinate system established by the viewBox attribute on the svg element.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example polyline01 - increasingly larger bars</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2" />

  <polyline fill="none" stroke="blue" stroke-width="10" 
            points="50,375
                    150,375 150,325 250,325 250,375
                    350,375 350,250 450,250 450,375
                    550,375 550,175 650,175 650,375
                    750,375 750,100 850,100 850,375
                    950,375 950,25 1050,25 1050,375
                    1150,375" />
</svg>
Example polyline01 — increasingly larger bars

Example polyline01

View this example as SVG (SVG-enabled browsers only)

9.7. The ‘polygon’ element

The polygon element defines a closed shape consisting of a set of connected straight line segments.

polygon
Categories:
Graphics element, renderable element, shape element
Content model:
Any number of the following elements, in any order:clipPath, marker, mask, script, style
Attributes:
DOM Interfaces:

Attribute definitions:

Name Value Initial value Animatable
points <points> (none) yes

The points that make up the polygon. All coordinate values are in the user coordinate system.

If an odd number of coordinates is provided, then the element is in error, with the same user agent behavior as occurs with an incorrectly specified path element.

The initial value, (none), indicates that the polygon element is valid, but does not render.

A future specification may convert the points attribute to a geometric property. Currently, it can only be specified via an element attribute, and not CSS.

Mathematically, a polygon element can be mapped to an equivalent path element as follows:

Example polygon01 below specifies two polygons (a star and a hexagon) in the user coordinate system established by the viewBox attribute on the svg element.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example polygon01 - star and hexagon</desc>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="1198" height="398"
        fill="none" stroke="blue" stroke-width="2" />

  <polygon fill="red" stroke="blue" stroke-width="10" 
            points="350,75  379,161 469,161 397,215
                    423,301 350,250 277,301 303,215
                    231,161 321,161" />
  <polygon fill="lime" stroke="blue" stroke-width="10" 
            points="850,75  958,137.5 958,262.5
                    850,325 742,262.6 742,137.5" />
</svg>
Example polygon01 — star and hexagon

Example polygon01

View this example as SVG (SVG-enabled browsers only)

9.8. The ‘mesh’ element

New in SVG 2.

Added by resolution at the Amsterdam Editor's Meeting in order to distinguish a mesh as a graphics element from mesh as a paint server. Behavior of overflow resolved on the last day.

The mesh element is a wrapper for a meshgradient paint server. Its geometry is determined by the referenced meshgradient.

mesh
Categories:
Graphics element, graphics referencing element, renderable element, shape element
Content model:
Any number of animation elements, descriptive elements, mask, clipPath, marker, script, and style elements, along with zero or one meshgradient element.
Attributes:
DOM Interfaces:
Name Value Initial value Animatable
href URL [URL] (none) yes

An URL reference to a meshgradient paint server.

Refer to the common handling defined for URL reference attributes.

If the href points to a valid meshgradient paint server, use that to render the mesh element; else if the first meshgradient child element is valid use that. Otherwise, the mesh will not render. A non-rendered mesh behaves the same as a path that has a d property with value none. Note: The fill property is not used to define the paint of a mesh, however a mesh may have a stroke and markers positioned using the equivalent path.

The equivalent path consists of a path constructed to match the outer shape of the referenced meshgradient. To construct the path, start at the first corner of the first meshpatch and then walk around the ouside of the meshgradient, adding each linear or Bézier segment encountered to the path. When the starting point is reached, the path should be closed with a segment-completing close path command.

A simple 2x2 patch mesh with a thick black stroke along
       the outside.  A red dot is at the upper left corner and an
       arrow showing the direction the path is constructed.

A 2x2 patch mesh gradient. The equivalent path is shown by the heavy black path. The path starting point is indicated by the red circle and the path direction by the arrow.

Meshes can fold over such that there may be painted regions that are outside the equivalent path. Painting of these regions is controlled by the overflow property. The initial value for this property is visible.

Two simple one patch meshes with thick black strokes along
       the outsides.

Single patch mesh gradient with different values of the overflow property. Left: overflow with value display. Right overflow with value hidden.

A mesh is always painted as if the fill rule is nonzero regardless of the value of the fill-rule property.

9.9. DOM interfaces

9.9.1. Interface SVGRectElement

An SVGRectElement object represents a rect element in the DOM.

interface SVGRectElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
  [SameObject] readonly attribute SVGAnimatedLength rx;
  [SameObject] readonly attribute SVGAnimatedLength ry;
};

The x, y, width, height, rx and ry IDL attributes reflect the computed values of the x, y, width, height, rx and ry properties and their corresponding presentation attributes, respectively.

9.9.2. Interface SVGCircleElement

An SVGCircleElement object represents a circle element in the DOM.

interface SVGCircleElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength cx;
  [SameObject] readonly attribute SVGAnimatedLength cy;
  [SameObject] readonly attribute SVGAnimatedLength r;
};

The cx, cy and r IDL attributes reflect the computed values of the cx, cy and y properties and their corresponding presentation attributes, respectively.

9.9.3. Interface SVGEllipseElement

An SVGEllipseElement object represents a ellipse element in the DOM.

interface SVGEllipseElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength cx;
  [SameObject] readonly attribute SVGAnimatedLength cy;
  [SameObject] readonly attribute SVGAnimatedLength rx;
  [SameObject] readonly attribute SVGAnimatedLength ry;
};

The cx, cy, rx and ry IDL attributes reflect the computed values of the cx, cy, rx and ry properties and their corresponding presentation attributes, respectively.

9.9.4. Interface SVGLineElement

The SVGLineElement interface corresponds to the line element.
interface SVGLineElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength x1;
  [SameObject] readonly attribute SVGAnimatedLength y1;
  [SameObject] readonly attribute SVGAnimatedLength x2;
  [SameObject] readonly attribute SVGAnimatedLength y2;
};

The x1, y1, x2 and y2 IDL attributes reflect the x1, y1, x2 and y2 content attributes, respectively

9.9.5. Interface SVGMeshElement

An SVGMeshElement object represents a mesh element in the DOM.

interface SVGMeshElement : SVGGeometryElement {};

SVGMeshElement implements SVGURIReference;

9.9.6. Interface SVGAnimatedPoints

The SVGAnimatedPoints interface is used to reflect a points attribute on a polygon or polyline element. It is mixed in to the SVGPolygonElement and SVGPolylineElement interfaces.

Note: In SVG 1.1 SE, the animatedPoints attribute represented the current animated value. In this version of SVG, it is simply an alias for points.

[NoInterfaceObject]
interface SVGAnimatedPoints {
  [SameObject] readonly attribute SVGPointList points;
  [SameObject] readonly attribute SVGPointList animatedPoints;
};

The points and animatedPoints IDL attributes represent the current non-animated value of the reflected attribute. On getting points or animatedPoints, an SVGPointList object is returned that reflects the base value of the reflected attribute.

9.9.7. Interface SVGPointList

The SVGPointList interface is a list interface whose elements are DOMPoint objects. An SVGPointList object represents a list of points.

interface SVGPointList {

  readonly attribute unsigned long length;
  readonly attribute unsigned long numberOfItems;

  void clear();
  DOMPoint initialize(DOMPoint newItem);
  getter DOMPoint getItem(unsigned long index);
  DOMPoint insertItemBefore(DOMPoint newItem, unsigned long index);
  DOMPoint replaceItem(DOMPoint newItem, unsigned long index);
  DOMPoint removeItem(unsigned long index);
  DOMPoint appendItem(DOMPoint newItem);
  setter void (unsigned long index, DOMPoint newItem);
};

The behavior of all of the interface members of SVGPointList are defined in List interfaces.

This specification imposes additional requirements on the behaviour of DOMPoint objects beyond those described in the the Geometry Interfaces specification, so that they can be used to reflect points attributes.

Every DOMPoint object operates in one of three modes. It can:

  1. reflect an element of the base value of a reflected animatable attribute (being exposed through the methods on the points member of an SVGAnimatedPoints),
  2. represent the current translation of a given svg element (being exposed through the currentTranslate member on SVGSVGElement), or
  3. be detached, which is the case for DOMPoint objects created using their constructor or with createSVGPoint.

A DOMPoint object can be associated with a particular element. The associated element is used to determine which element's content attribute to update if the object reflects an attribute. Unless otherwise described, a DOMPoint object is not associated with any element.

A DOMPoint object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown. When assigning to a read only DOMPoint's x, y, w or z IDL attribute, a NoModificationAllowedError must be thrown instead of updating the internal coordinate value.

Note that this applies only to the read-write DOMPoint interface; the DOMPointReadOnly interface, which is not used for reflecting the points attribute, will already throw an exception if an attempt is made to modify it.

When assigning to a writable DOMPoint's x, y, w or z IDL attribute, the following steps are run after updating the internal coordinate value:

  1. If the DOMPoint reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute using the SVGPointList that reflects the attribute's base value.
  2. Otherwise, if the DOMPoint represents the current translation of an svg element and that element is the outermost svg element, then:
    1. Let [a b c d e f] be the 2x3 matrix that represents the document's magnification and panning transform.
    2. Let x and y be the x and y coordinates of the DOMPoint object, respectively.
    3. Set the document's magnification and panning transform to [a 0 0 d x y].

9.9.8. Interface SVGPolylineElement

An SVGPolylineElement object represents a polyline element in the DOM.

interface SVGPolylineElement : SVGGeometryElement {
};

SVGPolylineElement implements SVGAnimatedPoints;

9.9.9. Interface SVGPolygonElement

An SVGPolygonElement object represents a polygon element in the DOM.

interface SVGPolygonElement : SVGGeometryElement {
};

SVGPolygonElement implements SVGAnimatedPoints;
SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 10: Text

10.1. Introduction

Text that is to be rendered as part of an SVG document fragment is specified using the text element. The text within a text element can be rendered:

The section Text layout gives an introduction to text layout. It is followed by sections covering content areas and the algorithm for laying out text within a content area. The specialized layout rules corresponding to text that is pre-formatted, auto-wrapped, and on a path are then addressed in individual sections.

Rules for text layout in SVG 1.1 are mostly defined within the SVG 1.1 specification. The rules mirror to a large extent those found in CSS. In SVG 2, the dependence on CSS is more explicit. In practice the resulting layout is the same. The change to directly relying on CSS specifications simplifies the SVG specification while making it more obvious that rendering agents can use the same code to render both text in HTML and in SVG. In particular, SVG 2 auto-wrapped text is based on CSS text layout.

SVG's text elements are rendered like other graphics elements. Thus, coordinate system transformations, painting, clipping and masking features apply to text elements in the same way as they apply to shapes such as paths and rectangles.

SVG text supports advanced typographic features including:

SVG text supports international text processing needs such as:

Multi-language SVG content is possible by substituting different text strings based on the user's preferred language.

The characters to be drawn are expressed as XML character data ([XML10], section 2.4) inside the text element. As a result:

For accessibility reasons, it is recommended that text that is included in a document have appropriate semantic markup to indicate its function. See SVG accessibility guidelines for more information.

10.1.1. Definitions

character
A character is an atomic unit of text as defined in XML [XML10].

Essentially, a tab, carriage return, line feed, or a Unicode character.

addressable character
A character that is addressable by text positioning attributes and SVG DOM text methods. Characters discarded during layout such as collapsed white space characters are not addressable.
typographic character
A unit of a writing system— such as a Latin alphabetic letter (including its diacritics), Hangul syllable, Chinese ideographic character, Myanmar syllable cluster— that is indivisible with respect to a particular typographic operation (line-breaking, first-letter effects, tracking, justification, vertical arrangement, etc.). See CSS Text Module Level 3, ([CSS3TEXT]).
font
A font represents an organized collection of glyphs in which the various glyph representations will share a particular appearance or styling.
glyph
A glyph represents a unit of rendered content within a font. Often, there is a one-to-one correspondence between characters to be drawn and corresponding glyphs (e.g., usually the character "A" is rendered using a single glyph), but other times multiple glyphs are used to render a single character (e.g., characters with accents) or a single glyph can be used to render multiple characters (e.g., ligatures). Typically, a glyph is defined by one or more shapes such as a path, possibly with additional information such as rendering hints that help a font engine to produce legible text in small sizes.
text content element
A text content element is an SVG element that causes a text string to be rendered onto the canvas. The SVG text content elements are: text, textPath and tspan.
text content child element
A text content child element is a text content element that is allowed as a descendant of another text content element. In SVG the text content child elements are: textPath and tspan.
text content block element
A text content block element is a text content element that serves as a standalone element for a unit of text, and which may optionally contain certain child text content elements (e.g. ‘tspan’). SVG 2 defines a single text content block element: text.
content area
The area in which the text is normally laid out. This is equivalent to the CSS content area. The actual region where text layout occurs may be smaller due to padding and/or exclusions.
wrapping context
One or more regions (shapes) to be excluded from the content area during text layout. This is the same as the CSS wrapping context.
wrapping area
The area in which the text is laid out after subtracting any padding or exclude areas (wrapping context). This is the same as the CSS wrapping area.
line box
The box used to layout a single line of text.

css3-box point to css3-text for the definition of 'line box'; but while css3-text uses the term, it does not define it.

inline-base direction
The primary direction in which content is ordered within a line or part of a line of text. It defines the start and end sides of a line or part of a line of text (relevant, for example to how the text-anchor property is applied). It is determined by the direction property. (Note: the ordering of characters in a line of text is primary controlled by the Unicode bidi algorithm and not the inline-base direction.)
block-flow direction
The direction in which line boxes are stacked. It is determined by the writing-mode property.
alignment point
The point on a typographic character that should be aligned with the current text position. It is determined by the glyph cell metrics and may depend on the script and inline-base direction.
current text position
The point in the current user space where the alignment point of the next typographic character to be rendered should be placed.
text chunk
An independent block of text in which all characters are positioned together. Each new absolute positioning adjustment (due to an x or y attribute, or forced line break) creates a new text chunk. Ligature substitution and bidi-reordering only occur within a text chunk. Text chunks are only relevant to pre-formatted text.
white space characters
The following characters are considered white space characters: U+0009 CHARACTER TABULATION, U+000C FORM FEED (FF), U+000D CARRIAGE RETURN (CR), U+000A LINE FEED (LF) and U+0020 SPACE.

10.1.2. Fonts and glyphs

A font consists of a collection of glyphs together with other information (collectively, the font tables) necessary to use those glyphs to present characters on some visual medium. The combination of the collection of glyphs and the font tables is called the font data.

A font may supply substitution and positioning tables that can be used by a formatter (shaper) to re-order, combine and position a sequence of glyphs to form one or more composite glyphs. The combining may be as simple as a ligature, or as complex as an indic syllable which combines, usually with some re-ordering, multiple consonants and vowel glyphs. The tables may be language dependent allowing the use of language appropriate letter forms.

When a glyph, simple or composite, represents an indivisible unit for typesetting purposes, it is know as a typographic character.

Ligatures are an important feature of advance text layout. Some ligatures are discretionary while others (e.g. in Arabic) are required. The following explicit rules apply to ligature formation:

SVG 2 Requirement: Include explicit support for Web Open Font Format (WOFF).
Resolution: We will mandate WOFF support in SVG 2.
Purpose: To allow access to full OpenType features for internationalization and advanced typography.
Owner: Chris (no action)
Status: Done

Proper text rendering may depend on using the same font as used during authoring. For this reason SVG requires support for downloadable fonts as defined in the Font Resources section of the CSS Fonts Module. In particular, support for the Web Open Font Format [WOFF] is required.

New in SVG 2, WOFF allows authors to provide the fonts needed to properly render their content. This includes ensuring that the fonts have the proper OpenType tables to support complex scripts, discretionary ligatures, swashes, old-style numbers, and so on. WOFF also allows the fonts to be compressed, subsetted, and include licensing information.

10.1.3. Glyph metrics and layout

Glyph selection and positioning is normally handled according to the rules of CSS. In some cases, however, the final layout of text in SVG requires knowledge of the geometry properties of individual glyphs.

The geometric font characteristics are expressed in a coordinate system based on the EM box. (The EM is a relative measure of the height of the glyphs in the font.) The box 1 EM high and 1 EM wide is called the design space. This space is given a geometric coordinates by sub-dividing the EM into a number of units per em.

Units per em is a font characteristic. A typical value for units per em is 1000 or 2048.

The coordinate space of the EM box is called the design space coordinate system. For scalable fonts, the curves and lines that are used to draw a glyph are represented using this coordinate system.

Most often, the (0,0) point in this coordinate system is positioned on the left edge of the EM box, but not at the bottom left corner. The Y coordinate of the bottom of a roman capital letter is usually zero. And the descenders on lowercase roman letters have negative coordinate values.

An 'M' inside an EM box showing the coordinate system, baseline,
	      ascent and descent.

An 'M' inside an Em box (blue square). The 'M' sits on the baseline (blue line). The origin of the coordinate system is shown by the small black circle.

SVG assumes that the font tables will provide at least three font characteristics: an ascent, a descent and a set of baseline-tables. The ascent is the distance to the top of the EM box from the (0,0) point of the font; the descent is the distance to the bottom of the EM box from the (0.0) point of the font. The baseline-table is explained below.

Within an OpenType font, for horizontal writing-modes, the ascent and descent are given by the sTypoAscender and sTypoDescender entries in the OS/2 table. For vertical writing-modes, the descent (the distance, in this case from the (0,0) point to the left edge of the glyph) is normally zero because the (0,0) point is on the left edge. The ascent for vertical writing-modes is either 1 em or is specified by the ideographic top baseline value in the OpenType Base table for vertical writing-modes.

Glyphs are positioned relative to a particular point on each glyph known as the alignment point. For horizontal writing-modes, the glyphs' alignment points are vertically aligned while for vertical writing-modes, they are horizontally aligned. The position of the alignment point depends on the script. For example, Western glyphs are aligned at the bottom of capital letters, northern indic glyphs are aligned at the top of a horizontal stroke near the top of the glyphs, and far-eastern glyphs are aligned either at the bottom or center of the glyph.

Within a script and within a line of text having a single font-size, the sequence of alignment points defines, in the inline-base direction, a geometric line called a baseline. Western and most other alphabetic and syllabic glyphs are aligned to an "alphabetic" baseline, the northern indic glyphs are aligned to a "hanging" baseline and the far-eastern glyphs are aligned to an "ideographic" baseline.

Baseline example in three different scripts.

Example baselines (red lines) in three different scripts. From left to right: alphabetic, hanging, ideographic. The EM box is shown in blue for the ideographic script.

As glyphs are sequentially placed along a baseline, the alignment point of a glyph is typically positioned at the current text position (some properties such as vertical-align may alter the positioning). After each glyph is placed, the current text position is advanced by the glyph's advance value (typically the width for horizontal text or height for vertical text) with any correction for kerning or other spacing adjustment as well as for new lines in pre-formatted or auto-wrapped text. The initial and final current text positions are used for alignment (e.g. when the text-anchor value is either 'middle' or 'end'). The glyph's advance is needed when placing text along a path.

Baseline example in three different scripts.

Example of font metrics. The blue boxes show the geometric boxes for the three glyphs. The labeled small circles show the current text position before glyph placement. The small square shows the final current text position after placing the last glyph. Note that the left side of the 'a' glyph's box is not aligned with the right side of the 'V' glyph's box due to kerning.

If a glyph does not provide explicit advance values corresponding to the current glyph orientation, then an appropriate approximation should be used. For vertical text, a suggested approximation is the em size.

The initial current text position is established by the x and y attributes on the text element or first rendered tspan element for pre-formatted text, or auto-wrapped text when the content area is determined by the inline-size property. For other auto-wrapped text, the initial current text position is determined by the position of the first rendered glyph after applying the CSS line wrapping algorithm.

A baseline-table specifies the position of one or more baselines in the design space coordinate system. The function of the baseline table is to facilitate the alignment of different scripts with respect to each other when they are mixed on the same text line. Because the desired relative alignments may depend on which script is dominant in a line (or block), there may be a different baseline table for each script. In addition, different alignment positions are needed for horizontal and vertical writing modes. Therefore, the font may have a set of baseline tables: typically, one or more for horizontal writing-modes and zero or more for vertical writing-modes.

Some fonts may not have values for the baseline tables. Heuristics are suggested for approximating the baseline tables in CSS Inline Layout Module Level 3[CSS3INLINE] when a given font does not supply baseline tables.

When a different font (or change in font size) is specified in the middle of a run of text, the dominant baseline determines the baseline used to align glyphs in the new font (new size) to those in the previous font. The dominant-baseline property is used to set the dominant baseline.

Alignment between an object relative to its parent is determined by the alignment baseline. It is normally the same baseline as the dominant baseline but by using the shorthand vertical-align property (preferred) or the longhand alignment-baseline another baseline can be chosen.

The dominant baseline can be temporarily shifted (as needed for superscripts or subscripts) by using either the shorthand vertical-align property (preferred) or the longhand baseline-shift property. Note that shifts can be nested, each shift added to the previous shift.

Examples of using the 'vertical-align' property. Left shows '[[z]]' where the inner brackets are smaller. Right shows 'x2' where the '2' is a superscript.

Examples of using the 'vertical-align' property. Left: 'vertical-align:mathematical' ('alignment-baseline:mathematical') is applied to the tspan containing '[z]'. The light-blue line shows the position of the mathematical baseline. Right: 'vertical-align:super' ('baseline-shift:super') applied to the tspan containing '2'. The light-blue lines indicate the shift in baseline.

SVG further assumes that for each glyph in the font data for a font, there are two width values, two alignment-baselines and two alignment points, one each for horizontal writing-modes and the other for vertical writing-modes. (Even though it is specified as a width, for vertical writing-modes the width is used in the vertical direction.) The inline-base direction position of the alignment point is on the start-edge of the glyph.

Additional information on baselines can be found in the CSS Inline Layout Module Level 3 specification. [CSS3INLINE] (Also see: CSS Writing Modes Level 3 specification. [CSSWRITINGMODES3])

SVG 2 Requirement: Support text aligned to different baselines.
Resolution: SVG 2 will support glyphs being aligned to different baselines, perhaps by using existing or improved CSS properties.
Purpose: To allow glyphs in horizontal text to have different vertical alignments for stylistic effects.
Owner: Chris (no action)
Status: Done

A single line of text is laid out inside a line box. Multi-line text is produced by stacking these boxes. The height of a line box is determined by finding the maximum ascent and the maximum descent of all the glyphs in a line of text after applying the effect of the line-height property. The width of a line box is normally the width of the containing text block. In SVG, when the containing text block does not have a fixed geometry (as with pre-formatted text), the line box tightly wraps the glyph boxes within the box.

The sentence 'A big word.' where 'big' is in a larger font.

Example of determining the height of a line box. First each glyph box (small light-blue boxes) is extended vertically above and below according to the line-height property. In this case the line-height property is 125%. The larger glyphs have a font-size of 96px so their extra height is 24px (25% of 96px). The extra height is evenly divided above and below resulting in the red boxes. (For clarity, all glyphs in the same inline element have been grouped together). The final line box (large light-blue box) is then found using the maximum extents of the red boxes above and below the baseline.

In order to support various international writing systems, line boxes may be orientated in a horizontal or vertical direction. Text within a vertical line box flows from top to bottom. Text within a horizontal line box may flow left-to-right (e.g., modern Latin scripts), right-to-left (e.g., Hebrew or Arabic), or a mixture of left-to-right and right-to-left (bidirectional text).

The processing model for bidirectional text is as follows. The user agent processes the characters which are provided in logical order (i.e., the order the characters appear in the original document). The user agent determines the set of independent blocks within each of which it should apply the Unicode bidirectional algorithm. Each text chunk represents an independent block of text. Additionally, any change in glyph orientation due to processing of the text-orientation or obsoleted glyph-orientation-vertical properties will subdivide the independent blocks of text further. After processing the Unicode bidirectional algorithm and properties direction and unicode-bidi on each of the independent text blocks, the user agent will have a potentially re-ordered list of characters which are now in left-to-right rendering order. Simultaneous with re-ordering of the characters, the dx, dy, and rotate attributes on the text and tspan elements are also re-ordered to maintain the original correspondence between characters and attribute values. While kerning or ligature processing might be font-specific, the preferred model is that kerning and ligature processing occurs between combinations of characters or glyphs after the characters have been re-ordered.

The orientation of line boxes as well as the direction in which they are stacked (block-flow direction) is determined by the writing-mode property. For horizontal text (writing-mode value horizontal-tb) line boxes are stacked from top to bottom. For vertical text, line boxes are stacked from right-to-left (writing-mode value vertical-rl) or left-to-right (writing-mode value vertical-lr).

10.2. The ‘text’ and ‘tspan’ elements

The text element defines a graphics element consisting of text. The tspan element within a text or another tspan element, allows one to switch the style and/or adjust the position of the rendered text inside the tspan element relative to the parent element.

The XML character data within the text and tspan elements, along with relevant attributes and properties, and character-to-glyph mapping tables within the font itself, define the glyphs to be rendered. The attributes and properties on the text and tspan elements indicate such things as the writing direction, font specification, and painting attributes which describe how exactly to render the characters. Subsequent sections of this chapter describe the relevant text-specific attributes and properties.

Since text and tspan elements are rendered using the same rendering methods as other graphics elements, all of the same painting features that apply to shapes such as paths and rectangles also apply to text and tspan elements. In addition, coordinate system transformations, clipping, and masking can be applied to the text element as a whole.

In CSS terms, the text element acts as a block element. The tspan, textPath, and a elements act as inline elements.

It is possible to apply a gradient, pattern, clipping path, mask or filter to text. When one of these facilities is applied to text and keyword 'objectBoundingBox' is used (see Object bounding box units) to specify a graphical effect relative to the "object bounding box", then the object bounding box units are computed relative to the entire text element in all cases, even when different effects are applied to different tspan elements within the same text element.

The text element renders its first glyph (after bidirectionality reordering) at the initial current text position (with possible adjustments due to the value of the text-anchor property or the text-align property). For pre-formatted text and for auto-wrapped text where the content area is determined by the inline-size property, the initial current text position is determined by the x and y values of the text or tspan element which contains the first rendered character. For auto-wrapped text in a shape or text on a path see the Auto-wrapped text or Text on a path sections, respectively, to determine the initial current text position. After the glyph(s) corresponding to the given character is (are) rendered, the current text position is updated for the next character. In the simplest case, the new current text position is the previous current text position plus the glyphs' advance value (horizontal or vertical). See text layout for a description of glyph placement and glyph advance.

The text string Hello, out there! is rendered onto the canvas using the Verdana font family with the glyphs filled with the color blue.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 1000 300"
     xmlns="http://www.w3.org/2000/svg" version="1.1">

  <text x="250" y="180"
        font-family="Verdana" font-size="64" fill="blue" >
    Hello, out there!
  </text>

</svg>
Image showing the blue text.

A tspan is used to change the styling of the word not.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 1000 300"
     xmlns="http://www.w3.org/2000/svg" version="1.1">

  <g font-family="Verdana" font-size="64" >
    <text x="160" y="180" fill="blue" >
      You are
      <tspan font-weight="bold" fill="red" >not</tspan>
      a banana.
    </text>
  </g>

</svg>
Blue text except the word 'not' is red.

Two tspan elements are repositioned horizontally and vertically using the x and y attributes. Because all the text is within a single text element, a user will be able to select through all the text and copy it to the system clipboard in user agents that support text selection and clipboard operations.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 1000 300"
     xmlns="http://www.w3.org/2000/svg" version="1.1">

  <g font-family="Verdana" font-size="64" >
    <text x="100" y="180" fill="blue" >
      But you
      <tspan dx="2em" dy="-50" font-weight="bold" fill="red" >
        are
      </tspan>
      <tspan dy="100">
        a peach!
      </tspan>
    </text>
  </g>

</svg>
A sentence with several shifted words.
text
Categories:
Graphics element, renderable element, text content element
Content model:
Any number of the following elements or character data, in any order:a, clipPath, marker, mask, script, style
Attributes:
DOM Interfaces:
SVG 2 Requirement: Allow transforms on tspan.
Resolution: SVG 2 will allow transforms on ‘tspan’.
Purpose: Align with other elements such as a which already allow transforms.
Owner: Cameron (no action)
Status: Done

This decission was reversed. See GitHub Issue 210. CSS/HTML does not allow transforms on inline elements and no renderer supports transforms on the a element when inline (in both SVG and HTML).

tspan
Categories:
Graphics element, renderable element, text content element, text content child element
Content model:
Any number of the following elements or character data, in any order:a, animate, script, set, style, tspan
Attributes:
DOM Interfaces:

10.2.1. Attributes

Name Value Initial value Animatable
x, y [[<length> | <percentage> | <number>]# ]+ 0 yes

If a single <length> is provided, then the value represents the new absolute X (Y) coordinate for the current text position for rendering the glyphs that correspond to the first character within this element or any of its descendants.

If a comma- or space-separated list of n <length>s is provided, then the values represent new absolute X (Y) coordinates for the current text position for rendering the glyphs corresponding to each of the first n characters within this element or any of its descendants.

If more <length>s are provided than characters, then the extra <length>s will have no effect on glyph positioning.

If more characters exist than <length>s, then for each of these extra characters: (a) if an ancestor text or tspan element specifies an absolute X (Y) coordinate for the given character via an ‘x’ (‘y’) attribute, then that absolute X (Y) coordinate is used as the starting X (Y) coordinate for that character (nearest ancestor has precedence), else (b) the starting X (Y) coordinate for rendering the glyphs corresponding to the given character is the X (Y) coordinate of the resulting current text position from the most recently rendered glyph for the current text element.

If the attribute is not specified: (a) if an ancestor text or tspan element specifies an absolute X (Y) coordinate for a given character via an ‘x’ (‘y’) attribute, then that absolute X (Y) coordinate is used (nearest ancestor has precedence), else (b) the starting X (Y) coordinate for rendering the glyphs corresponding to a given character is the X (Y) coordinate of the resulting current text position from the most recently rendered glyph for the current text element.

In SVG 2, the text and tspan x and y attributes are not presentation attributes and cannot be set via CSS. This may change in a future version of SVG.

Name Value Initial value Animatable
dx, dy [[<length> | <percentage> | <number>]# ]+ See below yes

If a single <length> is provided, this value represents the new relative X (Y) coordinate for the current text position for rendering the glyphs corresponding to the first character within this element or any of its descendants. The current text position is shifted along the x-axis (y-axis) of the current user coordinate system by <length> before the first character's glyphs are rendered.

If a comma- or space-separated list of n <length>s is provided, then the values represent incremental shifts along the x-axis (y-axis) for the current text position before rendering the glyphs corresponding to the first n characters within this element or any of its descendants. Thus, before the glyphs are rendered corresponding to each character, the current text position resulting from drawing the glyphs for the previous character within the current text element is shifted along the x-axis (y-axis) of the current user coordinate system by <length>.

If more <length>s are provided than characters, then any extra <length>s will have no effect on glyph positioning.

If more characters exist than <length>s, then for each of these extra characters: (a) if an ancestor text or tspan element specifies a relative X (Y) coordinate for the given character via a ‘dx’ (‘dy’) attribute, then the current text position is shifted along the x-axis (y-axis) of the current user coordinate system by that amount (nearest ancestor has precedence), else (b) no extra shift along the x-axis (y-axis) occurs.

If the attribute is not specified: (a) if an ancestor text or tspan element specifies a relative X (Y) coordinate for a given character via a ‘dx’ (‘dy’) attribute, then the current text position is shifted along the x-axis (y-axis) of the current user coordinate system by that amount (nearest ancestor has precedence), else (b) no extra shift along the x-axis (y-axis) occurs.

Name Value Initial value Animatable
rotate [[<number>]# ]+ See below yes (non-additive).

The supplemental rotation about the current text position that will be applied to all of the glyphs corresponding to each character within this element.

If a comma- or space-separated list of <number>s is provided, then the first <number> represents the supplemental rotation for the glyphs corresponding to the first character within this element or any of its descendants, the second <number> represents the supplemental rotation for the glyphs that correspond to the second character, and so on.

If more <number>s are provided than there are characters, then the extra <number>s will be ignored.

If more characters are provided than <number>s, then for each of these extra characters the rotation value specified by the last number must be used.

If the attribute is not specified and if an ancestor of a tspan element specifies a supplemental rotation for a given character via a rotate attribute, then the given supplemental rotation is applied to the given character (nearest ancestor has precedence). If there are more characters than <number>s specified in the ancestor's rotate attribute, then for each of these extra characters the rotation value specified by the last number must be used.

This supplemental rotation has no impact on the rules by which current text position is modified as glyphs get rendered and is supplemental to any rotation due to text on a path and to glyph-orientation-horizontal or glyph-orientation-vertical.

Name Value Initial value Animatable
textLength <length> | <percentage> | <number> See below yes

The author's computation of the total sum of all of the advance values that correspond to character data within this element, including the advance value on the glyph (horizontal or vertical), the effect of properties letter-spacing and word-spacing and adjustments due to attributes dx and dy on this text or tspan element or any descendants. This value is used to calibrate the user agent's own calculations with that of the author.

The purpose of this attribute is to allow the author to achieve exact alignment, in visual rendering order after any bidirectional reordering, for the first and last rendered glyphs that correspond to this element; thus, for the last rendered character (in visual rendering order after any bidirectional reordering), any supplemental inter-character spacing beyond normal glyph advances are ignored (in most cases) when the user agent determines the appropriate amount to expand/compress the text string to fit within a length of textLength.

If attribute textLength is specified on a given element and also specified on an ancestor, the adjustments on all character data within this element are controlled by the value of textLength on this element exclusively, with the possible side-effect that the adjustment ratio for the contents of this element might be different than the adjustment ratio used for other content that shares the same ancestor. The user agent must assume that the total advance values for the other content within that ancestor is the difference between the advance value on that ancestor and the advance value for this element.

This attribute is not intended for use to obtain effects such as shrinking or expanding text.

A negative value is an error (see Error processing).

The textLength attribute is only applied when the wrapping area is not defined by the shape-inside or the inline-size properties. It is also not applied for any text or tspan element that has forced line breaks (due to a white-space value of pre or pre-line).

If the attribute is not specified anywhere within a text element, the effect is as if the author's computation exactly matched the value calculated by the user agent; thus, no advance adjustments are made.

Name Value Initial value Animatable
lengthAdjust spacing | spacingAndGlyphs spacing yes
spacing
Indicates that only the advance values are adjusted. The glyphs themselves are not stretched or compressed.
spacingAndGlyphs
Indicates that the advance values are adjusted and the glyphs themselves stretched or compressed in one axis (i.e., a direction parallel to the inline-base direction).

The user agent is required to achieve correct start and end positions for the text strings, but the locations of intermediate glyphs are not predictable because user agents might employ advanced algorithms to stretch or compress text strings in order to balance correct start and end positioning with optimal typography.

Note that, for a text string that contains n characters, the adjustments to the advance values often occur only for n−1 characters (see description of attribute textLength), whereas stretching or compressing of the glyphs will be applied to all n characters.

10.2.2. Notes on 'x', 'y', 'dx', 'dy' and 'rotate'

The x, y, dx, dy, and rotate on the text and tspan elements are useful in high-end typography scenarios where individual glyphs require exact placement. These attributes are useful for minor positioning adjustments between characters or for major positioning adjustments, such as moving a section of text to a new location to achieve the visual effect of a new line of text (compatible with SVG 1.1). Note that the x, y, dx, dy, and rotate attributes are ignored for auto-wrapped text (except for the initial current text position when the content area is specified by the inline-size property).

It was decided at the 2015 Sydney F2F that 'dx', 'dy', and 'rotate' would be ignored for auto-wrapped text. (Technically, it is not difficult to apply them but it was not seen as being really useful.)

In situations where micro-level positioning adjustment are necessary for advanced typographic control, the SVG content designer needs to ensure that the necessary font will be available for all viewers of the document (e.g., package up the necessary font data in the form of an SVG font or an alternative WebFont format which is stored at the same Web site as the SVG content) and that the viewing software will process the font in the expected way (the capabilities, characteristics and font layout mechanisms vary greatly from system to system). If the SVG content contains x, y, dx, or dy attribute values which are meant to correspond to a particular font processed by a particular set of viewing software and either of these requirements is not met, then the text might display with poor quality.

The following additional rules apply to attributes x, y, dx, dy, and rotate when they contain a list of numbers:

Example tspan04 uses the rotate attribute on the tspan element to rotate the glyphs to be rendered. This example shows a single text string in a tspan element that contains more characters than the number of values specified in the rotate attribute. In this case the last value specified in the rotate attribute of the tspan must be applied to the remaining characters in the string.

<?xml version="1.0" standalone="no"?>
<svg width="10cm" height="3cm" viewBox="0 0 1000 300"
  xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>
    Example tspan04 - The number of rotate values is less than the number of
    characters in the string.
  </desc>
  <text font-family="Verdana" font-size="55" fill="blue" >
    <tspan x="250" y="150" rotate="-30,0,30">
      Hello, out there
    </tspan>
  </text>
  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="998" height="298"
  fill="none" stroke="blue" stroke-width="2" />
</svg>
Example tspan04 — simple rotation of characters in a tspan element

Example tspan04

View this example as SVG (SVG-enabled browsers only)

Example tspan05 specifies the rotate attribute on the text element and on all but one of the child tspan elements to rotate the glyphs to be rendered. The example demonstrates the propagation of the rotate attribute.

<?xml version="1.0" standalone="no"?>
<svg width="100%" height="100%" viewBox="0 0 500 120"
  xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>
    Example tspan05 - propagation of rotation values to nested tspan elements.
  </desc>
  <text id="parent" font-family="Arial, sans-serif" font-size="32" fill="red" x="40" y="40"
    rotate="5,15,25,35,45,55">
    Not

    <tspan id="child1" rotate="-10,-20,-30,-40" fill="orange">
      all characters

      <tspan id="child2" rotate="70,60,50,40,30,20,10" fill="yellow">
        in
        
        <tspan id="child3">
          the
        </tspan>
      </tspan>

      <tspan id="child4" fill="orange" x="40" y="90">
        text
      </tspan>

      have a
    </tspan>

    <tspan id="child5" rotate="-10" fill="blue">
      specified
    </tspan>

    rotation
  </text>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="498" height="118" fill="none"
        stroke="blue" stroke-width="2" />
</svg>
Example tspan05 — propagation of rotation values to nested tspan elements

Example tspan05

View this example as SVG (SVG-enabled browsers only)

Rotation of red text inside the text element:

Rotation of the orange text inside the "child1" tspanelement:

Rotation of the yellow text inside the "child2" tspanelement:

Rotation of the blue text inside the "child5" tspan element:

The following diagram illustrates how the rotation values propagate to tspan elements nested withing a text element:

Image that shows propagation of rotation values

10.3. Text layout – Introduction

SVG 2 Requirement: Include text layout improvements from SVG Tiny 1.2.
Resolution: SVG 2 will include the improved text from SVG Tiny 1.2 on characters and glyphs, text layout, text selection, text search.
Purpose: To include clearer descriptions of text layout; no functional change.
Owner: Chris (ACTION-3236)
SVG 2 Requirement: Support text in shapes.
Resolution: SVG 2 will require automatic text wrapping compatible with CSS.
Purpose: Text in flow charts, etc.
Owner: Tav (no action)

This section gives a short overview of SVG text layout. It is followed by sections that cover different aspects of text layout in more detail.

Text layout in SVG is a multi-stage process that takes as input a text element subtree and its property values and produces a sequence of glyphs to render and their positions in each text content element's coordinate system.

First, a text element and its descendants are laid out inside a content area or wrapping area according to CSS, as if the text were a block element and any tspan, textPath, and a descendants were inline elements. This layout takes into account all paragraph level and font related CSS properties described in this chapter.

The content area may be explicitly declared by setting the inline-size property, or by setting the shape-inside property that defines or references an SVG shape. If a content area is not declared, it defaults to a rectangle of infinite width and height.

Second, any positioning given by x, y, dx and dy attributes are applied to the resulting glyph positions from the CSS layout process. The rules for which transforms are allowed depend on if the content area was explicitly declared or not. If not explicitly declared, the rules define the layout of pre-formatted text. If declared, the rules define the layout of auto-wrapped text.

Third, the effect of the text-anchor property is applied if necessary.

Finally, layout of glyphs for any textPath elements is performed, converting pre-formatted text to text-on-a-path.

Examples of the different types of text layout:

Pre-formatted:
For short strings of text (e.g. labels) or where exact placement of glyphs is required (e.g. hand-kerned titles).

An example of multi-line pre-formatted text.

<svg xmlns="http://www.w3.org/2000/svg">
     width="300" height="100" viewBox="0 0 300 100"

     <text x="20" y="45" style="font: 24px sans-serif;">
       Example of multi-line,
       <tspan x="20" y="75">pre-formatted text.</tspan>
     </text>

</svg>
Image showing two lines of pre-formatted text.

Pre-formatted text where a tspan element has been used to create multi-line text.

Wrapped text:
For long strings of text where automatic text wrapping is required.

An example of auto-wrapped text.

<svg xmlns="http://www.w3.org/2000/svg">
     width="300" height="100" viewBox="0 0 300 100"

  <text x="20" y="45" style="font: 24px sans-serif; inline-size: 250px;">
    Example of text auto-wrapped.</text>

</svg>
Image showing auto-wrapped text on two lines.

Auto-wrapped text. The inline-size property defines a rectangular content area of infinite height (shown in light blue).

Text on path:
For text that follows a specified path.

An example of text on a path.

<svg xmlns="http://www.w3.org/2000/svg">
     width="300" height="100" viewBox="0 0 300 100"

  <path id="MyPath" stroke="lightblue" fill="none"
	d="M 50,50 C 100,0 200,100 250,50"/>

  <text style="font: 24px sans-serif;">
    <textPath href="#MyPath">Text on a path.</textPath>
  </text>

</svg>
Image showing text following a path.

Text on a path. The textPath element references a path element (shown in light blue).

SVG 2 introduces the ability to automatically wrap text inside a rectangle or other shape by specifying a content area. The design of SVG wrapped text is motivated by the desire that SVG text wrapping be as compatible as possible with text wrapping in CSS in order that renderers that support CSS text wrapping can implement SVG text wrapping easily (but without requiring non-HTML compatible SVG renderers to implement HTML). There are several differences between SVG and CSS text wrapping. The most important is that in SVG, a content area must be explicitly provided as SVG does not have an automatic finite (or semi-finite) content area (provided in CSS by the box model). Another difference is that SVG does not have the <p></p> and <br/> elements which create line breaks. Instead, SVG relies on the pre and pre-line values of white-space to provide line breaks. SVG wrapped text also allows a content-creation tool to provide a natural fallback for SVG 1.1 renderers that do not support wrapped text (by use of x and y attributes in the text and tspan elements, which are ignored by SVG 2 renderers for auto-wrapped text).

SVG's text layout options are designed to cover most general use cases. If more complex layout is required (bulleted lists, tables, etc.), text can be rendered in another XML namespace such as XHTML [XHTML] embedded inline within a foreignObject element.

10.4. Text layout – Content Area

A content area is defined by specifying in a text element an inline-size property, or a shape-inside property that defines or references an SVG shape. If no content area is provided, the content area defaults to a rectangle of infinite width and height (see the pre-formatted text section). If both an inline-size property and a shape-inside property with value other than 'none' are given, the shape-inside property is used.

Wrapped text is laid out in a wrapping area. The wrapping area is normally the same as the content area. When the content area is defined using the shape-inside property, the wrapping area may be smaller due to the presence of a shape-subtract property and/or a shape-padding property. The shape-subtract property (along with the shape-margin property) defines a wrapping context. The wrapping area then is found by subtracting the wrapping context from the content area. A non-zero value for the shape-padding property causes an additional inset to the wrapping area.

Once a wrapping area is defined, the text is laid out inside the wrapping area according to the rules of CSS (respecting any special rules given in this section).

Constructing equivalent wrapping areas in SVG and HTML. The text inside the wrapping areas is rendered the same in both cases.

Image showing the creation of an hour glass shape
           using a circle with two semicircles spaced out
           horizontally. Text is wrapped in the circle after
           the left and right semicircles exclude part of the
           circle.

Defining a wrapping area in SVG. The text element has both a shape-inside property and a shape-subtract property. The shape-inside property references a circle that defines a content area (dotted purple line). The shape-subtract property referencing two semicircles defines a wrapping context (dotted green line) which when subtracted from the content area results in the wrapping area (light blue line).

Image showing the creation of an hour glass shape
           using a circle with two semicircles spaced out
           horizontally. Text is wrapped in the circle after
           the left and right semicircles exclude part of the
           circle.

Defining a wrapping area in HTML. A wrapper <div> contains two float <div>s. The wrapper <div> defines a rectangular region (solid purple line). Its shape-inside property defines a content area within the <div> (dotted purple line). The two other <div>s define two floats, one on the left (solid green line) and the right (solid pink line). The floats are rectangular in shape. Each float has a shape-outside property which defines the wrapping context for each float (dotted green and pink lines). The combined wrapping context is subtracted from the content area to defined the wrapping area (light blue line).

10.4.1. The ‘inline-size’ property

'extent' added by resolution from February 12th, 2015. 'extent' replaces the 'width' and 'height' attributes, added by resolution from June 27th, 2013. Replaced by 'inline-size' presentation attribute per resolution from Linkoping F2F, June 11, 2015.

The inline-size property allows one to set the wrapping area to a rectangular shape. The computed value of the property sets the width of the rectangle for horizontal text and the height of the rectangle for vertical text. The other dimension (height for horizontal text, width for vertical text) is of infinite length. A value of zero disables the creation of a wrapping area.

The initial current text position is taken from the x and y attributes of the text element (or first child tspan element if the attributes are not given on the text element). For left-to-right text, the initial current text position is at the left of the rectangle. For right-to-left text it is at the right of the rectangle. For vertical text, the initial current text position is at the top of the rectangle.

The rectangle (wrapping area) is then anchored according to the text-anchor property using the edges of the wrapping area to determine the start, middle, and end positions.

The inline-size property method to wrap text is an extension to pre-formatted SVG text where the author simply gives a limit to the width or height of the block of text; thus the use of the x and y attributes along with the direction and text-anchor properties to position the first line of text. If full justification is needed, the shape-inside property should be used to create the wrapping area.

Name: inline-size
Value: <length> | <percentage> | <number>
Initial: 0
Applies to: text elements
Inherited: no
Percentages: Refer to the width (for horizontal text) or height (for vertical text) of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

An example of using inline-size for wrapping horizontal text.

<svg xmlns="http://www.w3.org/2000/svg"
     width="300" height="100" viewBox="0 0 300 100">

  <text x="50" y="30" style="font: 20px sans-serif; inline-size: 200px">
    This text wraps at 200 pixels.
  </text>

</svg>
Image showing English text wrapped into two lines.

Horizontal text wrapping. The light-blue lines indicate the limits of the content area. Note that the content area is of infinite height. The red dot shows the initial current text position.

An example of using inline-size for wrapping right to left horizontal text.

<svg xmlns="http://www.w3.org/2000/svg"
     width="300" height="100" viewBox="0 0 300 100">

  <text x="250" y="30"
	style="font: 20px PakType Naqsh; inline-size: 200px; direction: rtl;">
    هذا النص يلتف في 200 بكسل.</text>

</svg>
Image showing Arabic text wrapped into two lines.

Horizontal text wrapping for right to left text. The light-blue lines indicate the limits of the content area. Note that the content area is of infinite height. The red dot shows the initial current text position.

Some browser may not render this SVG 1.1 figure correctly. Batik and Firefox seems to get it right. Bug filed against Chrome.

An example of using inline-size for wrapping vertical text.

<svg xmlns="http://www.w3.org/2000/svg"
     width="100" height="300" viewBox="0 0 100 300">

  <text x="62.5" y="25" inline-size="200"
	style="font: 25px IPAMincho; inline-size: 200px; writing-mode: vertical-rl;">
    テキストは10文字後に折り返されます。</text>

</svg>
Image showing vertical Japanese text wrapped into two columns.

Vertical text wrapping. The light-blue lines indicate the limits of the content area. Note that the content area is of infinite width. The red dot shows the initial current text position.

This SVG 1.1 image doesn't work in Firefox, even nightly. Firefox does not support the presentation attribute 'writing-mode'. Bug filed against Firefox.

An example of using inline-size for wrapping horizontal text, anchored in the middle.

<svg xmlns="http://www.w3.org/2000/svg"
     width="300" height="100" viewBox="0 0 300 100">

  <text x="50" y="30" style="font: 20px sans-serif; inline-size: 200px; text-anchor: middle">
    This text wraps at 200 pixels.
  </text>

</svg>
Image showing English text wrapped into two lines, anchored in the center.

Horizontal text wrapping. The light-blue lines indicate the limits of the content area. The text is anchored in the middle. The red dot shows the initial current text position.

10.4.2. The ‘shape-inside’ property

The shape-inside property allows one to set the content area to a CSS basic shape or to an SVG shape.

In CSS/HTML shape-inside applies to block-level elements and absolute and percentage values are defined relative to the block-level element. In SVG absolute and percentage values are defined relative to the current local coordinate system and the viewBox.

Name: shape-inside
Value: auto | [<basic-shape> | <uri>]+
Initial: auto
Applies to: text elements
Inherited: no
Percentages: Relative to the viewBox
Media: visual
Computed value: computed lengths for <shape>, the absolute URI for <uri>, otherwise as specified
Animatable: yes, see Interpolation of Basic Shapes
auto
For the purposes of SVG, the 'auto' value indicates that the content area should be defined using the inline-size property or as for pre-formatted text.
<basic-shape>
The shape is computed based on the values of one of 'circle()', 'ellipse()' or 'polygon()'. The CSS value of 'inset()' is invalid for SVG.

An example of using a CSS basic-shape for wrapping horizontal text.

<svg xmlns="http://www.w3.org/2000/svg"
     width="300" height="300" viewBox="0 0 300 300">

  <text style="font: 20px/25px sans-serif;
               text-align: center;
               shape-inside: circle(120px at 150px 150px);">
    Lorem ipsum dolor sit amet, consec-tetuer adipiscing elit...</text>

</svg>
Image showing text wrapped inside a circle.

Horizontal text wrapping inside a CSS circle shape. The light-blue circle indicates the limit of the content area.

<uri>
If the <uri> references an SVG shape element, that element defines the shape. Otherwise, if the <uri> references an image, the shape is extracted and computed based on the alpha channel of the specified image using the shape-image-threshold. If the <uri> does not reference an SVG shape element or an image, the effect is as if the value ‘auto’ had been specified.

An example of using a reference to an SVG shape for wrapping horizontal text.

<svg xmlns="http://www.w3.org/2000/svg"
     width="300" height="100" viewBox="0 0 300 100">

  <defs>
    <rect id="wrap" x="50" y="10" width="200" height="80"/>
  </defs>

  <text style="font: 20px sans-serif; shape-inside: url(#wrap);">
    This text wraps in a rectangle.</text>

</svg>
Image showing text wrapped inside a rectangle.

Horizontal text wrapping inside an SVG rectangle shape. The light-blue lines indicate the limits of the content area.

The CSS values of 'outside-shape', 'shape-box', are 'display' are invalid for SVG.

SVG allows the shape-inside property to have a list of shapes. Each shape defines an independent content area. Text is first laid out in the content area of the first shape. If the text overflows the first shape, the overflow text is laid out in the next shape until all text is laid out or no more shapes are available.

This behavior is different from how a list of shapes behaves in CSS where each shape serves to reduce the content area of a single block level element.

It is recommended that an overflow shape be provided to ensure the accessibility of all text in case, for example, a user increases the font size.

Except as noted, see the CSS Shapes Module Level 2 for the definition of 'shape-inside'. [CSSSHAPES2]

'shape-inside' was removed when the CSS Exclusions and Shapes Module was split into separate Exclusions and Shapes modules. At the Tokyo joint SVG/CSS F2F meeting, it was agreed that it would reappear in CSS Shapes Module Level 2.

10.4.3. The ‘shape-subtract’ property

The shape-subtract property allows one to exclude part of the content area from the wrapping area. The excluded area is the addition of all the areas defined in a list of CSS basic shapes and/or SVG shapes.

It was resolved at the 2016 Sydney F2F that 'shape-subtract' should be uses instead of 'shape-outside' due to the different behavior required. ('shape-outside' reduces the area of an exclusion.)

Absolute and percentage values are defined relative to the current local coordinate system and the viewBox.

Name: shape-subtract
Value: none | [<basic-shape>| <uri>]+
Initial: none
Applies to: text elements
Inherited: no
Percentages: Relative to the viewBox
Media: visual
Computed value: computed lengths for any <basic-shape>, the absolute URI for <uri>, otherwise as specified
Animatable: yes, see Interpolation of Basic Shapes
<basic-shape>
The shape is computed based on the values of one of 'circle()', 'ellipse()' or 'polygon()'.
<uri>
For any <uri> that references an SVG shape element, that element defines the contributing shape. For any <uri> that references an image, the contributing shape is extracted and computed based on the alpha channel of the specified image using the shape-image-threshold. If an <uri> does not reference an SVG shape element or an image, that <uri> is ignored.

An example of using shape-subtract.

.
<svg xmlns="http://www.w3.org/2000/svg"
     width="450" height="300" viewBox="0 0 450 300">

  <rect id="rect1" x="25"  y="25"  width="225" height="175" fill="white" stroke="black"/>
  <rect id="rect2" x="200" y="125" width="225" height="150" fill="white" stroke="black"/>

  <text style="shape-inside:url(#rect1);
	       shape-subtract:url(#rect2);
	       shape-padding:25px;
	       shape-margin:25px;
               font-family:DejaVu Sans;
	       font-size:12px;
	       text-align:justified;
	       line-height:110%">Lorem ipsum ...</text>
  <text style="shape-inside:url(#rect2);
	       shape-padding:25px;
               font-family:DejaVu Sans;
	       font-size:12px;
	       text-align:justified;
	       line-height:110%">Lorem ipsum ...</text>
</svg>
Image showing horizontal text wrapped inside two overlapping rectangles.

Horizontal text wrapping inside two overlapping rectangles using shape-subtract as well as shape-inside, shape-padding and shape-margin. The black rectangles show the content areas. The inner blue lines show the wrapping areas.

10.4.4. The ‘shape-image-threshold’ property

The shape-image-threshold defines the alpha channel threshold used to extract the shape using an image. A value of 0.5 means that the shape will enclose all the pixels that are more than 50% opaque.

For the purposes of SVG, this property applies to text elements.

Except as noted, see the CSS Shapes Module Level 1 for the definition of 'shape-image-threshold'. [CSSSHAPES1]

10.4.5. The ‘shape-margin’ property

The shape-margin property adds a margin to a shape-subtract. For each shape in the list, this defines a new shape where every point is the specified distance from the original shape. This property takes on positive values only.

Name: shape-margin
Value: <length> | <percentage>
Initial: 0
Applies to: text elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: the absolute length
Animatable: yes

Except as noted, see the CSS Shapes Module Level 1 for the definition of See 'shape-margin'. [CSSSHAPES1]

10.4.6. The ‘shape-padding’ property

The shape-padding property can be used to offset the inline flow content wrapping on the inside of elements. Offsets created by the ‘wrap-padding’ property are offset from the content area of the element. This property takes on positive values only.

An example of using shape-padding

.
<svg xmlns="http://www.w3.org/2000/svg"
     width="300" height="300" viewBox="0 0 300 300">

  <circle id="circle" cx="150" cy="150" r="125" fill="none" stroke="black"/>
  <text style="shape-inside: url(#circle);
	       shape-padding: 25px;
	       font: 18px DejaVu Sans;
	       text-align: justified;
	       line-height: 110%;">This is an
  example of wrapped text in SVG 2! There should
  be 25 pixel pixel around the text. The text is
  justified on both sides. It looks good!</text>

</svg>
Image showing horizontal text wrapped inside a circle with a padding.

Horizontal text wrapping inside a circle with a shape-padding. The outer black circle shows the content area. The inner blue circle shows the wrapping area.

This image is a PNG. Figure out how to make a good SVG. Note: Chrome supports 'textLength' on 'tspan' but Firefox does not.

Except as noted, see the CSS Shapes Module Level 2 for the definition of 'shape-padding'.

10.5. Text layout – Algorithm

Text layout begins by passing to a CSS based text renderer the content of the text element which includes text data along with styling information and a description of one or more shapes to be filled. The text element is treated as a block element and its descendant tspan, textPath and a elements are treated as inline elements. The CSS renderer returns a set of typographic characters with their positions resulting from laying out the text as if the text were absolutely positioned.

A typographic character may contain more than one glyph. It is assumed here the relative positioning of the glyphs inside a typographic character is encapsulated by the typographic character and it is not user controllable.

Once a content area has been defined, the following algorithm is used to determine the typographic characters and their positions for a given text element:

A number of CSS properties have no or limited effect on SVG text layout:

Various SVG attributes and properties may reposition the typographic characters depending on how the content area is defined:

The following SVG text layout algorithm returns output information about each character in the DOM in the text element's subtree. That information includes:

The arrays given in the SVG attributes x, y, dx, dy, and rotate are indexed by addressable characters. However, repositioning is applied typographic characters. If a typographic character corresponds to more than one character (e.g. a ligature), only the array values corresponding to the first character are used in positioning the typographic character. Array values corresponding to other characters in the typographic character are skipped (for x and y), are accumulated and applied to the next typographic character (for dx and dy), or if it is the last value in the array, applied to the following typographic characters (for rotate). This ensures, for example, that attribute values are applied to the same characters regardless of whether or not a font has a particular ligature.

The SVG specific text layout algorithm is as follows:

  1. Setup
    1. Let root be the result of generating typographic character positions for the text element and its subtree, laid out as if it were an absolutely positioned element.

      This will be a single line of text unless the white-space property causes line breaks.

    2. Let count be the number of DOM characters within the text element's subtree.
    3. Let result be an array of length count whose entries contain the per-character information described above. Each entry is initialized as follows:
      • its global index number equal to its position in the array,
      • its "x" coordinate set to "unspecified",
      • its "y" coordinate set to "unspecified",
      • its "rotate" coordinate set to "unspecified",
      • its "hidden" flag is false,
      • its "addressable" flag is true,
      • its "middle" flag is false,
      • its "anchored chunk" flag is false.
      If result is empty, then return result.
    4. Let CSS_positions be an array of length count whose entries will be filled with the x and y positions of the corresponding typographic character inroot. The array entries are initialized to (0, 0).
    5. Let "horizontal" be a flag, true if the writing mode of text is horizontal, false otherwise.
  2. Set flags and assign initial positions

    For each array element with index i in result:

    1. Set addressable to false if the character at index i was:

      Since there is collapsible white space not addressable by glyph positioning attributes in the following text element (with a standard font), the "B" glyph will be placed at x=300.

      <text x="100 200 300">
      	      A
      	      B
      	      </text>

      This is because the white space before the "A", and all but one white space character between the "A" and "B", is collapsed away or trimmed.

    2. Set middle to true if the character at index i is the second or later character that corresponds to a typographic character.
    3. If the character at index i corresponds to a typographic character at the beginning of a line, then set the "anchored chunk" flag of result[i] to true.

      This ensures chunks shifted by text-anchor do not span multiple lines.

    4. If addressable is true and middle is false then set CSS_positions[i] to the position of the corresponding typographic character as determined by the CSS renderer. Otherwise, if i > 0, then set CSS_positions[i] = CSS_positions[i − 1]
  3. Resolve character positioning

    Position adjustments (e.g values in a x attribute) specified by a node apply to all characters in that node including characters in the node's descendants. Adjustments specified in descendant nodes, however, override adjustments from ancestor nodes. This section resolves which adjustments are to be applied to which characters. It also directly sets the rotate coordinate of result.

    1. Set up:
      1. Let resolve_x, resolve_y, resolve_dx, and resolve_dy be arrays of length count whose entries are all initialized to "unspecified".
      2. Set "in_text_path" flag false.

        This flag will allow y (x) attribute values to be ignored for horizontal (vertical) text inside textPath elements.

      3. Call the following procedure with the text element node.
    2. Procedure: resolve character positioning:

      A recursive procedure that takes as input a node and whose steps are as follows:

      1. If node is a text or tspan node:
        1. Let index equal the "global index number" of the first character in the node.
        2. Let x, y, dx, dy and rotate be the lists of values from the corresponding attributes on node, or empty lists if the corresponding attribute was not specified or was invalid.
        3. If "in_text_path" flag is false:
          • Let new_chunk_count = max(length of x, length of y).
          Else:
          • If the "horizontal" flag is true:
            • Let new_chunk_count = length of x.
          • Else:
            • Let new_chunk_count = length of y.
        4. Let length be the number of DOM characters in the subtree rooted at node.
        5. Let i = 0 and j = 0.

          i is an index of addressable characters in the node; j is an index of all characters in the node.

        6. While j < length, do:

          This loop applies the x, y, dx, dy and rotate attributes to the content inside node.

          1. If the "addressable" flag of result[index + j] is true, then:
            1. If i < new_check_count, then set the "anchored chunk" flag of result[index + j] to true. Else set the flag to false.

              Setting the flag to false ensures that x and y attributes set in a text element don't create anchored chunk in a textPath element when they should not.

            2. If i < length of x, then set resolve_x[index + j] to x[i].
            3. If "in_text_path" flag is true and the "horizontal" flag is false, unset resolve_x[index].

              The x attribute is ignored for vertical text on a path.

            4. If i < length of y, then set resolve_y[index + j] to y[i].
            5. If "in_text_path" flag is true and the "horizontal" flag is true, unset resolve_y[index].

              The y attribute is ignored for horizontal text on a path.

            6. If i < length of dx, then set resolve_dx[index + j] to dy[i].
            7. If i < length of dy, then set resolve_dy[index + j] to dy[i].
            8. If i < length of rotate, then set the angle value of result[index + j] to rotate[i]. Otherwise, if rotate is not empty, then set result[index + j] to result[index + j − 1].
            9. Set i = i + 1.
          2. Set j = j + 1.
      2. If node is a textPath node:
        1. Let index equal the global index number of the first character in the node (including descendant nodes).
        2. Set the "anchored chunk" flag of result[index] to true.

          A textPath element always creates an anchored chunk.

        3. Set in_text_path flag true.
      3. For each child node child of node:
        1. Resolve glyph positioning of child.
      4. If node is a textPath node:
        1. Set "in_text_path" flag false.
  4. Adjust positions: dx, dy

    The dx and dy adjustments are applied before adjustments due to the textLength attribute while the x, y and rotate adjustments are applied after.

    1. Let shift be the cumulative x and y shifts due to x and y attributes, initialized to (0,0).
    2. For each array element with index i in result:
      1. If resolve_x[i] is unspecified, set it to 0. If resolve_y[i] is unspecified, set it to 0.
      2. Let shift.x = shift.x + resolve_x[i] and shift.y = shift.y + resolve_y[i].
      3. Let result[i].x = CSS_positions[i].x + shift.x and result[i].y = CSS_positions[i].y + shift.y.
  5. Apply textLength attribute
    1. Set up:
      1. Define resolved descendant node as a descendant of node with a valid textLength attribute that is not itself a descendant node of a descendant node that has a valid textLength attribute.
      2. Call the following procedure with the text element node.
    2. Procedure: resolve text length:

      A recursive procedure that takes as input a node and whose steps are as follows:

      1. For each child node child of node:
        1. Resolve text length of child.

          Child nodes are adjusted before parent nodes.

      2. If node is a text or tspan node and if the node has a valid textLength attribute value:
        1. Let a = +∞ and b = −∞.
        2. Let i and j be the global index of the first character and last characters in node, respectively.
        3. For each index k in the range [i, j] where the "addressable" flag of result[k] is true:

          This loop finds the left-(top-) most and right-(bottom-) most extents of the typographic characters within the node and checks for forced line breaks.

          1. If the character at k is a linefeed or carriage return, return. No adjustments due to textLength are made to a node with a forced line break.
          2. Let pos = the x coordinate of the position in result[k], if the "horizontal" flag is true, and the y coordinate otherwise.
          3. Let advance = the advance of the typographic character corresponding to character k. [NOTE: This advance will be negative for RTL horizontal text.]
          4. Set a = min(a, pos, pos + advance).
          5. Set b = max(b, pos, pos + advance).
        4. If a ≠ +∞ then:
          1. Find the distance delta = textLength computed value − (b − a).

            User agents are required to shift the last typographic character in the node by delta, in the positive x direction if the "horizontal" flag is true and if direction is lrt, in the negative x direction if the "horizontal" flag is true and direction is rtl, or in the positive y direction otherwise. User agents are free to adjust intermediate typographic characters for optimal typography. The next steps indicate one way to adjust typographic characters when the value of lengthAdjust is spacing.

          2. Find n, the total number of typographic characters in this node including any descendant nodes that are not resolved descendant nodes or within a resolved descendant node.
          3. Let n = n + number of resolved descendant nodes − 1.

            Each resolved descendant node is treated as if it were a single typographic character in this context.

          4. Find the per-character adjustment δ = delta/n.
          5. Let shift = 0.
          6. For each index k in the range [i,j]:
            1. Add shift to the x coordinate of the position in result[k], if the "horizontal" flag is true, and to the y coordinate otherwise.
            2. If the "middle" flag for result[k] is not true and k is not a character in a resolved descendant node other than the first character then shift = shift + δ.
  6. Adjust positions: x, y

    This loop applies x and y values, and ensures that text-anchor chunks do not start in the middle of a typographic character.

    1. Let shift be the current adjustment due to the x and y attributes, initialized to (0,0).
    2. Set index = 1.
    3. While index < count:
      1. If resolved_x[index] is set, then let shift.x = resolved_x[index] − result.x[index].
      2. If resolved_y[index] is set, then let shift.y = resolved_y[index] − result.y[index].
      3. Let result.x[index] = result.x[index] + shift.x and result.y[index] = result.y[index] + shift.y.
      4. If the "middle" and "anchored chunk" flags of result[index] are both true, then:
        1. Set the "anchored chunk" flag of result[index] to false.
        2. If index + 1 < count, then set the "anchored chunk" flag of result[index + 1] to true.
      5. Set index to index + 1.
  7. Apply anchoring
    1. For each slice result[i..j] (inclusive of both i and j), where:
      • the "anchored chunk" flag of result[i] is true,
      • the "anchored chunk" flags of result[k] where i < kj are false, and
      • j = count − 1 or the "anchored chunk" flag of result[j + 1] is true;
      do:

      This loops over each anchored chunk.

      1. Let a = +∞ and b = −∞.
      2. For each index k in the range [i, j] where the "addressable" flag of result[k] is true:

        This loop finds the left-(top-) most and right-(bottom-) most extents of the typographic character within the anchored chunk.

        1. Let pos = the x coordinate of the position in result[k], if the "horizontal" flag is true, and the y coordinate otherwise.
        2. Let advance = the advance of the typographic character corresponding to character k. [NOTE: This advance will be negative for RTL horizontal text.]
        3. Set a = min(a, pos, pos + advance).
        4. Set b = max(b, pos, pos + advance).
      3. If a ≠ +∞, then:

        Here we perform the text anchoring.

        1. Let shift be the x coordinate of result[i], if the "horizontal" flag is true, and the y coordinate otherwise.
        2. Adjust shift based on the value of text-anchor and direction of the element the character at index i is in:
          (start, ltr) or (end, rtl)
          Set shift = shifta.
          (start, rtl) or (end, ltr)
          Set shift = shiftb.
          (middle, ltr) or (middle, rtl)
          Set shift = shift − (a + b) / 2.
        3. For each index k in the range [i, j]:
          1. Add shift to the x coordinate of the position in result[k], if the "horizontal" flag is true, and to the y coordinate otherwise.
  8. Position on path
    1. Set index = 0.
    2. Set the "in path" flag to false.
    3. Set the "after path" flag to false.
    4. Let path_end be an offset for characters that follow a textPath element. Set path_end to (0,0).
    5. While index < count:
      1. If the character at index i is within a textPath element and corresponds to a typographic character, then:
        1. Set "in path" flag to true.
        2. If the "middle" flag of result[index] is false, then:

          Here we apply textPath positioning.

          1. Let path be the equivalent path of the basic shape element referenced by the textPath element, or an empty path if the reference is invalid.
          2. If the side attribute of the textPath element is 'right', then reverse path.
          3. Let length be the length of path.
          4. Let offset be the value of the textPath element's startOffset attribute, adjusted due to any pathLength attribute on the referenced element (if the referenced element is a path element).
          5. Let advance = the advance of the typographic character corresponding to character k. [NOTE: This advance will be negative for RTL horizontal text.]
          6. Let (x, y) and angle be the position and angle in result[index].
          7. Let mid be a coordinate value depending on the value of the "horizontal" flag:
            true
            mid is x + advance / 2 + offset
            false
            mid is y + advance / 2 + offset

            The user agent is free to make any additional adjustments to mid necessary to ensure high quality typesetting due to a spacing value of 'auto' or a method value of 'stretch'.

          8. If path is not a closed subpath and mid < 0 or mid > length, set the "hidden" flag of result[index] to true.
          9. If path is a closed subpath depending on the values of text-anchor and direction of the element the character at index is in:

            This implements the special wrapping criteria for single closed subpaths.

            (start, ltr) or (end, rtl)
            If midoffset < 0 or midoffset > length, set the "hidden" flag of result[index] to true.
            (middle, ltr) or (middle, rtl)
            If If midoffset < −length/2 or midoffset > length/2, set the "hidden" flag of result[index] to true.
            (start, rtl) or (end, ltr)
            If midoffset < −length or midoffset > 0, set the "hidden" flag of result[index] to true.

            Set mid = mid mod length.

          10. If the hidden flag is false:
            1. Let point be the position and t be the unit vector tangent to the point mid distance along path.
            2. If the "horizontal" flag is
              true
              1. Let n be the normal unit vector pointing in the direction t + 90°.
              2. Let o be the horizontal distance from the vertical center line of the glyph to the alignment point.
              3. Then set the position in result[index] to point - o×t + y×n.
              4. Let r be the angle from the positive x-axis to the tangent.
              5. Set the angle value in result[index] to angle + r.
              false
              1. Let n be the normal unit vector pointing in the direction t - 90°.
              2. Let o be the vertical distance from the horizontal center line of the glyph to the alignment point.
              3. Then set the position in result[index] to point - o×t + x×n.
              4. Let r be the angle from the positive y-axis to the tangent.
              5. Set the angle value in result[index] to angle + r.
        3. Otherwise, the "middle" flag of result[index] is true:
          1. Set the position and angle values of result[index] to those in result[index − 1].
      2. If the character at index i is not within a textPath element and corresponds to a typographic character, then:

        This sets the starting point for rendering any characters that occur after a textPath element to the end of the path.

        1. If the "in path" flag is true:
          1. Set the "in path" flag to false.
          2. Set the "after path" flag to true.
          3. Set path_end equal to the end point of the path referenced by textPath − the position of result[index].
        2. If the "after path" is true.
          1. If anchored chunk of result[index] is true, set the "after path" flag to false.
          2. Else, let result.x[index] = result.x[index] + path_end.x and result.y[index] = result.y[index] + path_end.y.
      3. Set index = index + 1.
  9. Return result

SVG 2 Requirement: Align with CSS for text layout functionality.
Resolution: SVG 2 Will use CSS3 definitions for text layout (white space, bidi, etc.) that is not specific to SVG.
Purpose: To facilitate shared specification and implementation of text layout in HTML and SVG.
Owner: Cameron and Chris (ACTION-3004, ACTION-3005)

10.6. Pre-formatted text

This option corresponds to basic SVG 1.1 text layout.

This is the default text layout method and is used in the absence of an explicitly defined content area. It is also used as a first step in laying out text on a path (with slightly modified rules). In this layout method, no automatic line breaking or word wrapping is done. Nominally, the text is rendered as a single line inside a rectangular content area of infinite width and height. Multiple lines of text can be obtained by precomputing line breaks and using one of the following methods:

The following properties do not apply to pre-formatted text: text-align, text-align-last, line-break, word-break, hyphens, word-wrap, and overflow-wrap.

10.6.1. Multi-line text via 'white-space'

Multi-line pre-formatted text may be created by using the white-space values pre or pre-line. In these cases, a line-feed or carriage return is preserved as a forced line break which creates a new line box. The line boxes are stacked following the rules of CSS.

10.6.2. Repositioning Glyphs

After text is laid out according to the basic CSS text layout rules, typographic characters can be repositioned using SVG specific rules. Absolute repositioning can be prescribed by giving absolute coordinates in the x and y attributes or by forced line breaks. Absolute repositioning may be influenced by the text-anchor property. Relative repositioning can be prescribed by giving relative coordinates in the dx and dy attributes. The typographic characters may be arbitrarily rotated by giving a list of values in the rotate attribute. Absolute repositioning (including any adjustment due to the text-anchor property) is done before relative repositioning and rotation.

10.7. Auto-wrapped text

Text is automatically wrapped when a content area is specified in the text element. The content area defines the outermost container for wrapping text. A wrapping context (set of exclusion areas) may also be given. The actual wrapping area is defined by subtracting the wrapping context from the content area. The wrapping context may also be reduced by the value of the shape-padding property. The effective area of an exclusion may be enlarged by the value of the shape-margin property.

In the case where the content area is defined by the by the inline-size property, the x and y attributes corresponding to the first rendered typographic character define the initial current text position. When the content area is inside a shape, the initial current text position is determined from the position of the first rendered typographic character after laying out the first line box inside the shape.

Except when used to determine the initial current text position, all values x and y are ignored on text, and tspan elements in auto-wrapped text.

The attributes x and y can provide a natural fallback mechanism for SVG1.1 renderers for wrapped text. Content producers may wish to pre-layout text by breaking up lines into tspan elements with x and y attributes. Then, for example, if a fallback font is used to render the text, an SVG2 renderer will ignore the x and y attributes and reflow the text using the font metrics of the fallback font. An SVG1.1 renderer will use the x and y attributes in rendering the text which will usually result in readable text even if the rendering doesn't match the shape. Many of the text wrapping examples in this section rely on this mechanism to render text in browsers that have not implemented text wrapping.

10.7.1. Notes on Text Wrapping

The following examples illustrate a few issues with laying out text in a shape.

10.7.1.1. First Line Positioning

Given an arbitrary shaped wrapping area, the first line box may not fit flush against the top (or side for vertical text). In this case, the first line box is shifted until it fits.

In CSS, the edge of a shape is treated as a series of 1 pixel × 1 pixel floats.

A future CSS specification may define a line grid that could be used to control the position of the first line of text to allow alignment of text between different wrapping areas.

Image showing two lines of text, the first line is 'The' and
              the next line is 'first line'.

The top line box (small light-blue rectangle), consisting of the smallest possible block of text, is moved down until the line box fits inside the wrapping area (light-blue path). Note, the line box includes the effect of the line-height property, here set to 1.25. The red rectangles tightly wrap the glyphs in each line box.

This appears to be different from the SVG 1.2 draft in which the top of the wrapping area served as the origin of a line grid. The first line was moved down by the line height until it fit inside the shape.

10.7.1.2. Broken Lines

Given an arbitrary shaped wrapping area, a single line of text might be broken into more than one part. In this case, a line box for each part is created. The height of all line boxes in a single line of text must be the same (ensuring all parts have the same baseline). This height is calculated by looking at all glyphs in the line of text.

This default behavior was agreed to at the CSS/SVG joint working group meeting in Sydney 2016.

A future CSS specification may allow one to control which parts of a shape broken into different parts is filled (e.g, fill only the right most parts, fill only the left most parts, etc.).

Image showing text laidout inside a 'V' shape.

The top line is split into two line boxes (light-blue rectangles), text in each line box is centered inside the box (due to 'text-align:center').

10.8. Text on a path

SVG can place text along a path defined either by a path element or the path equivalent of a basic shape. This is specified by including text within a textPath element that has either an href attribute with an URL reference pointing to a path element or basic shape, or by specifying a value for the path attribute that specifies the path data directly.

The ability to place text along a basic shape is new in SVG 2.

Placing text along a basic shape was resolved at the Sydney (2015) meeting.

Directly using a 'd' attribute to specify the path was added to SVG 2. The 'd' attribute was renamed to 'path' by decision at the London (2016) editor's meeting at the same time 'd' was promoted to being a presentation attribute.

Text on a path is conceptional like a single line of pre-formatted text text that is then transformed to follow the path. Except as indicated, all the properties that apply to pre-formatted text apply to text on a path.

10.8.1. The ‘textPath’ element

textPath
Categories:
Graphics element, renderable element, text content element, text content child element
Content model:
Any number of the following elements or character data, in any order:a, animate, clipPath, marker, mask, script, set, style, tspan
Attributes:
DOM Interfaces:
SVG 2 Requirement: Have a more precise explanation of text path stretch methods.
Resolution: We will clarify method="stretch" on >'textPath' elements.
Purpose: Improve interoperability of the feature.
Owner: Cameron (no action)

Both the path attribute and the href attribute specify a path along which the typographic characters will be rendered.

If both attributes are specified on a textPath element, the path that is used must follow the following order of precedence:

  1. path attribute
  2. href attribute

If the path attribute contains an error, the href attribute must be used.

10.8.2. Attributes

startOffset

An offset from the start of the path for the initial current text position, calculated using the user agent's distance along the path algorithm.

If a <length> other than a percentage is given, then the startOffset represents a distance along the path measured in the current user coordinate system.
If a percentage is given, then the startOffset represents a percentage distance along the entire path. Thus, startOffset="0%" indicates the start point of the path and startOffset="100%" indicates the end point of the path.

Negative values and values larger than the path length (e.g. 150%) are allowed.

Limiting values to the range 0%-100% prevents easily creating effects like text moving along the path.

Any typographic characters with mid-points that are not on the path are not rendered.

Three paths with various values of 'startOffset' showing clipping
		  when glyphs are outside path region.

Rendering for different values of the startOffset attribute. From top to bottom: default value, 50%, -50%.

The bottom path should show only "path." on the left side of the path. Chrome and Safari both do not handle offsets outside the range 0% to 100%. Chrome bug https://bugs.chromium.org/p/chromium/issues/detail?id=476554

For paths consisting of a single closed subpath (including an equivalent path for a basic shape), typographic characters are rendered along one circuit of the path. The text is aligned as determined by the text-anchor property to a position along the path set by the startOffset attribute. For the start (end) value, the text it rendered from the start (end) of the line until the initial position along the path is reached again. For the middle, the text is rendered from the middle point in both directions until a point on the path equal distance in both directions from the initial position on the path is reached.

Two circular path with different values of
		  'startOffset' showing that all glyphs are rendered.

Rendering for text on a path referencing a circle with different values of the startOffset attribute. Left: 0. Right: 75% or -25%. The red circle marks the beginning of the path (after the canonical decomposition of the circle into a path).

Three circular path with different values of
		  'text-anchor' showing how glyphs are rendered.

Rendering for text on a path referencing a circle with different values of the text-anchor attribute. Left: 'start'. Middle: 'middle'. Right: 'end'. The red circles marks the beginning of the path (after the canonical decomposition of the circle into a path). The blue square marks the reference point for the start of rendering (shifted from the path start by a startOffset value of 75%). The gray arrow(s) shows the direction of typographic character placement and the point at which typographic character placement stops. The arrow(s) would be reversed if the direction property has a value of rtl.

Rendering all glyphs was agreed to for basic shapes at the Sydney (2015) meeting (but missing in minutes). Limiting the wrapping to a path with a single closed sub-path and to one loop, effected by the 'startOffset' attribute agreed to at the London (2016) Editor's Meeting.

Value
<length> | <percentage> | <number>
initial value
0
Animatable
yes
method

Indicates the method by which text should be rendered along the path.

A value of align indicates that the typographic character should be rendered using simple 2x3 transformations such that there is no stretching/warping of the typographic characters. Typically, supplemental rotation, scaling and translation transformations are done for each typographic characters to be rendered. As a result, with align, fonts where the typographic characters are designed to be connected (e.g., cursive fonts), the connections may not align properly when text is rendered along a path.

A value of stretch indicates that the typographic character outlines will be converted into paths, and then all end points and control points will be adjusted to be along the perpendicular vectors from the path, thereby stretching and possibly warping the glyphs. With this approach, connected typographic characters, such as in cursive scripts, will maintain their connections. (Non-vertical straight path segments should be converted to Bézier curves in such a way that horizontal straight paths have an (approximately) constant offset from the path along which the typographic characters are rendered.)

English and Arabic text on arcs.

Rendering of text on a path for different method values: Left: 'align'. Right: 'stretch'.

Value
align | stretch
initial value
align
Animatable
yes
spacing

Indicates how the user agent should determine the spacing between typographic characters that are to be rendered along a path.

A value of exact indicates that the typographic characters should be rendered exactly according to the spacing rules as specified in Text on a path layout rules.

A value of auto indicates that the user agent should use text-on-a-path layout algorithms to adjust the spacing between typographic characters in order to achieve visually appealing results.

Value
auto | exact
initial value
exact
Animatable
yes
side

Determines the side of the path the text is placed on (relative to the path direction). Specifying a value of right effectively reverses the path.

Two circular path with different values of 'side'
		  showing glyphs rendered outside the circle for
		  'left' and inside the circle for 'right'.

Rendering for text on a path referencing a circle with different values of the side attribute. Left: left. Right: right.

Added in SVG 2 to allow text either inside or outside closed subpaths and basic shapes (e.g. rectangles, circles, and ellipses).

Adding 'side' was resolved at the Sydney (2015) meeting.

Value
left | right
initial value
left
Animatable
yes
path

A path data string describing the path onto which the typographic characters will be rendered. An empty string indicates that there is no path data for the element. This means that the text within the textPath does not render or contribute to the bounding box of the text element.

Value
path data
initial value
an empty string
Animatable
yes
href

An URL reference to the path element or basic shape element onto which the glyphs will be rendered. If <url> is an invalid reference (e.g., no such element exists, or the referenced element is not a path element) or basic shape, then the textPath element is in error and its entire contents shall not be rendered by the user agent.

Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.

Value
URL [URL]
initial value
See above.
Animatable
yes

The path data coordinates within the referenced path element or basic shape element are assumed to be in the same coordinate system as the current text element, not in the coordinate system where the path element is defined. The transform attribute on the referenced path element or basic shape element represents a supplemental transformation relative to the current user coordinate system for the current text element, including any adjustments to the current user coordinate system due to a possible transform property on the current text element. For example, the following fragment of SVG content:

<svg xmlns="http://www.w3.org/2000/svg">
  <g transform="translate(25,25)">
    <defs>
      <path id="path1" transform="scale(2)" path="..." fill="none" stroke="red"/>
    </defs>
  </g>
  <text transform="rotate(45)">
    <textPath href="#path1">Text on a path1</textPath>
  </text>
</svg>
  

should have the same effect as the following:

<svg xmlns="http://www.w3.org/2000/svg">
  <g transform="rotate(45)">
    <defs>
      <path id="path1" transform="scale(2)" path="..." fill="none" stroke="red"/>
    </defs>
    <text>
      <textPath href="#path1">Text on a path1</textPath>
    </text>
  </g>
</svg>
  

Note that the transform="translate(25,25)" has no effect on the textPath element, whereas the transform="rotate(45)" applies to both the text and the use of the path element as the referenced shape for text on a path. Further note that the transform="scale(2)" scales the path but does not scale the text placed along the path.

Example toap01 provides a simple example of text on a path:

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="3.6cm" viewBox="0 0 1000 300" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <defs>
    <path id="MyPath"
          d="M 100 200 
             C 200 100 300   0 400 100
             C 500 200 600 300 700 200
             C 800 100 900 100 900 100" />
  </defs>
  <desc>Example toap01 - simple text on a path</desc>

  <use href="#MyPath" fill="none" stroke="red"  />
  <text font-family="Verdana" font-size="42.5" fill="blue" >
    <textPath href="#MyPath">
      We go up, then we go down, then up again
    </textPath>
  </text>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="998" height="298"
        fill="none" stroke="blue" stroke-width="2" />
</svg>
Example toap01 — simple text on a path

Example toap01

View this example as SVG (SVG-enabled browsers only)

Example toap02 shows how tspan elements can be included within textPath elements to adjust styling attributes and adjust the current text position before rendering a particular glyph. The first occurrence of the word "up" is filled with the color red. Attribute dy is used to lift the word "up" from the baseline.

The x, y, dx, dy, and rotate attributes can only be specified on text and tspan elements (but may effect the rendering of glyphs in text on a path — see text on a path layout rules).

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="3.6cm" viewBox="0 0 1000 300" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <defs>
    <path id="MyPath"
          d="M 100 200 
             C 200 100 300   0 400 100
             C 500 200 600 300 700 200
             C 800 100 900 100 900 100" />
  </defs>
  <desc>Example toap02 - tspan within textPath</desc>

  <use href="#MyPath" fill="none" stroke="red"  />
  <text font-family="Verdana" font-size="42.5" fill="blue" >
    <textPath href="#MyPath">
      We go 
      <tspan dy="-30" fill="red" >
        up
      </tspan>
      <tspan dy="30">
        ,
      </tspan>
      then we go down, then up again
    </textPath>
  </text>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="998" height="298"
        fill="none" stroke="blue" stroke-width="2" />
</svg>
Example toap02 — tspan within textPath

Example toap02

View this example as SVG (SVG-enabled browsers only)

Example toap03 demonstrates the use of the startOffset attribute on the textPath element to specify the start position of the text string as a particular position along the path. Notice that glyphs that fall off the end of the path are not rendered (see text on a path layout rules).

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="3.6cm" viewBox="0 0 1000 300" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <defs>
    <path id="MyPath"
          d="M 100 200 
             C 200 100 300   0 400 100
             C 500 200 600 300 700 200
             C 800 100 900 100 900 100" />
  </defs>
  <desc>Example toap03 - text on a path with startOffset attribute</desc>

  <use href="#MyPath" fill="none" stroke="red"  />
  <text font-family="Verdana" font-size="42.5" fill="blue" >
    <textPath href="#MyPath" startOffset="80%">
      We go up, then we go down, then up again
    </textPath>
  </text>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="998" height="298"
        fill="none" stroke="blue" stroke-width="2" />
</svg>
Example toap03 — text on a path with startOffset attribute

Example toap03

View this example as SVG (SVG-enabled browsers only)

10.8.3. Text on a path layout rules

Conceptually, for text on a path the target path is stretched out into either a horizontal or vertical straight line segment. For horizontal text layout flows, the path is stretched out into a hypothetical horizontal line segment such that the start of the path is mapped to the left of the line segment. For vertical text layout flows, the path is stretched out into a hypothetical vertical line segment such that the start of the path is mapped to the top of the line segment. The standard text layout rules are applied to the hypothetical straight line segment and the result is mapped back onto the target path. Vertical and bidirectional text layout rules also apply to text on a path.

The orientation of each glyph along a path is determined individually. For horizontal text layout flows, the default orientation (the up direction) for a given glyph is along the vector that starts at the intersection point on the path to which the glyph is attached and which points in the direction 90 degrees counter-clockwise from the angle of the curve at the intersection point. For vertical text layout flows, the default orientation for a given glyph is along the vector that starts at the intersection point on the path to which the glyph is attached and which points in the direction 180 degrees from the angle of the curve at the intersection point.

Left, horizontal text with the character 'A' on a path.
	      Right, vertical text with the character '字' on a path.

Default glyph orientation along a path. Left, horizontal text. Right: vertical text.

Example toap04 will be used to illustrate the particular layout rules for text on a path that supplement the basic text layout rules for straight line horizontal or vertical text.

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="3.6cm" viewBox="0 0 1000 300" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <defs>
    <path id="MyPath"
          d="M 100 125 
             C 150 125 250 175 300 175
             C 350 175 450 125 500 125
             C 550 125 650 175 700 175
             C 750 175 850 125 900 125" />
  </defs>
  <desc>Example toap04 - text on a path layout rules</desc>

  <use href="#MyPath" fill="none" stroke="red"  />
  <text font-family="Verdana" font-size="60" fill="blue" letter-spacing="2" >
    <textPath href="#MyPath">
      Choose shame or get war 
    </textPath>
  </text>

  <!-- Show outline of viewport using 'rect' element -->
  <rect x="1" y="1" width="998" height="298"
        fill="none" stroke="blue" stroke-width="2" />
</svg>
Example toap04 — text on a path layout rules

Example toap04

View this example as SVG (SVG-enabled browsers only)

The following picture does an initial zoom in on the first glyph in the text element.

Image that shows text
	    on a path

The small dot above shows the point at which the glyph is attached to the path. The box around the glyph shows the glyph is rotated such that its horizontal axis is parallel to the tangent of the curve at the point at which the glyph is attached to the path. The box also shows the glyph's charwidth (i.e., the amount which the current text position advances horizontally when the glyph is drawn using horizontal text layout).

The next picture zooms in further to demonstrate the detailed layout rules.

Image that shows text on a path

For left-to-right horizontal text layout along a path (i.e., when the glyph orientation is perpendicular to the inline-base direction the layout rules are as follows:

Comparable rules are used for top-to-bottom vertical text layout along a path (i.e., when the glyph orientation is parallel with the inline-base direction, the layout rules are as follows:

In the calculations above, if either the startpoint-on-the-path or the endpoint-on-the-path is off the end of the path, then extend the path beyond its end points with a straight line that is parallel to the tangent at the path at its end point so that the midpoint-on-the-path can still be calculated.

When the inline-base direction is horizontal, then any ‘x’ attributes on text or tspan elements represent new absolute offsets along the path, thus providing explicit new values for startpoint-on-the-path. Any ‘y’ attributes on text or tspan elements are ignored. When the inline-base direction is vertical, then any ‘y’ attributes on text or tspan elements represent new absolute offsets along the path, thus providing explicit new values for startpoint-on-the-path. Any ‘x’ attributes on text or tspan elements are ignored.

Text that follows a textPath element (but is still inside a text element) that does not have explicit positioning information (x and y attributes) is positioned from the end of the path.

Text on a path showing the starting point for
	      rendering text after the <textPath> element.

The starting point for text after the textPath element without explicit positioning information is at the end of the path (red dot).

The choice of the end of the path over the position of the last character was chosen as it is more author predictable (not depending on font, etc.) Decided at the London (2016) editor's meeting. See also GitHub Issue 84.

10.9. Text rendering order

A text element is rendered in one or more chunks. Each chunk (as produced by the text layout algorithm) is rendered, one after the other, in document order. Each rendered chunk, which consists of one or more glyphs, is filled and stroked as if it were a single path.

For the purposes of painting, a text has zero, one, or more equivalent paths, one for each chunk. Each equivalent path consists of one subpath per glyph within that chunk.

Since the fill-rule property does not apply to SVG text elements, the specific order of the subpaths within the equivalent path does not matter.

The specific position of the start of each subpath, and the direction that the path progresses around glyph shape, is not defined.

This means that dashed strokes on text may not place the dash pattern at the same positions across different implementations.

10.10. Properties and pseudo-elements

CSS offers a multitude of properties for styling text. In general, only two sets of properties are applicable to SVG: those that determine which glyphs are to be rendered (font-family, font-style, etc.) and those that apply at the paragraph level (direction, writing-mode, line-height, letter-spacing, etc.).

The list of CSS properties that must be supported on SVG text elements can be found in the the Styling chapter.

Additionally, the @font-face rule must be supported for font selection as well as the ::first-line and ::first-letter pseudo-elements must be supported on text elements.

Other CSS properties that affect text layout and rendering may also be supported by an SVG user agent; their effect should be taken into account as part of the CSS text layout step of the overall SVG text layout process.

For example, while SVG 2 does not require support for the text-combine-upright property, its behavior in an SVG context should be obvious.

A number of CSS properties must not have any effect on SVG text elements:

Additionally, the ::before and ::after generated content pseudo-elements must not apply to SVG text elements.

10.10.1. SVG properties

This section covers properties that are not covered elsewhere in this specification and that are specific to SVG.

10.10.1.1. Text alignment, the ‘text-anchor’ property

The text-anchor property is used to align (start-, middle- or end-alignment) a string of pre-formatted text or auto-wrapped text where the wrapping area is determined from the the inline-size property relative to a given point. It is not applicable to other types of auto-wrapped text, see instead text-align. For multi-line text, the alignment takes place for each line.

The text-anchor property is applied to each individual text chunk within a given text element. Each text chunk has an initial current text position, which represents the point in the user coordinate system resulting from (depending on context) application of the x and y attributes on the text element, any x or y attribute values on a tspan element assigned explicitly to the first rendered character in a text chunk, or determination of the initial current text position for a textPath element. Each text chunk also has a final current text position which is the current text position after placing the last glyph in the text chunk. The positions are determined before applying the text-anchor property.

Name: text-anchor
Value: start | middle | end
Initial: start
Applies to: text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

Values have the following meanings:

start
The rendered characters are aligned such that the start of the resulting rendered text is at the initial current text position. For an element with a direction property value of "ltr" (typical for most European languages), the left side of the text is rendered at the initial text position. For an element with a direction property value of "rtl" (typical for Arabic and Hebrew), the right side of the text is rendered at the initial text position. For an element with a vertical primary text direction (often typical for Asian text), the top side of the text is rendered at the initial text position.
middle
The rendered characters are shifted such that the geometric middle of the resulting rendered text (determined from the initial and final current text position before applying the text-anchor property) is at the initial current text position.
end
The rendered characters are shifted such that the end of the resulting rendered text (final current text position before applying the text-anchor property) is at the initial current text position. For an element with a direction property value of "ltr" (typical for most European languages), the right side of the text is rendered at the initial text position. For an element with a direction property value of "rtl" (typical for Arabic and Hebrew), the left side of the text is rendered at the initial text position. For an element with a vertical primary text direction (often typical for Asian text), the bottom of the text is rendered at the initial text position.

An example of using text-anchor on multi-line text.

<svg xmlns="http://www.w3.org/2000/svg"
     width="300" height="100" viewBox="0 0 300 100">

  <text x="150" y="30" style="font: 20px sans-serif; white-space: pre-line;
                              text-anchor: middle;">
    This multi-line text is
    anchored to the middle.</text>

</svg>
Image showing two lines of text centered via text-anchor.

The preserved line-feed creates two text chunks, each anchored independently.

Another example of using text-anchor on multi-line text.

<svg xmlns="http://www.w3.org/2000/svg"
     width="200" height="150" viewBox="0 0 200 150">
  <path d="m 100,0 0,150" style="fill:none;stroke:#add8e6"/>
  <text x="100 100 100" y="50 95 140"
	style="font-size: 42px; text-anchor: middle">I❤SVG</text>
</svg>
Image showing three lines of text divided as 'I', '❤', 'SVG'.

The text is divided into three text chunks (due to the three coordinates in the x and y attributes). Each text chunk is independently anchored.

10.10.1.2. The ‘glyph-orientation-horizontal’ property

This property has been removed in SVG 2.

10.10.1.3. The ‘glyph-orientation-vertical’ property

This property applies only to vertical text. It has been obsoleted in SVG 2 and partially replaced by the text-orientation property of CSS Writing Modes Level 3. The following SVG 1.1 values must still be supported by aliasing the property as a shorthand to text-orientation as follows:

Any other values must be treated as invalid.

10.10.1.4. The ‘kerning’ property

The ‘kerning’ property has been removed in SVG 2.

SVG 1.1 uses the 'kerning' property to determine if the font kerning tables should be used to adjust inter-glyph spacing. It also allows a <length> value which if given is added to the spacing between glyphs (supplemental to any from the letter-spacing property). This property is replaced in SVG 2 by the CSS font-kerning property which solely controls turning on/off the use of the font kerning tables.

Chrome's UseCounter data showed a use of 0.01% in 2014. See GitHub issue 80.

10.10.2. SVG adaptions

This section covers CSS properties that are not covered elsewhere in this specification and have either SVG specific adaptions or are significantly altered from SVG 1.1.

SVG 2 Requirement: Reference CSS3 Fonts.
Resolution: SVG 2 will depend on CSS3 Fonts.
Purpose: Alignment with CSS 2.1 and CSS3 for Web font functionality, and to provide access to advanced typographic features of fonts.
Owner: Chris (ACTION-3123)

10.10.2.1. The ‘font-variant’ property

CSS Font Module Level 3 changes the meaning of the 'font-variant' property from that defined by CSS 2.1. It has been repurposed (and its functionality greatly expanded) as a shorthand for selecting font variants from within a single font.

SVG 2 requires all font-variant subproperties to be implemented (e.g. font-variant-ligatures).

10.10.2.2. The ‘line-height’ property

SVG uses the line-height property to determine the amount of leading space which is added between lines in multi-line text (both for horizontal and vertical text). It is not applicable to text on a path.

Except for the additional information provided here, the normative definition of the line-height property is in the CSS 2.1 specification ([CSS21]).

The CSS Inline Module Level 3 may update the definition of 'line-height'.

10.10.2.3. The ‘writing-mode’ property

This property sets the block-flow direction; or in-other-words, the direction in which lines of text are stacked. As a consequence it also determines if the text has a horizontal or vertical orientation.

SVG 2 references CSS Writing Modes Level 3 for the definition of the 'writing-mode' property. That specification introduces new values for the property. The SVG 1.1 values are obsolete but must still be supported by converting the specified values to computed values as follows:

In SVG 1.0, this property could be interpreted as to also setting the inline-base direction leading to confusion about its role relative to the direction property. SVG 1.1 was a bit more specific about the role of direction (e.g. that direction set the reference point for the text-anchor property) but still was open to interpretation. The fact that neither SVG 1.0 nor SVG 1.1 allowed multi-line text added to the confusion.

Except for the additional information provided here, the normative definition of the writing-mode property is in CSS Writing Modes Level 3 ([CSSWRITINGMODES3]).

10.10.2.4. The ‘direction’ property

The property specifies the inline-base direction of a text or tspan element. It defines the start and end points of a line of text as used by the text-anchor and inline-size properties. It also may effect the direction in which characters are positioned if the unicode-bidi property's value is either embed or bidi-override.

The direction property applies only to glyphs oriented perpendicular to the inline-base direction, which includes the usual case of horizontally-oriented Latin or Arabic text and the case of narrow-cell Latin or Arabic characters rotated 90 degrees clockwise relative to a top-to-bottom inline-base direction.

Check this agrees with CSS3 Writing modes.

Except for the additional information provided here, the normative definition of the direction property is in CSS Writing Modes Level 3 ([CSSWRITINGMODES3]).

In many cases, the bidirectional algorithm from Unicode [UNICODE] produces the desired result automatically, and in such cases the author does not need to use these properties. For other cases, such as when using right-to-left languages, it may be sufficient to add the direction property to the outermost svg element, and allow that direction to inherit to all text elements, as in the following example (which may be used as a template):

<svg xmlns="http://www.w3.org/2000/svg"
     width="100%" height="100%" viewBox="0 0 600 72"
     direction="rtl" xml:lang="fa">

  <title direction="ltr" xml:lang="en">Right-to-left Text</title>
  <desc direction="ltr" xml:lang="en">
    A simple example for using the 'direction' property in documents
    that predominantly use right-to-left languages.
  </desc>

  <text x="300" y="50" text-anchor="middle" font-size="36">داستان SVG 1.1 SE طولا ني است.</text>

</svg>
Example

Example

View this example as SVG (SVG-enabled browsers only)

Below is another example, where where implicit bidi reordering is not sufficient:

<?xml version="1.0" encoding="utf-8"?>
<svg xmlns="http://www.w3.org/2000/svg"
     width="100%" height="100%" viewBox="0 0 600 72"
     direction="rtl" xml:lang="he">

  <title direction="ltr" xml:lang="en">Right-to-left Text</title>
  <desc direction="ltr" xml:lang="en">
    An example for using the 'direction' and 'unicode-bidi' properties
    in documents that predominantly use right-to-left languages.
  </desc>

  <text x="300" y="50" text-anchor="middle" font-size="36"> כתובת MAC:&#x200F;
    <tspan direction="ltr" unicode-bidi="embed">00-24-AF-2A-55-FC</tspan> 
  </text>

</svg>
Example

Example

View this example as SVG (SVG-enabled browsers only)

10.10.2.5. The ‘dominant-baseline’ property

This property is defined in the CSS Line Layout Module 3 specification. See 'dominant-baseline'. [CSS3INLINE]

SVG 2 introduces some changes to the definition of this property. In particular:

SVG uses the value of the dominant-baseline property to align glyphs relative to the x and y attributes. For the text-orientation value sideways, the auto value for dominant-baseline is alphabetic; however, for backwards compatibility, the glyphs should be aligned to the x and y attributes using the value central.

We are interested in any actual use where one would prefer the old behavior.

The SVG 1.1 definition of the dominant-baseline property was derived from the XSL specification. (See XSL 'dominant-baseline'.)

10.10.2.6. The ‘alignment-baseline’ property

This property is defined in the CSS Line Layout Module 3 specification. See 'alignment-baseline'. [CSS3INLINE]

The vertical-align property shorthand should be preferred in new content.

SVG 2 introduces some changes to the definition of this property. In particular: the values 'auto', 'before-edge', and 'after-edge' have been removed. For backwards compatibility, 'text-before-edge' should be mapped to 'text-top' and 'text-after-edge' should be mapped to 'text-bottom'. Neither 'text-before-edge' nor 'text-after-edge' should be used with the vertical-align property.

10.10.2.7. The ‘baseline-shift’ property

This property is defined in the CSS Line Layout Module 3 specification. See 'baseline-shift'. [CSS3INLINE]

The vertical-align property shorthand should be preferred in new content.

The SVG 1.1 initial value 'baseline' has been removed from SVG 2. User agents may support this value as computing to '0' if necessary to support legacy SVG content.

Do we need to support the SVG 1.1 'baseline' value?

The 'baseline' value was removed with the conversion of 'vertical-align' to a shorthand for 'alignment-baseline' and 'baseline-shift' as it is also a value for 'alignment-baseline' and it is redundant with a length value of '0'.

SVG 2 Requirement: Align with CSS for baseline alignment functionality.
Resolution: SVG 2 will deprecate ‘baseline-shift’ and use ‘vertical-align’ instead.
Purpose: To align with CSS.
Owner: Cameron (ACTION-3281)

'baseline-shift' is important for aligning subscripts and superscripts (Inkscape relies on it for this purpose). It remains in the CSS Inline Layout Module Level 3. 'vertical-align' is a shorthand for changing multiple properties at once, including 'baseline-shift'.

10.10.2.8. The ‘letter-spacing’ property

SVG 2 removes percentage values from the letter-spacing property.

Except as noted, see CSS Text Level 3 for the definition of the letter-spacing.([CSS3TEXT]).

Percentage values based on the SVG viewport are not seen as useful. This brings the definition of 'letter-spacing' in line with CSS.

10.10.2.9. The ‘word-spacing’ property

SVG 2 changes the meaning of percentage values for the word-spacing property. In SVG 1.1, percentages define additional spacing as a percentage of the SVG viewport size. In SVG 2, following CSS Text Level 3, percentages define additional spacing as a percentage of the affected character's width.

Except as noted, see CSS Text Level 3 for the definition of the word-spacing.([CSS3TEXT]).

Percentage values based on the SVG viewport are not seen as useful. This brings the definition of 'word-spacing' in line with CSS.

10.10.2.10. The ‘text-overflow’ property

SVG 2 Requirement: Add text-overflow functionality.
Resolution: We will add text-overflow in SVG 2.
Purpose: To align with CSS, allow indicating that not all text is shown.
Owner: Erik (ACTION-3003)

New in SVG 2. Added to allow user agents to handle text strings that overflow a predefined wrapping area in a more useful way. Aligns SVG and HTML/CSS text processing.

See the CSS3 UI specification for the definition of of 'text-overflow'. [CSS3UI]

SVG uses the text-overflow property to control how text content block elements render when text overflows line boxes as, for example, can happen when the white-space property has the value nowrap. The property does not apply to pre-formatted text or text-on-a-path.

In SVG text-overflow has an effect if there is a validly specified wrapping area, regardless of the computed value of the overflow property on the text content block element.

If the text-overflow property has the value ellipsis then if the text that is to be rendered overflows the wrapping area an ellipsis is rendered such that it fits within the given area. For the purposes of rendering, the ellipsis is treated as if it replaced the characters at the point where it is inserted.

If the text-overflow property has the value clip then any text that overflows the wrapping area is clipped. Characters may be partially rendered.

Any other value for text-overflow is treated as if it wasn't specified.

Note that the effect of text-overflow is purely visual, the ellipsis itself does not become part of the DOM. For all the DOM methods it is as if text-overflow was not applied, and as if the wrapping area did not constrain the text.

The following example shows the use of text-overflow. The top line shows text as it would normally be rendered (text overflows due to white-space value pre and is displayed due to overflow value visible). The middle line shows text with text-overflow value clip, and the bottom line shows text with text-overflow value ellipsis.

<svg xmlns="http://www.w3.org/2000/svg"
     width="300" height="150" viewBox="0 0 300 150">
  <style>
    text { font: 25px sans-serif; white-space: pre; }
    path { fill: none; stroke: #add8e6; }
  </style>

  <path d="m  50,0 0,150"/>
  <path d="m 200,0 0,150"/>

  <text x="50" y="35"  inline-size="100" style="overflow:visible">SVG is awesome</text>
  <text x="50" y="85"  inline-size="100" style="text-overflow:clip">SVG is awesome</text>
  <text x="50" y="135" inline-size="100" style="text-overflow:ellipsis">SVG is awesome</text>

</svg>
Image showing the use of the text-overflow property.

The text-overflow property used on text elements, the bottom line showing text with an ellipsis applied.

It has been argued that this property is useless. It would be of more use if coupled with a mechanism that would expose the hidden text (tool-tip on hovering over ellipses?). The text-overflow property only deals with text that overflows off the end of a line. It does not deal with text that overflows the off the end of the wrapping area.

10.10.3. White space

New in SVG 2. Added white-space to allow a more useful way to control white-space handling. Aligns SVG and HTML/CSS text processing. xml:space deprecated in new content, retained for backwards compatibility.

10.10.3.1. SVG 2 Preferred white space handling, the ‘white-space’ property

Rendering of white space in SVG 2 is controlled by the white-space property. This specifies two things:

Name: white-space
Value: normal | pre | nowrap | pre-wrap | pre-line
Initial: not defined for shorthand properties
Applies to: text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: see individual properties
Animatable: yes

Values and their meanings are defined in CSS3 Text Module Level 3.[CSS3INLINE]

An example of using the white-space value pre-line.

<svg xmlns="http://www.w3.org/2000/svg">
     width="200" height="200" viewBox="0 0 200 200">

     <text x="150" y="30" style="font: 20px IPAMincho; writing-mode: vertical-rl;
	                         white-space: pre-line;">
       千利奴流乎和加
       餘多連曽津祢那
       良牟有為能於久
       耶万計不己衣天
       阿佐伎喩女美之
       恵比毛勢須</text>
</svg>
Japanese poem showing traditional line-breaking after every seven kanji.

Example of multi-line vertical text with line breaks. The text is from the Japanese poem Iroha. The lines are broken at traditional places. Example does not render properly in Firefox. It is SVG 1.1 text. Bad Firefox.

10.10.3.2. Legacy white-space handling, the ‘xml:space’ property

For compatibility, SVG 2 also supports the XML attribute xml:space to specify the handling of white space characters within a given text element's character data. New content should not use xml:space but instead, use the white-space property.

This section should be simplified to limit the discussion of xml:space and instead define it in the user agent style sheet using the white-space property. The CSS Text 4 specification's preserve-spaces value for the 'white-space-collapse' property is intended to match xml:space=preserve. (fantasai agreed to add an appropriate value for white-space to match SVG 1.1's odd xml:space="preserve" behavior.)

Note that any child element of a text element may also have an xml:space attribute which will apply to that child element's text content. The SVG user agent has special processing rules associated with this attribute as described below. These are behaviors that occur subsequent to XML parsing [XML10] and any construction of a DOM.

xml:space is an inheritable attribute which can have one of two values:

'default'
(The initial/default value for xml:space.) When xml:space="default", the SVG user agent will do the following using a copy of the original character data content. First, it will remove all newline characters. Then it will convert all tab characters into space characters. Then, it will strip off all leading and trailing space characters. Then, all contiguous space characters will be consolidated.
'preserve'
When xml:space="preserve", the SVG user agent will do the following using a copy of the original character data content. It will convert all newline and tab characters into space characters. Then, it will draw all space characters, including leading, trailing and multiple contiguous space characters. Thus, when drawn with xml:space="preserve", the string "a   b" (three spaces between "a" and "b") will produce a larger separation between "a" and "b" than "a b" (one space between "a" and "b").

The following example illustrates that line indentation can be important when using xml:space="default". The fragment below show two pairs of similar text elements, with both text elements using xml:space="default". For these examples, there is no extra white space at the end of any of the lines (i.e., the line break occurs immediately after the last visible character).

[01]  <text xml:space='default'>
[02]    WS example
[03]    indented lines
[04]  </text>
[05]  <text xml:space='preserve'>WS example indented lines</text>
[06]
[07]  <text xml:space='default'>
[08]WS example
[09]non-indented lines
[10]  </text>
[11]  <text xml:space='preserve'>WS examplenon-indented lines</text>
  

The first pair of text elements above show the effect of indented character data. The attribute xml:space="default" in the first text element instructs the user agent to:

The second pair of text elements above show the effect of non-indented character data. The attribute xml:space="default" in the third text element instructs the user agent to:

Note that XML parsers are required to convert the standard representations for a newline indicator (e.g., the literal two-character sequence "U+000D U+000A", CARRIAGE-RETURN LINE-FEED or the stand-alone literals U+000D or U+000A) into the single character U+000A before passing character data to the application. Thus, each newline in SVG will be represented by the single character U+000A, no matter what representation for newlines might have been used in the original resource. (See XML end-of-line handling.)

Any features in the SVG language or the SVG DOM that are based on character position number, such as the x, y, dx, dy and rotate attributes on the text and tspan elements, are based on character position after applying the white space handling rules described here. In particular, if xml:space="default", it is often the case that white space characters are removed as part of processing. Character position numbers index into the text string after the white space characters have been removed per the rules in this section.

Note that a glyph corresponding to a white-space character should only be displayed as a visible but blank space, even if the glyph itself happens to be non-blank. See display of unsupported characters [UNICODE].

The xml:space attribute is:

    Animatable: no.

10.10.3.3. Duplicate white-space directives

Older, SVG 1.1 content will use xml:space. New content, and older content that is being reworked, will use white-space and remove any existing xml:space. However, user agents may come across content which uses both methods on the same element. If the white-space property is set on any element, then the value of xml:space is ignored.

10.11. Text decoration

Text in SVG can be decorated with an underline, overline, and/or strike-through. The position and style of the decoration is determined respectively by the text-decoration-line and text-decoration-style properties, or by the text-decoration shorthand property as defined in the Line Decoration section of the CSS Text Decoration Module Level 3 [(CSS3TEXTDECOR)] specification. The fill and stroke of the decoration are given by the text-decoration-fill and text-decoration-stroke properties. If a color value is specified either by the text-decoration-color property or by the text-decoration shorthand, and no text-decoration-fill property is specified, it is interpreted as if the text-decoration-fill property were specified with that color value.

If the fill or stroke of the text decoration are not explicitly specified (via text-decoration, text-decoration-color, text-decoration-fill, or text-decoration-stroke), they are given by the fill and stroke of the text at the point where the text decoration is declared (see example below).

The text-decoration-line and text-decoration-style properties are new in SVG 2. The SVG 1.1/CSS 2.1 text-decoration property is transformed in a backwards compatible way to a short hand for these properties. text-decoration-fill and text-decoration-stroke are SVG specific properties which may be added to a future level of the CSS Text Decoration specification.

The order in which the text and decorations are drawn is defined by the Painting Order of Text Decorations section of CSS Text Decoration Module Level 3. The paint order of the text decoration itself (fill/stroke) is determined by the value of the paint-order property at the point where the text decoration is declared.

Example textdecoration01 provides examples for text-decoration. The first line of text has no value for text-decoration, so the initial value of text-decoration:none is used. The second line shows text-decoration:line-through. The third line shows text-decoration:underline. The fourth line illustrates the rule whereby decorations are rendered using the same fill and stroke properties as are present on the element for which the text-decoration is specified. Since text-decoration is specified on the text element, all text within the text element has its underline rendered with the same fill and stroke properties as exist on the text element (i.e., blue fill, red stroke), even though the various words have different fill and stroke property values. However, the word "different" explicitly specifies a value for text-decoration; thus, its underline is rendered using the fill and stroke properties as the tspan element that surrounds the word "different" (i.e., yellow fill, darkgreen stroke):

<?xml version="1.0" standalone="no"?>
<svg width="12cm" height="4cm" viewBox="0 0 1200 400"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example textdecoration01 - behavior of 'text-decoration' property</desc>
  <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="2" />
  <g font-size="60" fill="blue" stroke="red" stroke-width="1" >
    <text x="100" y="75">Normal text</text>
    <text x="100" y="165" text-decoration="line-through" >Text with line-through</text>
    <text x="100" y="255" text-decoration="underline" >Underlined text</text>
    <text x="100" y="345" text-decoration="underline" >
      <tspan>One </tspan>
      <tspan fill="yellow" stroke="purple" >word </tspan>
      <tspan fill="yellow" stroke="black" >has </tspan>
      <tspan fill="yellow" stroke="darkgreen" text-decoration="underline" >different </tspan>
      <tspan fill="yellow" stroke="blue" >underlining</tspan>
    </text>
  </g>
</svg>
Example textdecoration01 — behavior of 'text-decoration' property

Example textdecoration01

View this example as SVG (SVG-enabled browsers only)

10.11.1. The ‘text-decoration-fill’ and ‘text-decoration-stroke’ properties

The CSS working group agreed to the SVG specification of the 'text-decoration-fill' and 'text-decoration-stroke' properties at the joint CSS/SVG 2014 TPAC meeting. They again endorsed the use of these properties at the joint 2015 Sydney meeting. They expressed their intention to extend CSS text decoration to include these properties at the same time they allow 'fill' and 'stroke' properties on text.

Name: text-decoration-fill
Value: <paint>
Initial: See prose.
Applies to: text content elements
Inherited: See prose.
Percentages: N/A
Media: visual
Computed value: as specified, but with <color> values computed and <url> values made absolute.
Animatable: yes
Name: text-decoration-stroke
Value: <paint>
Initial: See prose.
Applies to: text content elements
Inherited: See prose.
Percentages: N/A
Media: visual
Computed value: as specified, but with <color> values computed and <url> values made absolute.
Animatable: yes

10.12. Text selection and clipboard operations

Conforming SVG viewers on systems which have the capacity for text selection (e.g., systems which are equipped with a pointer device such as a mouse) and which have system clipboards for copy/paste operations are required to support:

A text selection operation starts when all of the following occur:

As the text selection operation proceeds (e.g., the user continues to press the given mouse button), all associated events with other graphics elements are ignored (i.e., the text selection operation is modal) and the SVG user agent shall dynamically indicate which characters are selected by an appropriate highlighting technique, such as redrawing the selected glyphs with inverse colors. As the pointer is moved during the text selection process, the end glyph for the text selection operation is the glyph within the same text element whose glyph cell is closest to the pointer. All characters within the text element whose position within the text element is between the start of selection and end of selection shall be highlighted, regardless of position on the canvas and regardless of any graphics elements that might be above the end of selection point.

Once the text selection operation ends (e.g., the user releases the given mouse button), the selected text will stay highlighted until an event occurs which cancels text selection, such as a pointer device activation event (e.g., pressing a mouse button).

Detailed rules for determining which characters to highlight during a text selection operation are provided in Text selection implementation notes.

For systems which have system clipboards, the SVG user agent is required to provide a user interface for initiating a copy of the currently selected text to the system clipboard. It is sufficient for the SVG user agent to post the selected text string in the system's appropriate clipboard format for plain text, but it is preferable if the SVG user agent also posts a rich text alternative which captures the various font properties associated with the given text string.

For bidirectional text, the user agent must support text selection in logical order, which will result in discontinuous highlighting of glyphs due to the bidirectional reordering of characters. User agents can provide an alternative ability to select bidirectional text in visual rendering order (i.e., after bidirectional text layout algorithms have been applied), with the result that selected character data might be discontinuous logically. In this case, if the user requests that bidirectional text be copied to the clipboard, then the user agent is required to make appropriate adjustments to copy only the visually selected characters to the clipboard.

When feasible, it is recommended that generators of SVG attempt to order their text strings to facilitate properly ordered text selection within SVG viewing applications such as Web browsers.

10.13. DOM interfaces

SVG 2 Requirement: Have a DOM method to convert a text element to outline path data.
Resolution: We will add a DOM method to convert a ‘text’ element to outline path data, possibly moving the functionality to the FXTF.
Purpose: To allow manipulation of text as a path.
Owner: Cameron (ACTION-3076)

10.13.1. Interface SVGTextContentElement

The SVGTextContentElement interface is implemented by elements that support rendering child text content.

For the methods on this interface that refer to an index to a character or a number of characters, these references are to be interpreted as an index to a UTF-16 code unit or a number of UTF-16 code units, respectively. This is for consistency with DOM Level 2 Core, where methods on the CharacterData interface use UTF-16 code units as indexes and counts within the character data. Thus for example, if the text content of a text element is a single non-BMP character, such as U+10000, then invoking getNumberOfChars on that element will return 2 since there are two UTF-16 code units (the surrogate pair) used to represent that one character.

interface SVGTextContentElement : SVGGraphicsElement {

  // lengthAdjust Types
  const unsigned short LENGTHADJUST_UNKNOWN = 0;
  const unsigned short LENGTHADJUST_SPACING = 1;
  const unsigned short LENGTHADJUST_SPACINGANDGLYPHS = 2;

  [SameObject] readonly attribute SVGAnimatedLength textLength;
  [SameObject] readonly attribute SVGAnimatedEnumeration lengthAdjust;

  long getNumberOfChars();
  float getComputedTextLength();
  float getSubStringLength(unsigned long charnum, unsigned long nchars);
  DOMPoint getStartPositionOfChar(unsigned long charnum);
  DOMPoint getEndPositionOfChar(unsigned long charnum);
  DOMRect getExtentOfChar(unsigned long charnum);
  float getRotationOfChar(unsigned long charnum);
  long getCharNumAtPosition(DOMPoint point);
  void selectSubString(unsigned long charnum, unsigned long nchars);
};

The numeric length adjustment type constants defined on SVGTextContentElement are used to represent the keyword values that the lengthAdjust attribute can take. Their meanings are as follows:

ConstantMeaning
LENGTHADJUST_SPACINGThe spacing keyword.
LENGTHADJUST_SPACINGANDGLYPHSThe spacingAndGlyphs keyword.
LENGTHADJUST_UNKNOWNSome other value.

The textLength IDL attribute reflects the textLength content attribute.

The lengthAdjust IDL attribute reflects the lengthAdjust content attribute. The numeric type values for lengthAdjust are as described above in the numeric length adjust type constant table.

The getNumberOfChars method is used to determine the total number of characters available for rendering within the current element. When getNumberOfChars() is called, the following steps are run:

  1. Let text be the result that would be obtained from getting the textContent IDL attribute on the current element.
  2. Return the length of text.

The getComputedTextLength method is used to compute a "length" for the text within the element. When getComputedTextLength() is called, the following steps are run:

  1. Let count be the value that would be returned if the getNumberOfChars method were called on this element.
  2. Let length be the value that would be returned if the getSubStringLength method were called on this element, passing 0 and count as arguments.
  3. Return length.

The getSubStringLength method is used to compute a "length" for a substring of text within the element. When getSubStringLength(charnum, nchars) is called, the following steps are run:

  1. Assign an index to each character in the DOM within this element, where the first character has index 0.
  2. If charnum is greater than the highest index assigned to a character or if nchars, then throw an IndexSizeError.
  3. Let length be a length in user units, initialized to 0.
  4. For each character in the DOM within this element that has an index such that charnum ≤ index < (charnum + nchars):
    1. If the character corresponds to a typographic character and it is the first character in document order to correspond to that typographic character, then:
      1. Add the advance of the typographic character to length.
      2. If the letter-spacing or word-spacing properties contributed space just after the typographic character, then add that space to length.

      This means that, for example, if you have a ligature that crosses the boundary between two tspan elements, the advance of the typographic character and any subsequent letter-spacing or word-spacing space will be assigned to the first tspan element's text length.

  5. Return length.

To find the typographic character for a character at index index within an element element, the following steps are run:

  1. Assign an index to each character in the DOM within this element, where the first character has index 0.
  2. Let last be the highest index assigned to a character.
  3. While charnum < last and the character at index charnum does not correspond to a typographic character:
    1. Set charnum to charnum + 1.
  4. If charnum is greater than the highest index assigned to a character or, then return null.
  5. Otherwise, return the typographic character that corresponds to charnum.

The getStartPositionOfChar method is used to get the position of a typographic character after text layout has been performed. When getStartPositionOfChar(charnum) is called, the following steps are run:

  1. Let cluster be the result of finding the typographic character for the character at index charnum within the current element.
  2. If cluster is null, then then throw an IndexSizeError.
  3. Let p be the alignment point of the typographic character that correspond to the character at index charnum, in the coordinate system of the current element.
  4. Return a newly created, detached DOMPoint object representing the point p.

The getEndPositionOfChar method is used to get the trailing position of a typographic character after text layout has been performed. When getEndPositionOfChar(charnum) is called, the following steps are run:

  1. Let cluster be the result of finding the typographic character for the character at index charnum within the current element.
  2. If cluster is null, then then throw an IndexSizeError.
  3. Let p be the alignment point of cluster that correspond to the character at index charnum, in the coordinate system of the current element.
  4. Let direction be a unit vector in the direction of the cluster's advance. This direction takes into account the writing mode being used, the direction of the character, the text-orientation, glyph-orientation-horizontal and glyph-orientation-vertical properties, any rotate value that applies to cluster, and any rotation applied to due a textPath.
  5. Let advance be cluster's advance.
  6. Set p to p + advance · direction.
  7. Return a newly created, detached DOMPoint object representing the point p.

The getExtentOfChar method is used to compute a tight bounding box of the glyph cell that corresponds to a given typographic character. When getExtentOfChar(charnum) is called, the following steps are run:

  1. Let cluster be the result of finding the typographic character for the character at index charnum within the current element.
  2. If cluster is null, then then throw an IndexSizeError.
  3. Let quad be the potentially rotated rectangle in the current element's coordinate system that is the glyph cell for cluster.
  4. Let rect be the rectangle that forms the tightest bounding box around quad in the current element's coordinate system.
  5. Return a newly created DOMRect object representing the rectangle rect.

The getRotationOfChar method is used to get the rotation of typographic character. When getRotationOfChar(charnum) is called, the following steps are run:

  1. Let cluster be the result of finding the typograhic character for the character at index charnum within the current element.
  2. If cluster is null, then then throw an IndexSizeError.
  3. Let direction be the angle in degrees that represents the direction of the cluster's advance. This direction takes into account the writing mode being used, the direction of the character, the text-orientation, glyph-orientation-horizontal and glyph-orientation-vertical properties, any rotate value that applies to cluster, and any rotation applied to due a textPath.
  4. Return direction.

The getCharNumAtPosition method is used to find which character caused a typographic character to be rendered at a given position. When getCharNumAtPosition(point) is called, the following steps are run:

  1. Assign an index to each character in the DOM within this element, where the first character has index 0.
  2. Let last be the highest index assigned to a character.
  3. Let charnum be 0.
  4. Let result be -1.
  5. While charnum < last:
    1. If the character at index charnum corresponds to a typographic character and it is the first character in document order to correspond to that typographic character, and point in this element's coordinate system is within the glyph cell for the typographic character, then set result to charnum.
  6. Return result.

The selectSubString method is used to select text within the element. When selectSubString(charnum, nchars) is called, the following steps are run:

Selects a substring of the text in this element, beginning at character index charnum and extending forwards nchars characters. The following steps must be followed when this method is called:

  1. Let node be this text content element.
  2. Let count be the number of characters in this text content element.
  3. Let end = charnum + nchars.
  4. If charnumcount or endcount, then throw an IndexSizeError.
  5. Remove all ranges from the document's selection. [DOM4][EDITING]
  6. Set the selection's direction to forwards.
  7. Add to the selection a new range whose start is the boundary point tuple (node, charnum) and end is the boundary point tuple (node, end).

Ignoring the argument checking and exception throwing, this is equivalent to performing the following:

var selection = document.getSelection();
selection.removeAllRanges();
var range = new Range();
range.setStart(textContentElement, charnum);
range.setEnd(textContentElement, charnum + nchars);
selection.addRange(range);

This method is deprecated, as it duplicates functionality from the Selection API.

10.13.2. Interface SVGTextPositioningElement

The SVGTextPositioningElement interface is implemented by elements that support attributes that position individual text glyphs. It is inherited by SVGTextElement and SVGTSpanElement.

interface SVGTextPositioningElement : SVGTextContentElement {
  [SameObject] readonly attribute SVGAnimatedLengthList x;
  [SameObject] readonly attribute SVGAnimatedLengthList y;
  [SameObject] readonly attribute SVGAnimatedLengthList dx;
  [SameObject] readonly attribute SVGAnimatedLengthList dy;
  [SameObject] readonly attribute SVGAnimatedNumberList rotate;
};

The x, y, dx, dy and rotate IDL attributes reflect the x, y, dx, dy and rotate content attributes, respectively.

10.13.3. Interface SVGTextElement

An SVGTextElement object represents a text element in the DOM.

interface SVGTextElement : SVGTextPositioningElement {
};

10.13.4. Interface SVGTSpanElement

An SVGTSpanElement object represents a tspan element in the DOM.

interface SVGTSpanElement : SVGTextPositioningElement {
};

10.13.5. Interface SVGTextPathElement

An SVGTextPathElement object represents a textPath element in the DOM.

interface SVGTextPathElement : SVGTextContentElement {

  // textPath Method Types
  const unsigned short TEXTPATH_METHODTYPE_UNKNOWN = 0;
  const unsigned short TEXTPATH_METHODTYPE_ALIGN = 1;
  const unsigned short TEXTPATH_METHODTYPE_STRETCH = 2;

  // textPath Spacing Types
  const unsigned short TEXTPATH_SPACINGTYPE_UNKNOWN = 0;
  const unsigned short TEXTPATH_SPACINGTYPE_AUTO = 1;
  const unsigned short TEXTPATH_SPACINGTYPE_EXACT = 2;

  [SameObject] readonly attribute SVGAnimatedLength startOffset;
  [SameObject] readonly attribute SVGAnimatedEnumeration method;
  [SameObject] readonly attribute SVGAnimatedEnumeration spacing;
};

SVGTextPathElement implements SVGURIReference;

The numeric method type constants defined on SVGTextPathElement are used to represent the keyword values that the method attribute can take. Their meanings are as follows:

ConstantMeaning
TEXTPATH_METHODTYPE_ALIGNThe align keyword.
TEXTPATH_METHODTYPE_STRETCHThe stretch keyword.
TEXTPATH_METHODTYPE_UNKNOWNSome other value.

The numeric spacing type constants defined on SVGTextPathElement are used to represent the keyword values that the spacing attribute can take. Their meanings are as follows:

ConstantMeaning
TEXTPATH_SPACINGTYPE_AUTOThe auto keyword.
TEXTPATH_SPACINGTYPE_EXACTThe exact keyword.
TEXTPATH_SPACINGTYPE_UNKNOWNSome other value.

The startOffset IDL attribute reflects the startOffset content attribute.

The method IDL attribute reflects the method content attribute. The numeric type values for method are as described above in the numeric method type constant table.

The spacing IDL attribute reflects the spacing content attribute. The numeric type values for spacing are as described above in the numeric spacing type constant table.

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 11: Embedded Content

SVG 2 Requirement: - Allow HTML5 elements in SVG: audio, canvas, iframe and video.
Resolution: - Allow audio, canvas, iframe and video elements from HTML5, don't introduce almost the same but slightly different SVG NS elements.
Purpose: To allow various HTML embedded content elements to be used directly in SVG and support dynamic loading of content.
Owner: Nobody

11.1. Overview

Embedded content is content that imports another resource into the document, or content from another vocabulary that is inserted into the document. This is the same definition as HTML5's embedded content.

SVG supports embedded content with the use of image and foreignObject elements.

Additionally SVG allows embedded content using HTML5 'video', 'audio', 'iframe' and 'canvas' elements.

Except canvas and foreignObject, embedded content supports Resource Priorities for hinting of downloading external resources.

11.2. Placement of the referenced resource

Attribute definitions:

Name Value Initial value Animatable
x, y <length> 0 yes
width, height <length> | auto 0 yes

The x and y, width and height attributes specify the rectangular region into which the referenced resource is placed.

A negative value for width and height is invalid (see Error processing). A value of zero for either attribute disables rendering of the element.

The 'auto' value for width and height is used to size the corresponding element automatically based on the intrinsic size or aspect ratio of the referenced resource. If the intrinsic aspect ratio of the referenced resource is unknown, it is assumed to be 2:1. If the intrinsic size of the referenced resource is unknown, it is assumed to be 300x150, just as is required for CSS replaced elements. If 'auto' is specified for just one of width or height, then the other is determined based on the intrinsic aspect ratio. The automatically determined width and height values are interpreted as user units, and are reflected in the x and y IDL attributes as SVG_LENGTHTYPE_NUMBER values.

11.3. The ‘image’ element

image
Categories:
Graphics element, graphics referencing element, renderable element, structurally external element
Content model:
Any number of the following elements, in any order:clipPath, mask, script, style
Attributes:
DOM Interfaces:

The image element indicates that the contents of a complete file are to be rendered into a given rectangle within the current user coordinate system. The image element can refer to raster image files such as PNG or JPEG or to files with MIME type of "image/svg+xml". Conforming SVG viewers need to support at least PNG, JPEG and SVG format files. SVG files must be processed in secure animated mode if the current document supports animation, or in secure static mode if the current document is static.

The result of processing an image is always a four-channel RGBA result. When an image element references a raster image file such as PNG or JPEG files which only has three channels (RGB), then the effect is as if the object were converted into a 4-channel RGBA image with the alpha channel uniformly set to 1. For a single-channel raster image, the effect is as if the object were converted into a 4-channel RGBA image, where the single channel from the referenced object is used to compute the three color channels and the alpha channel is uniformly set to 1.

For image elements referencing a file with MIME type of "image/svg+xml", the preserveAspectRatio attribute on the root element in the referenced SVG image is ignored (see preserveAspectRatio for details). Instead, the preserveAspectRatio attribute on the referencing image element defines how the SVG image content is fit into the viewport.

The value of the viewBox attribute to use when evaluating the preserveAspectRatio attribute is defined by the referenced content. For content that clearly identifies a viewBox (e.g. an SVG file with the viewBox attribute on the outermost svg element) that value should be used. For most raster content (PNG, JPEG) the bounds of the image should be used (i.e. the image element has an implicit viewBox of '0 0 raster-image-width raster-image-height'). Where no value is readily available (e.g. an SVG file with no viewBox attribute on the outermost svg element) the preserveAspectRatio attribute is ignored, and only the translation due to the x & y attributes of the viewport is used to display the content.

To link into particular view of the SVG document, authors can use media fragments as defined in Linking into SVG content.

For example, if the image element referenced a PNG or JPEG and preserveAspectRatio="xMinYMin meet", then the aspect ratio of the raster would be preserved (which means that the scale factor from image's coordinates to current user space coordinates would be the same for both X and Y), the raster would be sized as large as possible while ensuring that the entire raster fits within the viewport, and the top/left of the raster would be aligned with the top/left of the viewport as defined by the attributes x, y, width and height on the image element.  If the value of preserveAspectRatio was 'none' then aspect ratio of the image would not be preserved. The image would be fit such that the top/left corner of the raster exactly aligns with coordinate (x, y) and the bottom/right corner of the raster exactly aligns with coordinate (x+width, y+height).

The resource referenced by the image element represents a separate document which generates its own parse tree and document object model (if the resource is XML). Thus, there is no inheritance of properties into the image.

Unlike use, the image element cannot reference elements within an SVG file.

SVG 2 Requirement: Support auto-sized images.
Resolution: We will allow auto-sized images in SVG 2.
Purpose: To allow raster images to use their own size without the need to set width and height.
Owner: Cameron (ACTION-3340)
SVG 2 Requirement: Support selecting part of an image for display.
Resolution: We will have a method for ‘image’ to select a part of an image to display, maybe by allowing ‘viewBox’ on it.
Purpose: To allow selection of part of an image without requiring the author to manually slice the image.
Owner: Nobody
SVG 2 Requirement: Support the ‘object-fit’ and ‘object-position’ properties from css3-images.
Resolution: SVG 2 will depend on CSS3 Image Values and CSS4 Image Values.
Purpose: To align with the CSS way of specifying image fitting that preserveAspectRatio provides.
Owner: Cameron or Erik (no action)

Attribute definitions:

Name Value Initial value Animatable
crossorigin [ anonymous | use-credentials ]? (see HTML definition of attribute) yes

The crossorigin attribute is a CORS settings attribute, and unless otherwise specified follows the same processing rules as in html [HTML].

Name Value Initial value Animatable
href URL [URL] (none) yes

An URL reference identifying the image to render. Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.

The URL is processed and the resource is fetched as described in the Linking chapter.

<?xml version="1.0" standalone="no"?>
<svg width="4in" height="3in"
     xmlns="http://www.w3.org/2000/svg">
  <desc>This graphic links to an external image
  </desc>
  <image x="200" y="200" width="100px" height="100px"
         href="myimage.png">
    <title>My image</title>
  </image>
</svg>

Since image references always refer to a complete document, a target-only URL is treated as a link to the same file, which is rendered again as an independent embedded image. Since the embedded image is processed in a secure mode, its own embedded references are not processed, preventing infinite recursion.

<?xml version="1.0" standalone="no"?>
<svg width="5cm" height="3cm" viewBox="0 0 50 30" 
     xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Recursive SVG</title>
  <desc>An SVG with two recursive image reference to itself.
    One reference uses the file name as a relative URL, 
    the other uses a target fragment only.
    When viewed in a processing mode that supports external file references,
    the embedded images should be rendered;
    however, the embedded image must be processed in secure mode,
    so the recursion only happens once.
    The appearance should be three nested red circles in a bulls-eye pattern;
    the innermost circle has solid fill because of target styles.
  </desc>
  <style type="text/css">
    #target:target {
      fill: red;
    }
  </style>
  <circle id="target" 
          stroke="red" stroke-width="5" fill="none"
          cx="50%" cy="50%" r="12" />
  <image xlink:href="recursive-image.svg"
         x="25%" y="25%" width="50%" height="50%" />
  <image xlink:href="#target"
         x="45%" y="45%" width="10%" height="10%" />
</svg>
Example recursive-image — an SVG that embeds itself, creating a bulls-eye pattern

Example recursive-image

View this example as SVG (SVG-enabled browsers only)

11.4. HTML5 elements in SVG subtrees

The following HTML5 elements render when included in an SVG subtree as a child of a container element and when using the HTML namespace:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml">
  <html:video src="file.mp4" controls="controls">
  </html:video>
</svg>

HTML elements, in the HTML namespace, used as children of 'video', 'audio', 'iframe' and 'canvas' elements within an SVG document fragment behave as specified in HTML. This applies in particular to fallback content; if fallback content is rendered, the embedded element behaves like an SVG foreignObject element to contain the HTML content. This would occur, for example, for a video element if the user agent does not support the specified video formats, or for a canvas element if scripting is disabled.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml">
  <html:video src="http://example.org/dummyvideo" controls="controls">
    <html:p>Video format not supported by your browser</html:p>
  </html:video>
</svg>

The HTML specification is applicable also for the 'track' and 'source' elements.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml">
  <html:video src="file.mp4" controls="controls">
    <html:source src="file.webm" type='video/webm;codecs="vp8, vorbis"'/>
    <html:source src="file.mp4" type='video/mp4;codecs="avc1.42E01E, mp4a.40.2"'/>
  </html:video>
</svg>

The HTML subtree, defined by the root HTML element and its children, contributes to SVG container bounding box computations.

CSS positioning properties (e.g. 'top') are not allowed for positioning the HTML subtree root element in the SVG coordinate system. The HTML element can be positioned in the SVG coordinate system using the transform property or by positioning the current SVG viewport.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml">
  <html:video style="transform:translate(10px,10px)" src="http://example.org/dummyvideo" controls="controls">
    <html:p>Video format not supported by your browser</html:p>
  </html:video>
</svg>

For the purpose of sizing the HTML subtree root element, the HTML 'width' and 'height' attributes and the CSS sizing properties (e.g. width or 'min-width') are used. For the purpose of resolving percentage values in the element sizing or in the layout and positioning of children elements in the HTML subtree, the current SVG viewport is defined to be the containing block of the HTML subtree.

Note that html specification says that 'width' and 'height' attributes of embedded content of html accepts integer. Accordingly, if you want to point to a floating point number for those sizing, you should use css sizing property instead of such html attributes.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml" viewBox="0 0 640 480">
  <html:video style="min-width:50%" src="http://example.org/dummyvideo" controls="controls">
  </html:video>
</svg>
<svg xmlns="http://www.w3.org/2000/svg" xmlns:html="http://www.w3.org/1999/xhtml" viewBox="0 0 640 480">
  <html:video src="http://example.org/dummyvideo" controls="controls">
    <html:p style="width: 50%">Video format not supported by your browser</html:p>
  </html:video>
</svg>

As SVG elements are implicitly positioned, the root of the HTML subtree has block display.

The 'width' and 'height' attributes of the HTML elements are defined by the HTML specification and are not SVG geometry properties. In particular, they do accept units. The 'width' and 'height' properties do.

Other HTML5 elements in an SVG subtree, when used outside of a foreignObject element, in any namespace, are treated as unknown elements.

The HTML5 elements in the HTML namespace in an SVG subtree, itself nested in an HTML5 document, are not parsed by the HTML parser as HTML elements. In such case, the nested HTML elements should be created and inserted in the DOM using DOM APIs

11.5. Foreign namespaces and private data

SVG allows inclusion of elements from foreign namespaces anywhere within the SVG content. In general, the SVG user agent will include the unknown elements in the DOM but will otherwise ignore unknown elements. (The notable exception is described under Embedding Foreign Object Types.) Also see the handling of unknown elements.

Additionally, SVG allows inclusion of attributes from foreign namespaces on any SVG element. The SVG user agent will include unknown attributes in the DOM but will otherwise ignore unknown attributes.

SVG's ability to include foreign namespaces can be used for the following purposes:

To illustrate, a business graphics authoring application might want to include some private data within an SVG document so that it could properly reassemble the chart (a pie chart in this case) upon reading it back in:

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
     xmlns = 'http://www.w3.org/2000/svg'>
  <defs>
    <myapp:piechart xmlns:myapp="http://example.org/myapp"
                    title="Sales by Region">
      <myapp:pieslice label="Northern Region" value="1.23"/>
      <myapp:pieslice label="Eastern Region" value="2.53"/>
      <myapp:pieslice label="Southern Region" value="3.89"/>
      <myapp:pieslice label="Western Region" value="2.04"/>
      <!-- Other private data goes here -->
    </myapp:piechart>
  </defs>
  <desc>This chart includes private data in another namespace
  </desc>
  <!-- In here would be the actual SVG graphics elements which
       draw the pie chart -->
</svg>

11.6. Embedding foreign object types

One goal for SVG is to provide a mechanism by which other XML language processors can render into an area within an SVG drawing, with those renderings subject to the various transformations and compositing parameters that are currently active at a given point within the SVG content tree. One particular example of this is to provide a frame for XML content styled with CSS or XSL so that dynamically reflowing text (subject to SVG transformations and compositing) could be inserted into the middle of some SVG content. Another example is inserting a MathML expression into an SVG drawing [MATHML].

The foreignObject element allows for inclusion of a foreign namespace which has its graphical content drawn by a different user agent. The included foreign graphical content is subject to SVG transformations, filters, clipping, masking and compositing.

The contents of foreignObject are assumed to be from a different namespace. Any SVG elements within a foreignObject will not be drawn, except in the situation where a properly defined SVG subdocument with a proper ‘xmlns’ (see Namespaces in XML [XML-NS]) attribute specification is embedded recursively. One situation where this can occur is when an SVG document fragment is embedded within another non-SVG document fragment, which in turn is embedded within an SVG document fragment (e.g., an SVG document fragment contains an XHTML document fragment which in turn contains yet another SVG document fragment).

Usually, a foreignObject will be used in conjunction with the switch element and the requiredExtensions attribute to provide proper checking for user agent support and provide an alternate rendering in case user agent support is not available.

11.7. The ‘foreignObject’ element

foreignObject
Categories:
Graphics element, renderable element, structurally external element
Content model:
Any elements or character data.
Attributes:
Geometry properties:
DOM Interfaces:

The x and y attributes define the coordinates of the left and top edges of the 'foreignObject', in the current user coordinate system.

The width and height attributes define width and height of the 'foreignObject' respectively. A negative value for either attribute is an error (see Error processing). A value of zero for either attribute disables rendering of the element.

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
 xmlns = 'http://www.w3.org/2000/svg'>
  <desc>This example uses the 'switch' element to provide a
        fallback graphical representation of an paragraph, if
        XMHTML is not supported.</desc>
  <!-- The 'switch' element will process the first child element
       whose testing attributes evaluate to true.-->
  <switch>
    <!-- Process the embedded XHTML if the requiredExtensions attribute
         evaluates to true (i.e., the user agent supports XHTML
         embedded within SVG). -->
    <foreignObject width="100" height="50"
                   requiredExtensions="http://example.com/SVGExtensions/EmbeddedXHTML">
      <!-- XHTML content goes here -->
      <body xmlns="http://www.w3.org/1999/xhtml">
        <p>Here is a paragraph that requires word wrap</p>
      </body>
    </foreignObject>
    <!-- Else, process the following alternate SVG.
         Note that there are no testing attributes on the 'text' element.
         If no testing attributes are provided, it is as if there
         were testing attributes and they evaluated to true.-->
    <text font-size="10" font-family="Verdana">
      <tspan x="10" y="10">Here is a paragraph that</tspan>
      <tspan x="10" y="20">requires word wrap.</tspan>
    </text>
  </switch>
</svg>

It is not required that SVG user agent support the ability to invoke other arbitrary user agents to handle embedded foreign object types; however, all conforming SVG user agents would need to support the switch element and must be able to render valid SVG elements when they appear as one of the alternatives within a switch element.

Ultimately, it is expected that commercial Web browsers will support the ability for SVG to embed content from other XML grammars which use CSS or XSL to format their content, with the resulting CSS- or XSL-formatted content subject to SVG transformations and compositing. At this time, such a capability is not a requirement.

11.8. DOM interfaces

11.8.1. Interface SVGImageElement

An SVGImageElement object represents an image element in the DOM.

interface SVGImageElement : SVGGraphicsElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
  [SameObject] readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;
  attribute DOMString? crossOrigin;
};

SVGImageElement implements SVGURIReference;

The x, y, width and height IDL attributes reflect the computed values of the x, y, width and height properties and their corresponding presentation attributes, respectively.

The preserveAspectRatio IDL attribute reflects the preserveAspectRatio content attribute.

The crossOrigin IDL attribute reflects the crossorigin content attribute.

11.8.2. Interface SVGForeignObjectElement

An SVGForeignObjectElement object represents a foreignObject in the DOM.

interface SVGForeignObjectElement : SVGGraphicsElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
};

The x, y, width and height IDL attributes reflect the computed values of the x, y, width and height properties and their corresponding presentation attributes, respectively.

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 12: Painting: Filling, Stroking and Marker Symbols

12.1. Introduction

12.1.1. Definitions

fill
The operation of painting the interior of a shape or the interior of the character glyphs in a text string.
stroke
The operation of painting the outline of a shape or the outline of character glyphs in a text string.

Graphical elements that define a shape – path elements, basic shapes, and text content elements – are rendered by being filled, which is painting the interior of the object, and stroked, which is painting along the outline of the object. Filling and stroking are both painting operations. SVG 2 supports a number of different paints that the fill and stroke of a graphical element can be painted with:

The paint to use for filling and stroking an element is specified using the fill and stroke properties. The following section describes the different values that can be used for these properties.

Other properties, such as fill-opacity and stroke-width, also have an effect on the way fill and stroke paint is applied to the canvas. The Fill properties and Stroke properties sections below describe these properties.

Some graphics elements – path elements and basic shapes – can also have marker symbols drawn at their vertices or at other positions along the path that they describe. The Markers section below describes how markers can be defined and used.

SVG 2 adds markers on shapes. Resolved at Tokyo F2F.

12.2. Specifying paint

SVG 2 Requirement: Add new paint values for referencing current fill paint, stroke paint, etc.
Resolution: We will add new paint values currentFillPaint, currentStrokePaint etc. to SVG 2
Purpose: Among other things, to provide an easy way to match marker color to stroke color.
Owner: Chris (ACTION-3094)
SVG 2 Addition: Allow multiple paints in fill and stroke.
Resolution: We will allow multiple paints in the fill and stroke properties in SVG 2.
Purpose: Useful for creating cross hatchings, putting a partially transparent pattern on top of a solid fill, etc.
Owner: Tav (ACTION-3500)

The fill and stroke properties, defined below, are used to specify the paint used to render the interior of and the stroke around shapes and text. A paint specification describes a way of putting color values on to the canvas and is composed of one or more paint layers. Four types of paints within these paint layers are supported: solid colors, gradients, patterns, and hatches.

A <paint> value is defined as follows:

<paint> = [ [ <paint-layer> , ]* <final-paint-layer> ] | context-fill | context-stroke

<paint-layer> = <paint-source>

<final-paint-layer> = <paint-source> || <color>

<paint-source> = none | child | child(<integer>) | <url>

The ability to apply more than one paint layer to an element is new in SVG 2.

A <paint> value can either be a comma-separated list of paint layers, or one of the context keywords, which reference the paint value of fill or stroke from a context element. Each paint layer can take one of the following values:

<url>
A URL reference to a paint server element, which is an element that defines a paint server: hatch, linearGradient, meshgradient, pattern, radialGradient and solidcolor.
child
A reference to the last child paint server element of the element being painted.
child(n)
A reference to the nth child paint server element of the element being painted.
none
No paint is applied in this layer.

The list of paint layers describes the sequence of paint servers and an optional color to render within the fill or stroke shape. These paint layers are rendered, one after another, in reverse order – that is, the right-most paint layer (the <final-paint-layer> value) is rendered first, then the next paint layer to the left is rendered, and so on proceeding left. Multiple paint layers can be used to build up a composite paint made up of more than one semi-transparent paint.

The reverse rendering order used here follows the rendering order of the CSS background properties.

<rect width="100" height="100" fill="url(#MyHatch1), url(#MyHatch2), powderblue">
  
An example of applying three paints to a rectangle.

The rightmost rectangle is filled by stacking the paints shown in the other rectangles.

The child keyword value references the last child paint server element and the child(n) function references the nth child paint server element (where the first has index 1). A value for n less than 1 is invalid and causes the entire property value to be invalid.

<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
    <rect width="50" height="50" x="25" y="25" fill="child, skyblue" stroke="grey">
        <pattern viewBox="0 0 100 100" width="20%" height="20%">
            <path d="M0,0 h40 L100,60 v40 z m 0,60 v40 h40 z" fill="red" />
        </pattern>
        <pattern viewBox="0 0 100 100" width="20%" height="20%">
            <path d="M0,0 h40 L100,60 v40 z m 0,60 v40 h40 z" fill="grey" />
        </pattern>
    </rect>
</svg>
An example of the child keyword for paint

The paint server used to fill the rect element is a child element of the shape being filled. Note that there are two child paint servers and the last paint server is the one matched to the child keyword.

A <final-paint-layer> allows a paint server reference, a <color> value, or both to be given. When both are given, the <color> value is a fallback color to use if the paint server reference in the layer is invalid (due to pointing to an element that does not exist or which is not a valid paint server). When only a paint server reference is given, it is used as the paint just as in any other <paint-layer>. When only a <color> is given, the color is used as the paint unconditionally.

Note that this is slightly different from CSS background syntax, where a background image and color specified in the final layer of a background value will result in both the image and color being rendered. The fallback nature of the color in SVG <paint> values is needed for compatibility with SVG 1.1, which supported only a single paint server reference plus a fallback color.

If a paint server reference in a <paint-layer> is invalid, then no paint is rendered for that layer.

This is changed from SVG 1.1 behavior where the document is in error if a paint server reference is invalid and there is no fallback color specified.

<rect width="100" height="100" fill="url(#MyHatch1), url(#MyHatch2) powderblue">
  
An example with a fallback solid paint fill.

The left rectangle shows the expected fill if both MyHatch1 and MyHatch2 are defined. The right rectangle shows the expected fill if MyHatch1 is defined but MyHatch2 is missing.

For a <color> value in the final paint layer, all color syntaxes defined in CSS Color Module Level 3 must be supported, including rgb(), rgba(), hsl(), hsla(), the extended color keywords and the currentColor value.

The context-fill and context-stroke values are a reference to the paint layers generated for the fill or stroke property, respectively, of the context element of the element being painted. The context element of an element is defined as follows:

If there is no context element and these keywords are used, then no paint is applied.

When the context paint layers include paint server references, then the coordinate space and the bounding box used to scale the paint server elements and content are those of the context element. In other words, any gradients and patterns referenced with these keywords should be continuous from the main shape to the markers, or from one element within a use-element shadow tree to another.

If the referenced value of fill or stroke is a context-fill and context-stroke value, then those contextual referencing is recursive.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <style>
    path {
      fill: none;
      stroke-width: 4px;
      marker: url(#diamond);
    }
  </style>
  <path d="M 10,50 v -20 h 40 v -20" stroke="red"/>
  <path d="M 30,70 v -20 h 40 v -20" stroke="green"/>
  <path d="M 50,90 v -20 h 40 v -20" stroke="blue"/>
  <marker id="diamond" markerWidth="12" markerHeight="12" refX="6" refY="6"
          markerUnits="userSpaceOnUse">
    <circle cx="6" cy="6" r="3"
            fill="white" stroke="context-stroke" stroke-width="2"/>
  </marker>
</svg>
An example of the content-stroke keyword used in a marker

The marker is defined using a shape whose stroke is set to context-stroke. This causes the marker to take on the color of each path element that uses the marker.

12.3. The effect of the ‘color’ property

See the CSS Color Module Level 3 specification for the definition of color. [CSS3COLOR]

The color property is used to provide a potential indirect value, currentColor, for the fill, stroke, solid-color, stop-color, flood-color and lighting-color properties. The property has no other effect on SVG elements.

The following example shows how the inherited value of the color property from an HTML document can be used to set the color of SVG text in an inline SVG fragment.

<!DOCTYPE html>
<style>
body { color: #468; font: 16px sans-serif }
svg { border: 1px solid #888; background-color: #eee }
</style>
<p>Please see the diagram below:</p>
<svg width="200" height="100">
  <g fill="currentColor">
    <text x="70" y="55" text-anchor="end">START</text>
    <text x="130" y="55">STOP</text>
    <path d="M 85,45 h 25 v -5 l 10,10 -10,10 v -5 h -25 z"/>
  </g>
</svg>

Please see the diagram below:

START STOP

The text and arrow in the SVG fragment are filled with the same color as the inherited color property.

12.4. Fill properties

12.4.1. Specifying fill paint: the ‘fill’ property

Name: fill
Value: <paint>
Initial: black
Applies to: shapes and text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified, but with <color> values computed and <url> values made absolute
Animatable: yes

The fill property paints the interior of the given graphical element. The area to be painted consists of any areas inside the outline of the shape. To determine the inside of the shape, all subpaths are considered, and the interior is determined according to the rules associated with the current value of the fill-rule property. The zero-width geometric outline of a shape is included in the area to be painted.

The fill operation fills open subpaths by performing the fill operation as if an additional "closepath" command were added to the path to connect the last point of the subpath with the first point of the subpath. Thus, fill operations apply to both open subpaths within path elements (i.e., subpaths without a closepath command) and polyline elements.

12.4.2. Winding rule: the ‘fill-rule’ property

Name: fill-rule
Value: nonzero | evenodd
Initial: nonzero
Applies to: shapes and text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

The fill-rule property indicates the algorithm (or winding rule) which is to be used to determine what parts of the canvas are included inside the shape. For a simple, non-intersecting path, it is intuitively clear what region lies "inside"; however, for a more complex path, such as a path that intersects itself or where one subpath encloses another, the interpretation of "inside" is not so obvious.

The fill-rule property provides two options for how the inside of a shape is determined:

nonzero

This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a path segment crosses the ray from left to right and subtract one each time a path segment crosses the ray from right to left. After counting the crossings, if the result is zero then the point is outside the path. Otherwise, it is inside. The following drawing illustrates the nonzero rule:

Image showing nonzero fill rule

The effect of a nonzero fill rule on paths with self-intersections and enclosed subpaths.

evenodd

This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and counting the number of path segments from the given shape that the ray crosses. If this number is odd, the point is inside; if even, the point is outside. The following drawing illustrates the evenodd rule:

Image showing evenodd fill rule

The effect of an evenodd fill rule on paths with self-intersections and enclosed subpaths.

The above descriptions do not specify what to do if a path segment coincides with or is tangent to the ray. Since any ray will do, one may simply choose a different ray that does not have such problem intersections.

12.4.3. Fill paint opacity: the ‘fill-opacity’ property

Name: fill-opacity
Value: <number>
Initial: 1
Applies to: shapes and text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified, but clamped to the range [0, 1]
Animatable: yes

fill-opacity specifies the opacity of the painting operation used to paint the interior the current object. (See Painting shapes and text.) A value of 0 means fully transparent, and a value of 1 means fully opaque.

See also the opacity property, which specifies group opacity.

12.5. Stroke properties

SVG 2 Requirement: Support non-scaling stroke.
Resolutions: SVG 2 will include non-scaling stroke.
SVG 2 will have the ‘vector-effect’ property.
Purpose: To support strokes whose width does not change when zooming a page, as common for example in maps.
Owner: Chris or Erik (no action)
Note: Note that this could be part of more generic non-scaling features.

In this section, we define a number of properties that allow the author to control different aspects of a stroke, including its paint, thickness, use of dashing, and joining and capping of path segments.

In all cases, all stroking properties which are affected by directionality, such as those having to do with dash patterns, must be rendered such that the stroke operation starts at the same point at which the graphics element starts. In particular, for path elements, the start of the path is the first point of the initial "moveto" command.

For stroking properties such as dash patterns whose computations are dependent on progress along the outline of the graphics element, distance calculations are required to utilize the SVG user agent's standard Distance along a path algorithms.

When stroking is performed using a complex paint server, such as a gradient or a pattern, the stroke operation must be identical to the result that would have occurred if the geometric shape defined by the geometry of the current graphics element and its associated stroking properties were converted to an equivalent path element and then filled using the given paint server.

12.5.1. Specifying stroke paint: the ‘stroke’ property

Name: stroke
Value: <paint>
Initial: none
Applies to: shapes and text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified, but with <color> values computed and <url> values made absolute
Animatable: yes

The stroke property paints along the outline of the given graphical element.

Note that when stroking a path element, any subpath consisting of a moveto but no following line drawing command will not be stroked. Any other type of zero-length subpath, such as 'M 10,10 L 10,10' or 'M 30,30 Z' will also not be stroked if the stroke-linecap property has a value of butt. See the definition of the stroke shape below for the details of computing the stroke of a path.

SVG 2 Requirement: Include a way to specify stroke position.
Resolution: SVG 2 shall include a way to specify stroke position.
Purpose: To allow a stroke to be inside or outside the path.
Owner: Cameron (ACTION-3162)
Note: See proposal page.

12.5.2. Stroke paint opacity: the ‘stroke-opacity’ property

Name: stroke-opacity
Value: <number>
Initial: 1
Applies to: shapes and text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified, but clamped to the range [0, 1]
Animatable: yes

The stroke-opacity property specifies the opacity of the painting operation used to stroke the current object. (See Painting shapes and text.) As with fill-opacity, a value of 0 means fully transparent, and a value of 1 means fully opaque.

See also the opacity property, which specifies group opacity.

12.5.3. Stroke width: the ‘stroke-width’ property

Name: stroke-width
Value: <percentage> | <length>
Initial: 1
Applies to: shapes and text content elements
Inherited: yes
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

This property specifies the width of the stroke on the current object. A zero value causes no stroke to be painted. A negative value is invalid.

12.5.4. Drawing caps at the ends of strokes: the ‘stroke-linecap’ property

Name: stroke-linecap
Value: butt | round | square
Initial: butt
Applies to: shapes and text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

stroke-linecap specifies the shape to be used at the end of open subpaths when they are stroked, and the shape to be drawn for zero length subpaths whether they are open or closed. The possible values are:

butt
This value indicates that the stroke for each subpath does not extend beyond its two endpoints. A zero length subpath will therefore not have any stroke.
round

This value indicates that at each end of each subpath, the shape representing the stroke will be extended by a half circle with a diameter equal to the stroke width. If a subpath, whether open or closed, has zero length, then the resulting effect is that the stroke for that subpath consists solely of a full circle centered at the subpath's point.

square

This value indicates that at the end of each subpath, the shape representing the stroke will be extended by a rectangle with the same width as the stroke width and whose length is half of the stroke width. If a subpath, whether open or closed, has zero length, then the resulting effect is that the stroke for that subpath consists solely of a square with side length equal to the stroke width, centered at the subpath's point, and oriented such that two of its sides are parallel to the effective tangent at that subpath's point. See ‘path’ element implementation notes for details on how to determine the tangent at a zero-length subpath.

Image showing three paths, each with a different line cap.

The three types of line caps.

See the definition of the cap shape below for a more precise description of the shape a line cap will have.

12.5.5. Controlling line joins: the ‘stroke-linejoin’ and ‘stroke-miterlimit’ properties

Name: stroke-linejoin
Value: miter | miter-clip | round | bevel | arcs
Initial: miter
Applies to: shapes and text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

stroke-linejoin specifies the shape to be used at the corners of paths or basic shapes when they are stroked. For further details see the path implementation notes.

miter
This value indicates that a sharp corner is to be used to join path segments. The corner is formed by extending the outer edges of the stroke at the tangents of the path segments until they intersect. If the stroke-miterlimit is exceeded, the line join falls back to bevel (see below).
miter-clip
This value is the same as miter but if the stroke-miterlimit is exceeded, the miter is clipped at a distance equal to half the stroke-miterlimit value multiplied by the stroke width from the intersection of the path segments (see below).
round
This value indicates that a round corner is to be used to join path segments. The corner is a circular sector centered on the join point.
bevel
This value indicates that a bevelled corner is to be used to join path segments. The bevel shape is a triangle that fills the area between the two stroked segments.
arcs
This value indicates that an arcs corner is to be used to join path segments. The arcs shape is formed by extending the outer edges of the stroke at the join point with arcs that have the same curvature as the outer edges at the join point.

The miter-clip and arcs values are new in SVG 2. The miter-clip value offers a more consistent presentation for a path with multiple joins as well as better behavior when a path is animated. The arcs value provides a better looking join when the path segments at the join are curved.

Adding 'arcs' line join was resolved at the Rigi Kaltbad group meeting.

Adding 'miter-clip' line join was resolved at the Sydney (2015) group meeting.

Image showing four paths, each with a different line join.

Four types of line joins.

Name: stroke-miterlimit
Value: <number>
Initial: 4
Applies to: shapes and text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

When two line segments meet at a sharp angle and a value of miter, miter-clip, or arcs has been specified for stroke-linejoin, it is possible for the join to extend far beyond the thickness of the line stroking the path. The stroke-miterlimit imposes a limit on the extent of the line join.

<number>
The limit on the extent of a miter, miter-clip, or arcs line join as a multiple of the stroke-width value. The value of stroke-miterlimit must be a <number> greater than or equal to 1. Any other value is an error (see Error processing).

For the miter or the miter-clip values, given the angle θ between the segments in local coordinate system, the miter length is calculated by:

miter length = ‘stroke-width’ sin θ 2
miter length = stroke-width / sin(theta / 2)

Historically, the miter length is defined as the distance from the inside stroke edge of the intersecting path segments to the tip of the miter. In practice, this is followed only for straight path segments. The above definition of miter length based on angles depends only on the tangents to the path segments at the join and thus gives consistent results independent of the curvature of the path segments. To be consistent with this definition, the clipping point of the miter-clip and arcs line joins is at a distance or arc length equal to half the stroke-miterlimit times the stroke width from the point the two path segments join.

Image showing the definition of the stroke miter length
	      and consistency of clipping between different shaped
	      path segments.

Left: Historical definition of miter length. Right: Two different paths with the same tangents to the path at the point where the path segments join. The behavior of the miter join (fallback to bevel or clipping position) is the same for both paths. It does not depend on the position where the inside stroked edges intersect.

If the miter length divided by the stroke width exceeds the stroke-miterlimit then for the value:

miter
the join is converted to a bevel;
miter-clip
the miter is clipped by a line perpendicular to the line bisecting the angle between the two path segments at a distance of half the value of miter length from the intersection of the two path segments.
Image showing resulting stroke when stroke miter limit is exceeded.

Effect on line join when stroke-miterlimit is exceeded. The olive-green dashed lines shows the position of the miter limit when the stroke-miterlimit value is 3. The gray regions shows what the joins would look like without a miter limit.

For the arcs value, the miter length is calculated along a circular arc that is tangent to the line bisecting the angle between the two segments at the point the two segments intersect and passes through the end point of the join. The line join is clipped, if necessary, by a line perpendicular to this arc at an arc length from the intersection point equal to half the value of the stroke-miterlimit value multiplied by the stroke width.

The effect of 'stroke-miterlimit' on an 'arcs' line join was resolved at Sydney (2015) group meeting.

See the definition of the line join shape below for a more precise description of the shape a line join will have.

12.5.6. Dashing strokes: the ‘stroke-dasharray’ and ‘stroke-dashoffset’ properties

Name: stroke-dasharray
Value: none | <dasharray>
Initial: none
Applies to: shapes and text content elements
Inherited: yes
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute lengths or percentages for <dasharray>, or keyword specified
Animatable: yes (non-additive)

where:

<dasharray> = [ <length> | <percentage> | <number> ]#*

The stroke-dasharray property controls the pattern of dashes and gaps used to form the shape of a path's stroke.

none
Indicates that no dashing is used.
<dasharray>

Specifies a dashing pattern to use. A <dasharray> is a list of comma and/or white space separated lengths or percentages. Each value specifies a length along the path for which the stroke is to be painted (a dash) and not painted (a gap). The first value and every second value in the list after it specifies the length of a dash, and every other value specifies the length of a gap between the dashes. If the list has an odd number of values, then it is repeated to yield an even number of values. (Thus, the rendering behavior of stroke-dasharray: 5,3,2 is equivalent to stroke-dasharray: 5,3,2,5,3,2.)

The resulting even-length dashing pattern is repeated along each subpath. The dashing pattern is reset and begins again at the start of each subpath.

If any value in the list is negative, the <dasharray> value is invalid. If all of the values in the list are zero, then the stroke is rendered as a solid line without any dashing.

Image showing a thick, dashed stroke.

A dashed stroke. The dashing pattern is 20,10. The red line shows the actual path that is stroked.

The pathLength attribute on a path element affects stroke-dasharray: each dash and gap length is interpreted relative to the author's path length as specified by pathLength.

Name: stroke-dashoffset
Value: <length> | <percentage>
Initial: 0
Applies to: shapes and text content elements
Inherited: yes
Percentages: refer to the size of the current SVG viewport (see Units)
Media: visual
Computed value: absolute length or percentage
Animatable: yes

The stroke-dashoffset property specifies the distance into the repeated dash pattern to start the stroke dashing at the beginning of the path. If the value is negative, then the effect is the same as dash offset d:

d = s - ‘stroke-dashoffset’ mod s
d = s - (abs(stroke-dashoffset) mod s)

where s is the sum of the dash array values.

Image showing a thick, dashed stroke with a non-zero dash offset.

A dashed stroke with a non-zero dash offset. The dashing pattern is 20,10 and the dash offset is 15. The red line shows the actual path that is stroked.

Like stroke-dasharray, stroke-dashoffset is interpreted relative to the author's path length as specified by the pathLength attribute on a path element.

The example below shows how a pathLength that is greatly different from the actual path length can be used to control stroke dashing more easily.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
     width="300" height="150">
  <defs>
    <path id="p" d="M -50,0 A 50,50 0 0 0 50,0 A 50,50 0 0 0 -50,0 z"
          pathLength="80"/>
    <g id="chip" stroke-width="10">
      <circle cy="5" r="55" fill="#000" fill-opacity="0.15" stroke="none"/>
      <use xlink:href="#p"/>
      <use xlink:href="#p" fill="none" stroke="#eee" stroke-width="10"
           stroke-dasharray="10 10" stroke-dashoffset="5"/>
      <g fill="none" stroke-width="5" stroke-dasharray="0 20" stroke-linecap="round">
        <use xlink:href="#p" stroke="#eee" stroke-dashoffset="10"/>
        <use xlink:href="#p" stroke-dashoffset="0"/>
      </g>
      <circle r="40" fill="#000" fill-opacity="0.15"
              stroke-width="2" stroke="white"/>
    </g>
  </defs>
  <rect width="100%" height="100%" fill="#063"/>
  <use xlink:href="#chip" x="140" y="75" fill="#00c" stroke="#00c"/>
  <use xlink:href="#chip" x="160" y="85" fill="#000" stroke="#000"/>
  <use xlink:href="#chip" x="170" y="65" fill="#c00" stroke="#c00"/>
</svg>
Image of three casino chips, each of which has a patterned border
              produced using stroke dashing.

The four broad white dashes and the eight small circular dashes around each chip are placed relative to an author specified pathLength of '80', which makes the desired stroke-dasharray and stroke-dashoffset values easy to compute.

See the definition of dash positions below for a more precise description of positions along a path that dashes will be placed.

12.5.7. Computing the shape of the stroke

SVG 2 Requirement: Specify stroke dashing more precisely.
Resolution: SVG 2 shall specify stroke dashing more precisely.
Purpose: To define dash starting point on basic shapes and path segments.
Owner: Cameron (no action)

The stroke shape of an element is the shape that is filled by the stroke property. Since text elements can be rendered in multiple chunks, each chunk has its own stroke shape. The following algorithm describes the ideal stroke shape of a path, basic shape or individual text chunk is, taking into account the stroking properties above. The ideal stroke shape described defines a best case implementation, but implementations are given some leeway to deviate from this description for performance reasons.

Authors should be aware that the shape of a stroke may in some cases, such as at extremely tight curves, differ across platforms.
Image showing how stroke shape differs across platforms. One
            example is as described by the algorithm in this specification, the
            other is different and overall looks less correct. It is distinct in
            that the geometry created to describe the left and right sides of
            the stroke are distorted due to the proximity of the end of the 
            curve to the section of high curvature.

An example of how the shape painted for stroke may differ across platforms.

The above example shows the possible rendered results for the following two SVG paths:
<svg viewBox="0 0 10 10" xmlns="http://www.w3.org/2000/svg">
<path d="M 1,3 C 8,2 8,6 7,6" stroke-width="4" fill="none" stroke="skyblue"/>
<path d="M 1,3 C 8,2 8,6 7,6" stroke-width="0.075" fill="none" stroke="black"/>
</svg>
The ideal stroke shape is determined as follows:
  1. Let shape be an empty shape.
  2. If stroke-width > 0, then:
    1. Let scale be a scale factor for the dash pattern. If we are computing the stroke shape of a basic shape or an individual text chunk, then scale is 1. Otherwise, it is determined as follows:
      1. Let length be the user agent's computed length of the path.
      2. Let authorlength be the value of the pathLength attribute on the path element.
      3. scale is authorlength / length.
    2. Let path be the equivalent path of the element (or the individual chunk of a text element).
    3. For each subpath of path:
      1. Let positions be the dash positions for the subpath.
      2. For each pair <start, end> in positions:
        1. Scale start and end by scale.
        2. Let dash be the shape that includes, for all distances between start and end along the subpath, all points that lie on the line perpendicular to the subpath at that distance and which are within distance stroke-width of the point on the subpath at that position.
        3. Set dash to be the union of dash and the starting cap shape for the subpath at position start.
        4. Set dash to be the union of dash and the ending cap shape for the subpath at position end.
        5. Let index and last be the indexes of the path segments in the subpath at distance start and end along the subpath.

          It does not matter whether any zero length segments are included when choosing index and last.

        6. While index < last:
          1. Set dash to be the union of dash and the line join shape for the subpath at segment index index.
          2. Set index to index + 1.
        7. Set shape to be the union of shape and stroke.
  3. Return shape.

The dash positions for a given subpath of the equivalent path of a path or basic shape is a sequence of pairs of values, which represent the starting and ending distance along the subpath for each of the dashes that form the subpath's stroke. It is determined as follows:

  1. Let pathlength be the length of the subpath.
  2. Let dashes be the list of values of stroke-dasharray on the element, converted to user units, repeated if necessary so that it has an even number of elements; if the property has the value none, then the list has a single value 0.
  3. Let count be the number of values in dashes.
  4. Let sum be the sum of the values in dashes.
  5. If sum = 0, then return a sequence with the single pair <0, pathlength>.
  6. Let positions be an empty sequence.
  7. Let offset be the value of the stroke-dashoffset property on the element.
  8. If offset is negative, then set offset to sum − abs(offset).
  9. Set offset to offset mod sum.
  10. Let index be the smallest integer such that sum(dashesi, 0 ≤ iindex) ≥ offset.
  11. Let dashlength be min(sum(dashesi, 0 ≤ iindex) − offset, pathlength).
  12. If index mod 2 = 0, then append to positions the pair <0, dashlength>.
  13. Let position be dashlength.
  14. While position < pathlength:
    1. Set index to (index + 1) mod count.
    2. Let dashlength be min(dashesindex, pathlengthposition).
    3. If index mod 2 = 0, then append to positions the pair <position, position + dashlength>.
    4. Set position to position + dashlength.
  15. Return positions.

The starting and ending cap shapes at a given position along a subpath are determined as follows:

  1. If stroke-linecap is butt, then return an empty shape.
  2. Otherwise, if stroke-linecap is round, then:
    1. If this is a starting cap, then return a semicircle of diameter stroke-width positioned such that:
      • The subpath that the semicircle is relative to is the subpath starting at distance position.
      • Its straight edge is parallel to the line perpendicular to the subpath at distance position along it.
      • The midpoint of its straight edge is at the point that is along the subpath at distance position.
      • The direction from the midpoint of its arc to the midpoint of its straight edge is the same as the direction of the subpath at distance position.
    2. Otherwise, this is an ending cap. Return a semicircle of diameter stroke-width positioned such that:
      • The subpath that the semicircle is relative to is the subpath ending at distance position.
      • Its straight edge is parallel to the line perpendicular to the subpath at distance position along it.
      • The midpoint of its straight edge is at the point that is along the subpath at distance position.
      • The direction from the midpoint of its straight edge to the midpoint of its arc is the same as the direction of the subpath.
  3. Otherwise, stroke-linecap is square:
    1. If this is a starting cap, then return a rectangle with side lengths stroke-width and stroke-width / 2 positioned such that:
      • Its longer edges, A and B, are parallel to the line perpendicular to the subpath at distance position along it.
      • The midpoint of A is at start.
      • The direction from the midpoint of B to the midpoint of A is the same as the direction of the subpath at distance position along it.
    2. Otherwise, this is an ending cap. Return a rectangle with side lengths stroke-width and stroke-width / 2 positioned such that:
      • Its longer edges, A and B, are parallel to the line perpendicular to the subpath at distance position along it.
      • The midpoint of A is at end.
      • The direction from the midpoint of A to the midpoint of B is the same as the direction of the subpath at distance position along it.
Image showing how to construct the three types of line caps

The three different stroke-linecap values used on paths with a single, non-zero length subpath. The white line is the path itself and the thick gray area is the stroke. On the top row, the green lines indicate the perpendicular to the tangent at the path endpoints and the pink areas are the caps. The bottom row shows the stroke without the perpendicular and cap highlighting.

The line join shape for a given segment of a subpath is determined as follows:

  1. Let P be the point at the end of the segment.
  2. If the unit tangent vector at the end of the segment and the unit tangent vector at the start of the following segment are equal, then return an empty shape.

    This means for example that 'M 100,100 h 100 h 100' would not produce a line join shape between the two straight line segment, but 'M 100,100 h 100 h -100' would.

  3. Let A be the line parallel to the tangent at the end of the segment.
  4. Let B be the line parallel to the tangent at the start of the following segment.
  5. Let Aleft and Aright be lines parallel to A at a distance of stroke-width / 2 to the left and to the right of A relative to the subpath direction, respectively.
  6. Let Bleft and Bright be lines parallel to B at a distance of stroke-width / 2 to the left and to the right of B, relative to the subpath direction, respectively.
  7. Let P1, P2 and P3 be points determined as follows:
    1. If the smaller angle between A and B is on the right of these lines, considering the direction of the subpath, then P1 and P2 are the points on Aleft and Bleft closest to P, and P3 is the intersection of Aleft and Bleft.
    2. Otherwise, P1 and P2 are the points on Aright and Bright closest to P, and P3 is the intersection of Aright and Bright.
  8. Let bevel be the triangle formed from the three points P, P1 and P2.
  9. If stroke-linejoin is round, then return the union of bevel and a circular sector of diameter stroke-width, centered on P, and which has P1 and P2 as the two endpoints of the arc.
  10. If stroke-linejoin is arcs, then find the circles that are tangent to the stroke edges at P1 and P2 with the same curvature as the edges at those points (see below). If both curvatures are zero fall through to miter-clip. If either curvature is greater than 2/(stroke width), fallback to round. Extend the stroke edges using these circles (or a line, in the case of zero curvature). If the two circles (or circle and line) do not intersect, adjust the radii of the two circles by an equal amount (or just the circle in case of a circle and line) until they do intersect (see below). The line join region is defined by the lines that connect P with P1 and P2 and the arcs defined by the circles (or arc and line) between the closest intersection point to P, and P1 and P2. Next calculate the miter limit as defined in the stroke-miterlimit section. Clip any part of the line join region that extends past the miter limit. Return the resulting region. Note that the curvatures are calculated in user-space before any transforms are applied.
  11. If stroke-linejoin is miter or miter-clip then the line join region is the union of bevel and the triangle formed from the three points P1, P2 and P3.
  12. Let θ be the angle between A and B. If 1 / sin(θ / 2) ≤ stroke-miterlimit, then return the line join region.
  13. If stroke-linejoin is miter-clip, then clip any part of the line join region that extends past the miter limit and return this region.
  14. Return bevel.
Image showing the lines and points computed to construct a round line join.

Construction of a round line join shape, shown in pink. The white line is the original path, which has two segments that come to a point, and the gray region is the stroke.

Image showing the lines and points computed to construct an arcs line join.

Construction of an arcs line join shape, shown in pink. The white line is the original path, which has two segments that come to a point, and the dark gray region is the stroke. The dashed lines show circles that are tangent to and have the curvature of the segments at the join. The olive-green circles (concentric with the dashed circles) define the join shape.

12.5.8. Computing the circles for the arcs 'stroke-linejoin'

The arcs stroke-linejoin requires finding circles that are both tangent to and have the same curvatures as the outer stroke edges at the ends of path segments. To find one of these circles, first calculate the curvature κ of the path segment at its end (see below). Next, find the radius of a circle corresponding to this curvature: r = 1/κ. Increase or decrease the radius by one half of the stroke width to account for the stroke: rc = r ± ½ stroke-width. The center of the circle will be on a line normal to the path end a distance of rc away from the outer stroke edge at the end.

For a line: the curvature is zero. Extend the outer stroke edge by a line.

For an elliptical arc:

κ ( t ) = r x r y ( r x 2 sin 2 t + r y 2 cos 2 t ) 3 / 2
$$\kappa(t) = {{r_x r_y}\over{(r_x^2 \sin^2 t + r_y^2 \cos^2 t)^{3/2}}}$$

where:

t = arctan ( r y r x tan θ )
$$t = \arctan ( {r_y \over r_x} \tan \theta )$$

The parameter θ at the beginning or end of an arc segment can be found by using the formulas in the Elliptical arc implementation notes. (Note, some renderers convert elliptical arcs to cubic Béziers prior to rendering so the equations here may not be needed.)

For a quadratic Bézier:

κ ( 0 ) = 1 2 ( P 1 P 0 ) × ( P 2 P 1 ) | P 1 P 0 | 3
$$\kappa(0) = {2\over3}{(P_1-P_0)\times((P_0-P_1)+(P_2-P_1))\over|P_1-P_0|^3}$$
κ ( 1 ) = 1 2 ( P 2 P 1 ) × ( P 0 P 1 ) | P 2 P 1 | 3
$$\kappa(0) = {2\over3}{(P_1-P_0)\times((P_0-P_1)+(P_2-P_1))\over|P_1-P_0|^3}$$

Where κ(0) and κ(1) are the signed curvatures at the start and end of the path segment respectively, and the P's are the three points that define the quadratic Bézier.

For a cubic Bézier:

κ ( 0 ) = 2 3 ( P 1 P 0 ) × ( P 2 P 1 ) | P 1 P 0 | 3
$$\kappa(0) = {2\over3}{(P_1-P_0)\times((P_0-P_1)+(P_2-P_1))\over|P_1-P_0|^3}$$
κ ( 1 ) = 2 3 ( P 3 P 2 ) × ( P 1 P 2 ) | P 3 P 2 | 3
$$\kappa(1) = {2\over3}{(P_3-P_2)\times((P_1-P_2)+(P_3-P_2))\over|P_3-P_2|^3}$$

Where κ(0) and κ(1) are the signed curvatures at the start and end of the path segment respectively, and the P's are the four points that define the cubic Bézier. Note, if P0 and P1, or P2 and P3 are degenerate, the curvature will be infinite and a line should be used in constructing the join.

12.5.9. Adjusting the circles for the arcs 'stroke-linejoin' when the initial circles do not intersect

The fallback behavior was resolved at the Sydney 2016 F2F. It gives a smooth transition between the fallback and non-fallback states.

When the initial circles calculated for the arcs stroke-linejoin do not intersect, they need to be adjusted by changing both radii by the same magnitude (moving the circle centers to keep the circles tangent to the offset paths) until the circles just touch. There are two cases to consider. The first is when one circle encloses the other circle. In this case the larger circle is reduced in size while the smaller circle is increased in size:

Image showing the lines and points computed to construct an arcs line join
	      when the original offset circles do not intersect.

Construction of an arcs line join shape, shown in pink. The white line is the original path and the dark gray region is the stroke. The dashed lines show circles that are tangent to and have the curvature of the segments at the join. Note the circles do not intersect. Two new circles are constructed by adjusting the radii of the original circles by the same magnitude with the larger circle being made smaller and the smaller circle being made larger until the new circles just touch as shown by the olive-green circles. These new circles then define the join shape.

The second case is when there is no overlap between the circles. In this case the radii of both circles are increased by the same amount:

Image showing the lines and points computed to construct an arcs line join
	      when the original offset circles do not intersect.

Construction of an arcs line join shape, shown in pink. The white line is the original path and the dark gray region is the stroke. The dashed lines show circles that are tangent to and have the curvature of the segments at the join. Note they do not intersect. Two new circles are constructed by increasing the radii of the original circles by the same amount until the new circles just touch as shown by the olive-green circles. These new circles then define the join shape.

If in this latter case, the tangents of the offset paths at the line join are parallel, the circles cannot be adjusted so that they touch. The line join should then be constructed as a rectangle whose width is the stroke width and whose length is the stroke width times one half of the value of the stroke-miterlimit:

Image showing the lines and points computed to construct an arcs line join
	      when the original offset circles do not intersect.

Construction of an arcs line join shape, shown in pink. The white line is the original path, which has two segments that come to a point, and the dark gray region is the stroke. The dashed lines show circles that are tangent to and have the curvature of the segments at the join. Note they do not intersect. Even if the radii of the circles is increased to infinity, the circles will not intersect. The line join is then a rectangle with the length determined by the miter limit (shown as a vertical dashed line).

There are a couple of ways to implement the fallback algorithm. The first way is by recursive trial and error on the magnitude of the radius change. The second is by an exact calculation utilizing the touching circle condition and the constraints that the centers of the circles must remain on lines normal to the path segments at the join. This leads to a quadratic equation where one solution is the required radius change.

12.6. Vector effects

This chapter explains vector-effect related to Painting. Please refer to this for the perspective of vector-effect.

non-scaling-stroke
Modifies the way an object is stroked. Normally stroking involves calculating stroke outline of the shape's path in current local coordinate system and filling that outline with the stroke paint (color or gradient). With the non-scaling-stroke vector effect, stroke outline shall be calculated in the "host" coordinate space instead of local coordinate system. More precisely: a user agent establishes a host coordinate space which in SVG Tiny 1.2 is always the same as "screen coordinate space". The stroke outline is calculated in the following manner: first, the shape's path is transformed into the host coordinate space. Stroke outline is calculated in the host coordinate space. The resulting outline is transformed back to the local coordinate system. (Stroke outline is always filled with stroke paint in the current local coordinate system). The resulting visual effect of this modification is that stroke width is not dependant on the transformations of the element (including non-uniform scaling and shear transformations) and zoom level.

12.7. Markers

SVG 2 Requirement: Improve markers.
Resolution: We will improve markers for SVG 2.
Purpose: To solve the common problems authors have with SVG markers.
Owner: Cameron (ACTION-3286)

A marker is a graphical object that is painted at particular positions along any shape element. These elements are known as the markable elements.

The marker-start and marker-end properties can be used to place markers at the first and last vertex of a markable element, and the marker-mid property can be used to place markers at all other vertices (aside from the first and last). The marker-start and marker-end can be used for example to add arrowheads to paths. Markers placed using these properties are known as vertex markers.

In SVG 2, vertex markers are the only kind of markers available. Other specifications will add new types of markers.

The graphics for a marker are defined by a marker element. The marker-start, marker-end and marker-mid properties, together known as the marker properties, reference marker elements.

Markers can be animated, and as with use elements, the animated effects will show on all current uses of the markers within the document.

Markers on a given element are painted in the following order, from bottom to top:

12.7.1. The ‘marker’ element

marker
Categories:
Container element, never-rendered element
Content model:
Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
Attributes:
DOM Interfaces:

The marker element defines the graphics that are to be used for drawing markers on a markable element.

Attribute definitions:

Name Value Initial value Animatable
markerUnits strokeWidth | userSpaceOnUse strokeWidth yes

The markerUnits attribute defines the coordinate system for attributes markerWidth, markerHeight and the contents of the marker. Values have the following meanings:

strokeWidth
markerWidth, markerHeight and the contents of the marker have values in a coordinate system which has a single unit equal to the size in user units of the current stroke width (see the stroke-width property) of the element referencing the marker.
userSpaceOnUse
markerWidth, markerHeight and the contents of the marker have values in the current user coordinate system in place for the element referencing the marker.
Name Value Initial value Animatable
markerWidth, markerHeight <length> | <percentage> | <number> 3 yes

The markerWidth and markerHeight attributes represent the size of the SVG viewport into which the marker is to be fitted according to the viewBox and preserveAspectRatio attributes. A value of zero for either attribute results in nothing being rendered for the marker. A negative value for either attribute is an error (see Error processing).

Name Value Initial value Animatable
refX <length> | <percentage> | <number> | left | center | right 0 yes
refY <length> | <percentage> | <number> | top | center | bottom 0 yes

New in SVG 2: geometric keywords (matches use in symbol).

We will add top/center/bottom, left/center/right keywords to refX/refY on marker/symbol. Resolved at London F2F. Values inspired by 'background-position'.

The refX and refY attributes define the reference point of the marker, which is to be placed exactly at the marker's position on the markable element. Lengths and numbers must be interpreted as being in the coordinate system of the marker contents, after application of the viewBox and preserveAspectRatio attributes. Percentage values must be interpreted as being a percentage of the viewBox width for refX or a percentage of the viewBox height for refY.

The keyword values must evaluate to the following percentages:

Mapping of refX and refY keywords to percentages.
keywordpercentage equivalent
left0%
center50%
right100%
top0%
bottom100%
Name Value Initial value Animatable
orient auto | auto-start-reverse | <angle> | <number> 0 yes (non-additive)

The orient attribute indicates how the marker is rotated when it is placed at its position on the markable element. Values have the following meanings:

'auto'

The marker is oriented such that its positive x-axis is pointing in a direction relative to the path at the position the marker is placed (See Rendering Markers).

'auto-start-reverse'

If placed by marker-start, the marker is oriented 180° different from the orientation that would be used if 'auto' where specified. For all other markers, 'auto-start-reverse' means the same as 'auto'.

This allows a single arrowhead marker to be defined that can be used for both the start and end of a path, i.e. which points outwards from both ends.

<angle>
<number>

The marker is oriented such that the specified angle is that measured between the markable element's positive x-axis and the marker's positive x-axis. A <number> value specifies an angle in degrees.

For example, if a value of '45' is given, then the marker's positive x-axis would be pointing down and right in the markable element's coordinate system.

12.7.2. Vertex markers: the ‘marker-start’, ‘marker-mid’ and ‘marker-end’ properties

Name: marker-start, marker-mid, marker-end
Value: none | <marker-ref>
Initial: none
Applies to: markable elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified, but with <url> values (that are part of a <marker-ref>) made absolute
Animatable: yes

where:

<marker-ref> = <url>

The marker-start and marker-end properties are used to specify the marker that will be drawn at the first and last vertices of the given markable element, respectively. marker-mid is used to specify the marker that will be drawn at all other vertices (i.e., every vertex except the first and last). Possible values for marker-start, marker-mid and marker-end are:

none
Indicates that no marker symbol will be drawn at the given vertex or vertices.
<marker-ref>
Indicates that the marker element referenced by the <marker-ref> value will be drawn at the given vertex or vertices. If the reference is not valid, then no marker will be drawn at the given vertex or vertices.

For all markable elements, the path that must be used when calculating marker positions is the equivalent path.

For all shape elements, except polyline and path, the last vertex is the same as the first vertex. In this case, if the value of marker-start and marker-end are both not none, then two markers will be rendered on that final vertex. For path elements, for each closed subpath, the last vertex is the same as the first vertex. marker-start must only be rendered on the first vertex of the path data. marker-end must only be rendered on the final vertex of the path data. marker-mid must be rendered on every vertex other than the first vertex of the path data and the last vertex of the path data.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 30">
  <defs>
    <marker id="m1" viewBox="0 0 10 10" refX="5" refY="5"
     markerWidth="8" markerHeight="8">
      <circle cx="5" cy="5" r="5" fill="green"/>
    </marker>
    <marker id="m2" viewBox="0 0 10 10" refX="5" refY="5"
     markerWidth="6.5" markerHeight="6.5">
      <circle cx="5" cy="5" r="5" fill="skyblue" opacity="0.9"/>
    </marker>
    <marker id="m3" viewBox="0 0 10 10" refX="5" refY="5"
     markerWidth="5" markerHeight="5">
      <circle cx="5" cy="5" r="5" fill="maroon" opacity="0.85"/>
    </marker>    
  </defs>
  
  <path d="M10,10 h10 v10 z m20,0 h10 v10 z m20,0 h10 v10 z"
  fill="none" stroke="black"
  marker-start="url(#m1)"  
  marker-mid="url(#m2)"
  marker-end="url(#m3)"  
  />
</svg>
Image showing that for closed subpaths, two markers are painted at the start of each subpath.

For path data containing closed subpaths, two markers are drawn at the first/last vertex of each closed subpath. For the leftmost closed subpath, a marker-mid is drawn over the marker-start. For the middle closed subpath, two marker-mid are drawn on top of one another. For the rightmost closed subpath, marker-end is drawn over marker-mid.

Note that marker-start and marker-end refer to the first and last vertex of the entire path, not each subpath.

The following example shows a triangular marker symbol used as a vertex marker to form an arrowhead at the end of two paths.

<svg xmlns="http://www.w3.org/2000/svg"
     width="275" height="200" viewBox="0 0 275 200">
  <defs>
    <marker id="Triangle" viewBox="0 0 10 10" refX="1" refY="5" 
            markerUnits="strokeWidth" markerWidth="4" markerHeight="3"
            orient="auto">
      <path d="M 0 0 L 10 5 L 0 10 z" fill="context-stroke"/>
    </marker>
  </defs>

  <g fill="none" stroke-width="10" marker-end="url(#Triangle)">
    <path stroke="crimson" d="M 100,75 C 125,50 150,50 175,75"/>
    <path stroke="olivedrab" d="M 175,125 C 150,150 125,150 100,125"/>
  </g>
</svg>
Image showing the use of an automatically oriented marker.

The triangle is placed at the end of the path and oriented automatically so that it points in the right direction. The use of context-stroke ensures the fill of the triangle matches the stroke of each path.

12.7.3. Marker shorthand: the ‘marker’ property

Name: marker
Value: none | <marker-ref>
Initial: not defined for shorthand properties
Applies to: markable elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: see individual properties
Animatable: yes

The marker property sets values for the marker-start, marker-mid and marker-end properties. The value of the marker is used directly for all three of the corresponding longhand properties.

12.7.4. Rendering markers

When orienting a marker automatically, due to specifying orient as 'auto', the following rules are used:

For each marker that is drawn, a temporary new user coordinate system is established so that the marker will be positioned and sized correctly, as follows:

Note that the user agent style sheet sets the overflow property for marker elements to hidden, which causes a rectangular clipping path to be created at the bounds of marker's SVG viewport by default.

Properties do not inherit from the element referencing the marker into the contents of the marker. However, by using the context-stroke value for the fill or stroke on elements in its definition, a single marker can be designed to match the style of the element referencing the marker.

Markers cannot be interacted with. Events such as click or mouseover, for example, are not dispatched to a marker or its children when the mouse is clicked or moved over a rendered marker.

Markers are not rendered directly and must be referenced by one of the marker properties to be rendered. The display value for the marker element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute. marker elements are available for referencing even when the display property on the marker element or any of its ancestors is set to none.

The rendering effect of a marker is as if the contents of the referenced marker element were deeply cloned into a separate non-exposed DOM tree for each instance of the marker. Because the cloned DOM tree is non-exposed, the SVG DOM does not show the cloned instance of the marker.

The conceptual deep cloning of the referenced marker element into a non-exposed DOM tree also copies any property values resulting from the CSS cascade ([CSS21], chapter 6) and property inheritance on the referenced element and its contents. CSS selectors can be applied to the original (i.e., referenced) elements because they are part of the formal document structure. CSS selectors cannot be applied to the (conceptually) cloned DOM tree because its contents are not part of the formal document structure.

For illustrative purposes, we'll repeat the marker example shown earlier:

<?xml version="1.0" standalone="no"?>
<svg width="4in" height="2in"
     viewBox="0 0 4000 2000"
     xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="Triangle"
      viewBox="0 0 10 10" refX="0" refY="5"
      markerUnits="strokeWidth"
      markerWidth="4" markerHeight="3"
      orient="auto">
      <path d="M 0 0 L 10 5 L 0 10 z" />
    </marker>
  </defs>
  <rect x="10" y="10" width="3980" height="1980"
       fill="none" stroke="blue" stroke-width="10" />
  <desc>Placing an arrowhead at the end of a path.
  </desc>
  <path d="M 1000 750 L 2000 750 L 2500 1250"
        fill="none" stroke="black" stroke-width="100"
        marker-end="url(#Triangle)"  />
</svg>

The rendering effect of the above file will be visually identical to the following:

<?xml version="1.0" standalone="no"?>
<svg width="4in" height="2in"
     viewBox="0 0 4000 2000"
     xmlns="http://www.w3.org/2000/svg">
  <desc>File which produces the same effect
      as the marker example file, but without
      using markers.
  </desc>
  <rect x="10" y="10" width="3980" height="1980"
       fill="none" stroke="blue" stroke-width="10" />
  <!-- The path draws as before, but without the marker properties -->
  <path d="M 1000 750 L 2000 750 L 2500 1250"
        fill="none" stroke="black" stroke-width="100"  />
  <!-- The following logic simulates drawing a marker
       at final vertex of the path. -->
  <!-- First off, move the origin of the user coordinate system
       so that the origin is now aligned with the end point of the path. -->
  <g transform="translate(2500,1250)" >
    <!-- Rotate the coordinate system 45 degrees because
         the marker specified orient="auto" and the final segment
         of the path is going in the direction of 45 degrees. -->
    <g transform="rotate(45)" >
      <!-- Scale the coordinate system to match the coordinate system
           indicated by the 'markerUnits' attributes, which in this case has
           a value of 'strokeWidth'. Therefore, scale the coordinate system
           by the current value of the 'stroke-width' property, which is 100. -->
      <g transform="scale(100)" >
        <!-- Translate the coordinate system by
             (-refX*viewBoxToMarkerUnitsScaleX, -refY*viewBoxToMarkerUnitsScaleY)
             in order that (refX,refY) within the marker will align with the vertex.
             In this case, we use the default value for preserveAspectRatio
             ('xMidYMid meet'), which means find a uniform scale factor
             (i.e., viewBoxToMarkerUnitsScaleX=viewBoxToMarkerUnitsScaleY)
             such that the viewBox fits entirely within the SVG viewport ('meet') and
             is center-aligned ('xMidYMid'). In this case, the uniform scale factor
             is markerHeight/viewBoxHeight=3/10=.3. Therefore, translate by
             (-refX*.3,-refY*.3)=(0*.3,-5*.3)=(0,-1.5). -->
        <g transform="translate(0,-1.5)" >
          <!-- There is an implicit clipping path because the user agent style
               sheet says that the 'overflow' property for markers has the value
               'hidden'. To achieve this, create a clipping path at the bounds
               of the SVG viewport. Note that in this case the SVG viewport extends
               0.5 units to the left and right of the viewBox due to
               a uniform scale factor, different ratios for markerWidth/viewBoxWidth
               and markerHeight/viewBoxHeight, and 'xMidYMid' alignment -->
          <clipPath id="cp1" >
            <rect x="-0.5" y="0" width="4" height="3" />
          </clipPath>
          <g clip-path="url(#cp1)" >
            <!-- Scale the coordinate system by the uniform scale factor
                 markerHeight/viewBoxHeight=3/10=.3 to set the coordinate
                 system to viewBox units. -->
            <g transform="scale(.3)" >
              <!-- This 'g' element carries all property values that result from
                   cascading and inheritance of properties on the original 'marker' element.
                   In this example, neither fill nor stroke was specified on the 'marker'
                   element or any ancestors of the 'marker', so the initial values of
                   "black" and "none" are used, respectively. -->
             <g fill="black" stroke="none" >
                <!-- Expand out the contents of the 'marker' element. -->
                <path d="M 0 0 L 10 5 L 0 10 z" />
              </g>
            </g>
          </g>
        </g>
      </g>
    </g>
  </g>
</svg>

View this example as SVG (SVG-enabled browsers only)

12.8. Controlling paint operation order: the ‘paint-order’ property

SVG 2 Requirement: Support control of the order of filling, stroke and painting markers on shapes.
Resolution: SVG 2 will adopt the ‘paint-order’ property proposal, though possibly with a different name. The property name is now resolved, see 15 Nov 2013 minutes.
Purpose: To address the common desire to paint strokes below fills without having to duplicate an element.
Owner: Cameron (ACTION-3285)
Name: paint-order
Value: normal | [ fill || stroke || markers ]
Initial: normal
Applies to: graphics elements and text content elements
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

New in SVG 2. Added primarily to allow painting the stroke of text below its fill without needing to duplicate the text element.

The paint-order property controls the order that the three paint operations that shapes and text are rendered with: their fill, their stroke and any markers they might have.

When the value of this property is normal, the element is painted with the standard order of painting operations: the fill is painted first, then its stroke and finally its markers.

When any of the other keywords are used, the order of the paint operations for painting the element is as given, from left to right. If any of the three keywords are omitted, they are painted last, in the order they would be painted with paint-order: normal.

This mean that, for example, paint-order: stroke has the same rendering behavior as paint-order: stroke fill markers.

The following example shows how the paint-order property can be used to render stroked text in a more aesthetically pleasing manner.

<svg xmlns="http://www.w3.org/2000/svg"
     width="600" height="150" viewBox="0 0 600 150">

  <style>
    text {
      font: 80px bold sans-serif; stroke-linejoin: round;
      text-anchor: middle; fill: peachpuff; stroke: crimson;
    }
  </style>

  <text x="150" y="100" style="stroke-width: 6px;">pizazz</text>
  <text x="450" y="100" style="stroke-width: 12px; paint-order: stroke;">pizazz</text>
</svg>
Image showing the effect of paint-order.

Text painted with its stroke below the fill.

12.9. Color space for interpolation: the ‘color-interpolation’ property

Name: color-interpolation
Value: auto | sRGB | linearRGB
Initial: sRGB
Applies to: container elements, graphics elements, gradient elements and animate
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

The SVG user agent performs color interpolations and compositing at various points as it processes SVG content. The color-interpolation property controls which color space is used for the following graphics operations:

For filter effects, the color-interpolation-filters property controls which color space is used. [FILTERS]

The color-interpolation property chooses between color operations occurring in the sRGB color space or in a (light energy linear) linearized RGB color space. Having chosen the appropriate color space, component-wise linear interpolation is used. Values for color-interpolation have the following meanings:

auto
Indicates that the user agent can choose either the sRGB or linearRGB spaces for color interpolation. This option indicates that the author doesn't require that color interpolation occur in a particular color space.
sRGB
Indicates that color interpolation occurs in the sRGB color space.
linearRGB
Indicates that color interpolation occurs in the linearized RGB color space as described below.

The conversion formulas between the sRGB color space (i.e., nonlinear with 2.2 gamma curve) and the linearized RGB color space (i.e., color values expressed as sRGB tristimulus values without a gamma curve) can be found in the sRGB specification [SRGB]. For illustrative purposes, the following formula shows the conversion from sRGB to linearized RGB, where Csrgb is one of the three sRGB color components, Clinear is the corresponding linearized RGB color component, and all color values are between 0 and 1:

C linear = { C srgb 12.92 if  C srgb 0.04045 C srgb + 0.055 1.055 2.4 if  C srgb > 0.04045
if C_srgb <= 0.04045
  C_linear = C_srgb / 12.92
else if c_srgb > 0.04045
  C_linear = ((C_srgb + 0.055) / 1.055) ^ 2.4

Out-of-range color values, if supported by the user agent, also are converted using the above formulas. (See Clamping values which are restricted to a particular range.)

When a child element is blended into a background, the value of the color-interpolation property on the child determines the type of blending, not the value of the color-interpolation on the parent. For gradients which make use of the ‘href’ attribute to reference another gradient, the gradient uses the color-interpolation property value from the gradient element which is directly referenced by the fill or stroke property. When animating colors, color interpolation is performed according to the value of the color-interpolation property on the element being animated.

12.10. Rendering hints

12.10.1. The ‘color-rendering’ property

Name: color-rendering
Value: auto | optimizeSpeed | optimizeQuality
Initial: auto
Applies to: container elements, graphics elements, gradient elements and animate
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

The color-rendering property provides a hint to the SVG user agent about how to optimize its color interpolation and compositing operations. Values have the following meanings:

auto
Indicates that the user agent shall make appropriate tradeoffs to balance speed and quality, but quality shall be given more importance than speed.
optimizeSpeed
Indicates that the user agent shall emphasize rendering speed over quality. For RGB display devices, this option will sometimes cause the user agent to perform color interpolation and compositing in the device RGB color space.
optimizeQuality
Indicates that the user agent shall emphasize quality over rendering speed.

color-rendering takes precedence over color-interpolation-filters. For example, assume color-rendering: optimizeSpeed and color-interpolation-filters: linearRGB. In this case, the SVG user agent should perform color operations in a way that optimizes performance, which might mean sacrificing the color interpolation precision as specified by color-interpolation-filters: linearRGB.

12.10.2. The ‘shape-rendering’ property

Name: shape-rendering
Value: auto | optimizeSpeed | crispEdges | geometricPrecision
Initial: auto
Applies to: shapes
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

The shape-rendering property provides a hint to the implementation about what tradeoffs to make as it renders vector graphics elements such as path elements and basic shapes such as circles and rectangles. Values have the following meanings:

auto
Indicates that the user agent shall make appropriate tradeoffs to balance speed, crisp edges and geometric precision, but with geometric precision given more importance than speed and crisp edges.
optimizeSpeed
Indicates that the user agent shall emphasize rendering speed over geometric precision and crisp edges. This option will sometimes cause the user agent to turn off shape anti-aliasing.
crispEdges
Indicates that the user agent shall attempt to emphasize the contrast between clean edges of artwork over rendering speed and geometric precision. To achieve crisp edges, the user agent might turn off anti-aliasing for all lines and curves or possibly just for straight lines which are close to vertical or horizontal. Also, the user agent might adjust line positions and line widths to align edges with device pixels.
geometricPrecision
Indicates that the user agent shall emphasize geometric precision over speed and crisp edges.

12.10.3. The ‘text-rendering’ property

Name: text-rendering
Value: auto | optimizeSpeed | optimizeLegibility | geometricPrecision
Initial: auto
Applies to: text
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

The text-rendering property provides a hint to the implementation about what tradeoffs to make as it renders text. Values have the following meanings:

auto
Indicates that the user agent shall make appropriate tradeoffs to balance speed, legibility and geometric precision, but with legibility given more importance than speed and geometric precision.
optimizeSpeed
Indicates that the user agent shall emphasize rendering speed over legibility and geometric precision. This option will sometimes cause the user agent to turn off text anti-aliasing.
optimizeLegibility
Indicates that the user agent shall emphasize legibility over rendering speed and geometric precision. The user agent will often choose whether to apply anti-aliasing techniques, built-in font hinting or both to produce the most legible text.
geometricPrecision
Indicates that the user agent shall emphasize geometric precision over legibility and rendering speed. This option will usually cause the user agent to suspend the use of hinting so that glyph outlines are drawn with comparable geometric precision to the rendering of path data.

12.10.4. The ‘image-rendering’ property

Name: image-rendering
Value: auto | optimizeQuality | optimizeSpeed
Initial: auto
Applies to: shapes
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: yes

The CSS Image Values and Replacement Conent Module Level 4 may in the future redefine this property. In particular it should allow the choice between smoothing and keeping a pixelated look when upscaling.

The image-rendering property provides a hint to the implementation about how to make speed vs. quality tradeoffs as it performs image processing. Values have the following meanings:

auto
Indicates that the user agent shall make appropriate tradeoffs to balance speed and quality, but quality shall be given more importance than speed. The user agent shall employ a resampling algorithm at least as good as nearest neighbor resampling, but bilinear resampling is strongly preferred. For Conforming High-Quality SVG Viewers, the user agent shall employ a resampling algorithm at least as good as bilinear resampling.
optimizeQuality
Indicates that the user agent shall emphasize quality over rendering speed. The user agent shall employ a resampling algorithm at least as good as bilinear resampling.
optimizeSpeed
Indicates that the user agent shall emphasize rendering speed over quality. The user agent should use a resampling algorithm which achieves the goal of fast rendering, with the requirement that the resampling algorithm shall be at least as good as nearest neighbor resampling. If performance goals can be achieved with higher quality algorithms, then the user agent should use the higher quality algorithms instead of nearest neighbor resampling.

In all cases, resampling must be done in a truecolor (e.g., 24-bit) color space even if the original data and/or the target device is indexed color. High quality SVG viewers should perform image resampling using a linear color space.

12.11. The effect of the ‘will-change’ property

See the CSS Will Change Module Level 1 specification for the definition of will-change.

The will-change property is used to provide a hint to the user agent as to the types of changes that will be made to content, giving the user agent a better chance at performing rendering optimizations for a given element.

The will-change property applies to all SVG graphics elements, however since SVG elements do not support scrolling, the scroll-position value will have no effect on them.

The following example demonstrates how will-change can be used to forewarn the user agent that an element will have its transform property changed, with the potential result of the user agent rendering the element into its own GPU layer so that the scripted transform changes appear smooth.

<svg xmlns="http://www.w3.org/2000/svg">
  <style>
    #background { fill: lemonchiffon; }
    #star {
      fill: cornflowerblue;
      stroke: navy; stroke-width: 5px; stroke-linejoin: round;
      paint-order: stroke fill;
      will-change: transform;
    }
    text { font: 24px sans-serif; user-select: none; }
  </style>
  <g onmousemove="drag(evt.clientX, evt.clientY);"
     onmouseup="dragging = false;">
    <rect id="background" width="100%" height="100%"/>
    <text x="10" y="30">Drag the star!</text>
    <path id="star" transform="translate(200,150)"
          d="M 0.00,-40.00 -11.76,-16.18 -38.04,-12.36 -19.02,6.18 -23.51,32.36
               0.00,20.00 23.51,32.36 19.02,6.18 38.04,-12.36 11.76,-16.18 z"
          onmousedown="dragging = true;"/>
  </g>
  <script>
    var dragging = false;
    var star = document.getElementById("star");
    function drag(x, y) {
      if (dragging) {
        star.setAttribute("transform", "translate(" + x + "," + y + ")");
      }
    }
  </script>
</svg>
A blue star with the text "Drag the star!" above.

In a user agent that supports will-change on SVG elements, the star might be rendered into a layer so that it can be composited quickly when it is dragged around the canvas. View interactive SVG document.

The will-change property replaces the ‘buffered-rendering’ property defined in SVG Tiny 1.2.

12.12. DOM interfaces

12.12.1. Interface SVGMarkerElement

An SVGMarkerElement object represents a marker element in the DOM.

interface SVGMarkerElement : SVGElement {

  // Marker Unit Types
  const unsigned short SVG_MARKERUNITS_UNKNOWN = 0;
  const unsigned short SVG_MARKERUNITS_USERSPACEONUSE = 1;
  const unsigned short SVG_MARKERUNITS_STROKEWIDTH = 2;

  // Marker Orientation Types
  const unsigned short SVG_MARKER_ORIENT_UNKNOWN = 0;
  const unsigned short SVG_MARKER_ORIENT_AUTO = 1;
  const unsigned short SVG_MARKER_ORIENT_ANGLE = 2;

  [SameObject] readonly attribute SVGAnimatedLength refX;
  [SameObject] readonly attribute SVGAnimatedLength refY;
  [SameObject] readonly attribute SVGAnimatedEnumeration markerUnits;
  [SameObject] readonly attribute SVGAnimatedLength markerWidth;
  [SameObject] readonly attribute SVGAnimatedLength markerHeight;
  [SameObject] readonly attribute SVGAnimatedEnumeration orientType;
  [SameObject] readonly attribute SVGAnimatedAngle orientAngle;
  attribute DOMString orient;

  void setOrientToAuto();
  void setOrientToAngle(SVGAngle angle);
};

SVGMarkerElement implements SVGFitToViewBox;

The numeric marker unit type constants defined on SVGMarkerElement are used to represent the keyword values that the markerUnits attribute can take. Their meanings are as follows:

ConstantMeaning
SVG_MARKERUNITS_USERSPACEONUSEThe userSpaceOnUse keyword.
SVG_MARKERUNITS_STROKEWIDTHThe strokeWidth keyword.
SVG_MARKERUNITS_UNKNOWNSome other value.

The numeric marker orientation type constants defined on SVGMarkerElement are used to represent the types of values that the orient attribute can take. Their meanings are as follows:

ConstantMeaning
SVG_MARKER_ORIENT_AUTOThe auto keyword.
SVG_MARKER_ORIENT_ANGLEAn <angle> or <number> value indicating the orientation angle.
SVG_MARKER_ORIENT_UNKNOWNSome other value.

The markerUnits IDL attribute reflects the markerUnits content attribute. The numeric type values for markerUnits are as described above in the numeric marker unit type constant table.

The orientType, orientAngle and orient IDL attributes all reflect the orient content attribute. The numeric type values for orient are as follows:

ValueNumeric type value
auto SVG_MARKER_ORIENT_AUTO
auto-start-reverse SVG_MARKER_ORIENT_UNKNOWN
<angle> | <number> SVG_MARKER_ORIENT_ANGLE

The refX, refY, markerWidth and markerHeight IDL attributes reflect the refX, refY, markerWidth and markerHeight content attributes, respectively.

The setOrientToAuto method is used to set the value of the orient attribute to 'auto'. When setOrientToAuto() is called, the orient attribute is simply set to 'auto'.

The setOrientToAngle method is used to set the value of the orient attribute to a specific angle value. When setOrientToAngle(angle) is called, the orient attribute is reserialized using angle as the value.

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

Chapter 13: Paint Servers: Solid Colors, Gradients, Patterns and Hatches

13.1. Introduction

This section covers Paint Servers, a method which allows the fill or stroke of an object to be defined by a resource found elsewhere. It allows resources to be reused throughout a document. See the section Painting: Filling and Stroking for a general discussion of filling and stroking objects.

SVG defines several types of paint servers:

SVG 2 Requirement: Arbitrary fills for shapes.
Resolution: SVG 2 shall support filling and stroking from arbitrary elements.
Purpose: To allow for example videos or images to be used as a fill source.
Owner: Alex? (no action)
Image of three types of paint servers.

Three types of paint servers. From left to right: A solid color ("MyLightPurple"). A linear gradient. A pattern.

Paint servers are used by including a URL reference in a fill or stroke property (i.e. fill="url(#MyLightPurple)").

properties inherit into a paint-server element from its ancestors; properties do not inherit from the element referencing the paint server element.

Paint-server elements are never rendered directly; their only usage is as something that can be referenced using the fill and stroke properties. The display value for these elements must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute. Paint-server elements are available for referencing even when the display property on the paint-server element or any of its ancestors is set to none.

13.1.1. Using paint servers as templates

Most paint server elements accept an href attribute, which can be used to define a compatible paint server element as a template. Attributes defined for the template element can replace the initial value if corresponding attributes are not specified on the current element. Furthermore, if the current element does not have any child content other than descriptive elements, than the child content of the template element is cloned to replace it.

The exclusion of descriptive content is new in SVG 2, consistent with changes to allow descriptive content for any SVG element. Also new: template cross-references may be to external file resources (different chapters in SVG 1.1 had inconsistent guidance on this point), and the "inheritance" of child elements is represented through a shadow tree.

Templating can be indirect to an arbitrary level (subject to security limits on external file resources, which can make a reference invalid). Thus, if the referenced template element defines its attribute values or clones its shadow content from another element referenced by its own href attribute, then that value or content can be used for the current element.

The description of each href attribute defines the limits of the templating process, as follows:

If any of the specified attributes are not defined on the current element, or if the current element has no child elements other than descriptive elements, the user agent must process the URL to identify the referenced resource. If the URL reference is not invalid, then the URL's target element is used as the template element, as follows:

When a paint-server element has a shadow tree, the element instances in that tree must be used in rendering the paint server effect, as if they were the paint server element's own children.

The use-element shadow tree model for templating allows cloned content to inherit different styles than the original. This behavior is newly defined in SVG 2; SVG 1.1 did not define how styles applied to inherited paint server content.

13.2. Solid colors

Solid Colors are new in SVG 2 (ported from SVG 1.2 Tiny).

SVG 2 Requirement: Support named colors.
Resolution: Will add ‘solidColor’ element to SVG 2.
Purpose: To provide an easy mechanism for creating named colors and palettes. Also useful for animation.
Owner: Tav (no action)

The 'solidcolor' element is a paint server that provides a single color with opacity. It can be referenced any place a single color can be used. The 'solidcolor' element allows a palette to be defined and used consistently throughout a document. It is also useful as away of animating a palette colors. (See CSS3 Color for a more general discussion of color [CSS3COLOR].)

In SVG 1.1, 1-stop gradients can be used to to produce a palette. This method for creating a palette fails, however, when a palette color is to be used for a gradient stop, a flood-fill, etc.

Solid colors are defined by a solidcolor element.

solidcolor
Categories:
Paint server element
Content model:
Any number of the following elements, in any order:animate, script, set, style
Attributes:
DOM Interfaces:

13.2.1. Properties

solid-color

The solid-color property specifies the color of the solidcolor. The keyword currentColor and ICC colors can be specified in the same manner as within a <paint> specification for the fill and stroke properties.

Value
currentColor | <color> <icccolor>
Initial
black
Applies to
solid-color elements
Inherited
no
Percentages
N/A
Media
visual
Animatable
yes
solid-opacity

The solid-opacity property defines the opacity of the solidcolor.

Value
<opacity-value>
Initial
1
Applies to
solid-color elements
Inherited
no
Percentages
N/A
Media
visual
Animatable
yes
<opacity-value>
The opacity of the 'solidcolor'. Any values outside the range 0.0 (fully transparent) to 1.0 (fully opaque) must be clamped to this range. The value of 'solid-opacity' is independent of the opacity used to render the paint via fill or stroke.
<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 300 100" >

  <title>Example solidColor</title>
  <desc>Fill objects using a solidColor paint server.</desc>

  <defs>
    <solidColor id="MyLightPurple" solid-color="#a080ff" solid-opacity="0.5"/>
  </defs>

  <!-- The shapes are filled using a solidColor paint server -->
  <circle fill="url(#MyLightPurple)" cx="50" cy="50" r="40"/>
  <rect   fill="url(#MyLightPurple)" x="110" y="10" width="80" height="80"/>
  <path   fill="url(#MyLightPurple)" d="m 250 10 l 40 80 -80 0 z"/>
</svg>
Example solidcolor.svg — fill objects using a solidcolor paint server

Example solidcolor.svg

View this example as SVG (SVG-enabled browsers only)

13.3. Gradients

Gradients consist of smooth color transitions between points on a drawing surface. SVG provides for three types of gradients:

Once a gradient is defined, a graphics element can be filled or stroked with the gradient by setting the fill or stroke properties to reference the gradient.

Color transitions for linear and radial gradients are defined by a series of color stops along a gradient vector. A gradient normal defines how the colors in a vector are painted to the surface. For a linear gradient, a normal is a line perpendicular to the vector. For a radial gradient, a normal is a circle intersecting the vector at a right angle. Each gradient normal is painted with one color determined by the vector.

Image of linear and radial gradients with vectors and normals indicated.

Linear and radial gradients with the gradient vector indicated. The vector consists of three stops shown by small circles. One gradient normal is shown for each gradient.

For linear and radial gradients, the color value between two stops along the gradient vector is the linear interpolation, per channel, of the color for each stop, weighted by the distance from each stop.

V = C0 + ( C1 - C0 ) ( D - O0 O1 - O0 )
    $V = C0.rgba + (C1.rgba - C0.rgba) * ((D - C0.offset) / (C1.offset - C0.offset));
  

Where, for each channel:

When a graphics element references a gradient, conceptually the graphics element should take a copy of the gradient vector with gradient normals and treat it as part of its own geometry. Any transformations applied to the graphics element geometry also apply to the copied gradient vector and gradient normals. Any gradient transforms that are specified on the reference gradient are applied before any graphics element transformations are applied to the gradient.

Color transitions for mesh gradients are defined by an array of color stops. The mapping of colors to the drawing surface in this case is done by geometric data located in the stops. This is discussed in detail in the mesh gradients section.

13.3.1. Definitions

gradient element
A gradient element is one that defines a gradient paint server. This specification defines the following gradient elements: linearGradient, meshgradient and radialGradient.

13.3.2. Linear gradients

Linear gradients are defined by a linearGradient element.

linearGradient
Categories:
Gradient element, never-rendered element, paint server element
Content model:
Any number of the following elements, in any order:animate, animateTransform, script, set, stop, style
Attributes:
DOM Interfaces:

13.3.2.1. Attributes

gradientUnits

Defines the coordinate system for attributes x1, y1, x2 and y2.

Value
userSpaceOnUse | objectBoundingBox
initial value
objectBoundingBox
Animatable
yes
userSpaceOnUse

If gradientUnits="userSpaceOnUse", x1, y1, x2, and y2 represent values in the coordinate system that results from taking the current user coordinate system in place at the time when the gradient element is referenced (i.e., the user coordinate system for the element referencing the gradient element via a fill or stroke property) and then applying the transform specified by attribute gradientTransform. Percentages represent values relative to the current SVG viewport.

objectBoundingBox

If gradientUnits="objectBoundingBox", the user coordinate system for attributes x1, y1, x2 and y2 is established using the bounding box of the element to which the gradient is applied (see Object bounding box units) and then applying the transform specified by attribute gradientTransform. Percentages represent values relative to the bounding box for the object.

When gradientUnits="objectBoundingBox" and gradientTransform is the identity matrix, the normal of the linear gradient is perpendicular to the gradient vector in object bounding box space (i.e., the abstract coordinate system where (0,0) is at the top/left of the object bounding box and (1,1) is at the bottom/right of the object bounding box). When the object's bounding box is not square, the gradient normal which is initially perpendicular to the gradient vector within object bounding box space may render non-perpendicular relative to the gradient vector in user space. If the gradient vector is parallel to one of the axes of the bounding box, the gradient normal will remain perpendicular. This transformation is due to application of the non-uniform scaling transformation from bounding box space to local coordinate system.

gradientTransform

Contains the definition of an optional additional transformation from the gradient coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse' or 'objectBoundingBox'). This allows for things such as skewing the gradient. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations, including the implicit transformation necessary to convert from object bounding box units to local coordinate system.

Value
<transform-list>
initial value
identity transform
Animatable
yes
x1

x1, y1, x2 and y2 define a gradient vector for the linear gradient. This gradient vector provides starting and ending points onto which the gradient stops are mapped. The values of x1, y1, x2 and y2 can be either numbers or percentages.

Value
<length>
initial value
0%
Animatable
yes
y1

See x1.

Value
<length>
initial value
0%
Animatable
yes
x2

See x1.

Value
<length>
initial value
100%
Animatable
yes
y2

See x1.

Value
<length>
initial value
0%
Animatable
yes
spreadMethod

Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.

Value
pad | reflect | repeat
initial value
pad
Animatable
yes
pad
Use the terminal colors of the gradient to fill the remainder of the target region.
reflect
Reflect the gradient pattern start-to-end, end-to-start, start-to-end, etc. continuously until the target rectangle is filled.
repeat
Repeat the gradient pattern start-to-end, start-to-end, start-to-end, etc. continuously until the target region is filled.
Image of the three possible values for 'spreadMethod'.

Illustration of the three possible values for spreadMethod, from left to right: pad, reflect, repeat. The gradient vector spans from 40% to 60% of the bounding box width.

href

A URL reference to a template gradient element; to be valid, the reference must be to a different linearGradient or a radialGradient element.

Refer to the process for using paint servers as templates, and to the common handling defined for URL reference attributes and deprecated XLink attributes.

The specified attributes that will be copied from the template are:

Value
URL [URL]
initial value
empty
Animatable
yes

13.3.2.2. Notes on linear gradients

If x1 = x2 and y1 = y2, then the area to be painted will be painted as a single color using the color and opacity of the last gradient stop.

Example lingrad01 shows how to fill a rectangle by referencing a linear gradient paint server.

<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1"
     viewBox="0 0 300 200" >

  <title>Example lingrag01</title>
  <desc>Fill a rectangle using a linear-gradient paint server.</desc>

  <defs>
    <linearGradient id="MyGradient">
      <stop offset="5%" stop-color="#A8F" />
      <stop offset="95%" stop-color="#FDC" />
    </linearGradient>
  </defs>

  <!-- The rectangle is filled using a linear-gradient paint server -->
  <rect fill="url(#MyGradient)"
	stroke="black"
	stroke-width="2"
	x="25" y="25" width="250" height="150"/>
</svg>
Example lingrad01 — Fill a rectangle by referencing a linear gradient paint server

Example lingrad01

View this example as SVG (SVG-enabled browsers only)

13.3.3. Radial gradients

Radial gradients are defined by a radialGradient element.

radialGradient
Categories:
Gradient element, never-rendered element, paint server element
Content model:
Any number of the following elements, in any order:animate, animateTransform, script, set, stop, style
Attributes:
DOM Interfaces:

13.3.3.1. Attributes

gradientUnits = "userSpaceOnUse | objectBoundingBox"

Defines the coordinate system for attributes cx, cy, r, fx, fy, and fr.

initial value
objectBoundingBox
Animatable
yes
userSpaceOnUse

If gradientUnits="userSpaceOnUse", cx, cy, r, fx, fy, and fr represent values in the coordinate system that results from taking the current user coordinate system in place at the time when the gradient element is referenced (i.e., the user coordinate system for the element referencing the gradient element via a fill or stroke property) and then applying the transform specified by attribute gradientTransform. Percentages represent values relative to the current SVG viewport.

objectBoundingBox

If gradientUnits="objectBoundingBox", the user coordinate system for attributes cx, cy, r, fx, fy, and fr is established using the bounding box of the element to which the gradient is applied (see Object bounding box units) and then applying the transform specified by attribute gradientTransform. Percentages represent values relative to the bounding box for the object.

When gradientUnits="objectBoundingBox" and gradientTransform is the identity matrix, then the rings of the radial gradient are circular with respect to the object bounding box space (i.e., the abstract coordinate system where (0,0) is at the top/left of the object bounding box and (1,1) is at the bottom/right of the object bounding box). When the object's bounding box is not square, the rings that are conceptually circular within object bounding box space will render as elliptical due to application of the non-uniform scaling transformation from bounding box space to local coordinate system.

gradientTransform = "<transform-list>"

Contains the definition of an optional additional transformation from the gradient coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse' or 'objectBoundingBox'). This allows for things such as skewing the gradient. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations, including the implicit transformation necessary to convert from object bounding box units to local coordinate system.

initial value
identity transform
Animatable
yes
cx = "<length>"

cx, cy and r define the end circle for the radial gradient. The gradient will be drawn such that the 100% gradient stop is mapped to the perimeter of this end circle.

initial value
50%
Animatable
yes
cy = "<length>"

See cx.

initial value
50%
Animatable
yes
r = "<length>"

See cx.

A negative value is an error (see Error processing).

initial value
50%
Animatable
yes
fx = "<length>"

fx, fy, and fr define the start circle for the radial gradient. The gradient will be drawn such that the 0% gradient stop is mapped to the perimeter of this start circle.

initial value
see below
Animatable
yes

If attribute fx is not specified, fx will coincide with the presentational value of cx for the element whether the value for 'cx' was inherited or not. If the element references an element that specifies a value for 'fx', then the value of 'fx' is inherited from the referenced element.

Diagram of various radial gradient attributes.

This diagram shows how the geometric attributes are defined for the case where fr is 50% of r. The small circle marks the center of the outermost circle (cx,cy), while the cross marks the center of the innermost circle (fx,fy). The dashed lines show two gradient vectors. Vectors connect corresponding points on the inner and outer most circles. The region outside the outer circle is painted with the last stop-color while the region inside the inner circle is painted with the first stop-color.

fy = "<length>"

See fx.

initial value
see below
Animatable
yes

If attribute fy is not specified, fy will coincide with the presentational value of cy for the element whether the value for 'cy' was inherited or not. If the element references an element that specifies a value for 'fy', then the value of 'fy' is inherited from the referenced element.

fr = "<length>"

New in SVG 2. Added to align with Canvas.

fr is the radius of the focal circle. See fx.

A negative value is an error (see Error processing).

initial value
0%, see below
Animatable
yes

If the attribute is not specified, the effect is as if a value of '0%' were specified. If the element references an element that specifies a value for 'fr', then the value of 'fr' is inherited from the referenced element.

SVG 2 Requirement: Allow specifying focal circle radius in radial gradients.
Resolution: Add an ‘fr’ attribute to ‘radialGradient’> for SVG 2.
Purpose: To align with Canvas. The zero-offset stop would be along the circle defined by the ‘fx’, ‘fy’ and ‘fr’ attributes.
Owner: Erik (ACTION-3098)
spreadMethod = "pad | reflect | repeat"

Indicates what happens if the gradient starts or ends inside the bounds of the object(s) being painted by the gradient. Has the same values and meanings as the spreadMethod attribute on linearGradient element.

initial value
pad
Animatable
yes
href = [URL]

A URL reference to a template gradient element; to be valid, the reference must be to a linearGradient element or a different radialGradient element.

Refer to the process for using paint servers as templates, and to the common handling defined for URL reference attributes and deprecated XLink attributes.

The specified attributes that will be copied from the template are:

Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.

initial value
empty
Animatable
yes
SVG 2 Requirement: Clarify radial gradients with focal point on the circle.
Resolution: When the focal point is on the circle edge, with repeat, then the distance between the first and last stop for the repeating colors is 0 and the paint should generate a color that is the average of all the gradient stops.
Purpose: To improve interoperability of radial gradients.
Owner: Erik (ACTION-3097)
Note: SVG 1.1 does not define what to do when the focal point is on the circle edge, with 'repeat'. The distance between the first and last stop for the repeating colors is 0. It was resolved that the paint should generate a color that is the weighted average (by offset) of all the gradient stops.

13.3.3.2. Notes on radial gradients

Changed in SVG 2. SVG 1.1 required that the focal point, if outside the end circle, be moved to be on the end circle. The change was made to align with Canvas.

Allowing the focal point to lie outside the end circle was resolved at the Rigi Kaltbad working group meeting.

If the start circle defined by fx, fy and fr lies outside the end circle defined by cx, cy, and r, effectively a cone is created, touched by the two circles. Areas outside the cone stay untouched by the gradient (transparent black).

If the start circle fully overlaps with the end circle, no gradient is drawn. The area stays untouched (transparent black).

Image of a radial gradient with the focal (start circle) outside
	  the start circle.

A radial gradient with the focal (start) circle outside the end circle. The focal circle is the smaller circle on the right. The gradient has spreadMethod="reflect".

Image of two radial gradients, one with the focus just inside the circumference
    and one with the focus on the circumference.

Two radial gradients with spreadMethod="repeat". On the left, the focal point is just inside the right side of the circle defined by by cx, cy, and r. On the right, the focal point is on the circle. In this case, the area painted to the right of the circumference has a fill equal to the weighted average of the colors in the gradient vector.

The treatment of the area to the right of the gradient in the right-hand side of the above figure is different from that of Canvas where the area would be transparent black. The difference is to maintain compatibility with SVG 1.1.

The color space for the weighted average is the same as in which the gradient is interpolated. See Rigi Kaltbad working group meeting.

Example radgrad01 shows how to fill a rectangle by referencing a radial gradient paint server.

<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 300 200" >
  <title>Example radgrad01</title>
  <desc>Fill a rectangle by referencing a radial gradient paint server.</desc>

  <defs>
    <radialGradient id="MyGradient"
		    gradientUnits="userSpaceOnUse"
		    cx="150" cy="100"
		    r="100">
      <stop offset="0%"   stop-color="#A8F" />
      <stop offset="50%"  stop-color="#FDC" />
      <stop offset="100%" stop-color="#A8F" />
    </radialGradient>
  </defs>

  <!-- The rectangle is filled using a radial gradient paint server -->
  <rect fill="url(#MyGradient)"
	stroke="black"
	stroke-width="2"
	x="25" y="25" width="250" height="150"/>
</svg>
Example radgrad01 — Fill a rectangle by referencing a radial gradient paint server

Example radgrad01

View this example as SVG (SVG-enabled browsers only)

13.3.4. Mesh gradients

Mesh gradients are defined by a meshgradient element.

SVG 2 Requirement: Support photorealistic gradients.
Resolution: Mesh gradients are accepted by the WG for SVG 2.
Purpose: To allow more complex gradients such as those found in nature.
Owner: Tav (ACTION-3121)

Resolution: Rename stop-path to 'd' or 'path' (Coons patch syntax).

Seattle 2011 F2F day 3

Resolution: We will allow just C/c/L/l in mesh path data. We will leave out tensor control points. We will not allow multiple colors at mesh intersections, just use zero size patches instead.

Boston 2011 F2F

Resolution: We will have a type="smooth-bicubic" or similar on <mesh>. (Note: In the resolution, the attribute is incorrectly placed on <patch>; see the minutes.)

Sydney 2015 F2F

New in SVG 2. Added to allow complex shadings. This is needed, for example, in creating life-like drawings or in interpolating data points on a two-dimensional grid.

The mesh gradients in SVG are based on an array of Coons Patches. A Coons Patch is a shading defined by colors place at the corners of an area enclosed by four Bézier curves. The interpolation of the corner colors into the patch can either be bilinear or bicubic.

Image of single mesh patch.

A single Coons-Mesh patch.

A Coons Patch is equivalent to a bi-cubic Ferguson patch where the distance between a cubic Bézier end point and its nearest control point is one-third the length of the corresponding Ferguson tangent line.

13.3.4.1. Mesh Structure

A mesh gradient consists of patches placed in an array. There are two reasons for using an array. The first is that an array of meshes is a natural result for most content creation processes (start with a path and then subdivide its area into rows and columns of patches). The second is that the data can be compacted by sharing sides and corners. The array structure is conceptual only. The actual mesh can be distorted in any way possible. The mesh gradient syntax is designed so that it is easy to simulate other types of gradients such as conical gradients or triangle meshes as shown in the examples below.

The structure of a mesh gradient:

<mesh x="100" y="100">
  <meshrow>
    <meshpatch>
      <stop .../>
        Up to four stops in first patch. See details below.
    </meshpatch>
    <meshpatch>
      Any number of meshpatches in row.
    </meshpatch>
  </meshrow>
  <meshrow>
    Any number of meshrows, each with the same number of meshpatches as in the first row.
  </meshrow>
</mesh>

The first meshpatch in the first meshrow contains four stop elements. These elements correspond conceptually, in order, to the top, right, bottom, and left edges of the first patch. The following patches in the first row contains three stop elements, corresponding to the top, right, and bottom edges of the patch. The left edge of one of these patches is taken from the (reversed) right edge of the previous patch. The first patch of following rows contains three stop elements, corresponding to the right, bottom, and left edges. The top edge is taken from the (reversed) bottom edge of the first patch in the row above. The remaining patches contain two stop elements, corresponding to the right and bottom edges of the patch. The top edge is taken from the patch directly above in the array of patches while the left edge is taken from the previous patch in the same row.

Each stop element contains a path attribute which consists of a single 'c', 'C', 'l', or 'L' path command. The initial point for the path command is taken from the last point of the previous edge of the patch (which for the first stop in a patch is defined in the patch to the left or top), except for the first patch in the first row where the initial point is given by the x and y attributes in the meshgradient element. The path command in the last stop element of a meshpatch has one less point than normal as this "missing" point necessary to close the path is already defined.

For each stop element there is a color and opacity that correspond to the patch corner at the initial point of the stop's edge. This color and opacity are defined inside the stop by the stop-color and stop-opacity properties except for the first stop in all patches other than the first patch in the first row where the stop color and opacity are already defined by a previous patch.

Here is an annotated example of a two by two mesh gradient:

<meshgradient x="50" y="50" id="example"> <!-- x, y used for initial point in first patch. -->
  <meshrow> <!-- No attributes, used only to define begin/end of row. -->
	<meshpatch>
	  <stop path="c  25,-25  75, 25  100,0" stop-color="lightblue" />
	  <stop path="c  25, 25 -25, 75  0,100" stop-color="purple" />
	  <stop path="c -25, 25 -75,-25 -100,0" stop-color="red" />
	  <stop path="c -25,-25, 25,-75"        stop-color="purple" /> <!-- Last point not needed (closed path). -->
	</meshpatch>
	<meshpatch>
	  <stop path="c  25,-25  75, 25  100,0" /> <!-- stop-color from previous patch. -->
	  <stop path="c  25, 25 -25, 75  0,100" stop-color="lightblue" />
	  <stop path="c -25, 25 -75,-25"        stop-color="purple" /> <!-- Last point not needed (closed path). -->
	  <!-- Last path (left side) taken from right side of previous path (with points reversed). -->
	</meshpatch>
  </meshrow>
  <meshrow> <!-- New row. -->
	<meshpatch>
	  <!-- First path (top side) taken from bottom path of patch above. -->
	  <stop path="c  25, 25 -25, 75  0,100" /> <!-- stop-color from patch above. -->
	  <stop path="c -25, 25 -75,-25 -100,0" stop-color="purple" />
	  <stop path="c -25,-25, 25,-75"        stop-color="lightblue" /> <!-- Last point not needed (closed path). -->
	</meshpatch>
	<meshpatch>
	  <!-- First path (top side) taken from bottom path of patch above (with points reversed). -->
	  <stop path="c  25, 25 -25, 75  0,100" /> <!-- stop-color from patch above. -->
	  <stop path="c -25, 25 -75,-25"        stop-color="lightblue" /> <!-- Last point not needed (closed path). -->
	  <!-- Last path (left side) taken from right side of previous path (with points reversed). -->
	</meshpatch>
  </meshrow>
</meshgradient>
  

The above mesh gradient is rendered as:

Rendering of a two by two mesh.

The rendering for the above two by two mesh example. The overlaid paths show the order in which the patch edges are defined.

Coons patch meshes can simulate other types of gradients. Here is an example of a conic gradient:

Rendering of a one by four mesh where each mesh covers
          a conic section.

The rendering for a one row, four patch mesh that simulates a conic gradient. The bottom edge of each patch is of zero length.

13.3.4.2. Painting a Mesh Patch

The corner colors are mapped to the patch area with a two step process. First the colors are placed at the corners of a unit square and the area inside the square is then colored using either bilinear interpolation or bicubic interpolation. Second, the points inside the square are mapped to points inside the patch using the following formula:

S = S C + S D S B
    $S = S_C + S_D - S_B$
  

where

S C ( u , v ) = ( 1 v ) × C 1 ( u ) + v × C 2 ( u ) , S D ( u , v ) = ( 1 u ) × D 1 ( v ) + u × D 2 ( v ) , S B ( u , v ) = ( 1 v ) × [ ( 1 u ) × C 1 ( 0 ) + u × C 1 ( 1 ) ] + v × [ ( 1 u ) × C 2 ( 0 ) + u × C 2 ( 1 ) ] .
    $$
    \begin{align}
    S_C(u,v) &= (1-v)×C_1(u) + v×C_2(u),\\
    S_D(u,v) &= (1-u)×D_1(v) + u×D_2(v),\\
    S_B(u,v) &= (1-v)×[(1-u)×C_1(0) + u×C_1(1)]\\
    &\qquad {}+  v×[(1-u)×C_2(0) + u×C_2(1)].
    \end{align}
    $$
  

C1 , C2 , D1 , and D2 are the curves at the top, bottom, left, and right of the patch, respectively; u and v are the coordinates inside the unit square. The subtraction term ensures that the boundary conditions are met.

Come up with better explanation of the mapping with diagram.

One method of rendering a patch is to "divide and conquer." Check if the four corner colors of the patch are the same within a specified tolerance. If so, paint the patch with the average color using the normal path filling routine. If not, divide the patch into four smaller patches and repeat the color tolerance check. Repeat the process as many times as necessary.

Another way to render a patch is to first divide the patch vertically or horizontally into a series of smaller patches that are each less than one pixel high or wide. Then each resulting patch can be rendered as a path.

Bilinear interpolation of the corner colors depends only on the values of the corner colors. The color profile along two opposite edges is first computed and then corresponding points along those edges are interpolated to fill in the interior. The color profile across a patch boundary may not be smooth, leading to an optical phenomena known as Mach banding.

Bicubic interpolation requires knowing not only the value of the corner colors but also their derivatives. The derivatives are chosen to ensure a smooth transition across patch boundaries and that there are no color value minima or maxima in the patch interior (i.e. a monotone cubic interpolation). Only the derivatives in x and y (where the x and y are the directions along the rows and columns of the conceptual mesh grid) are used (the cross derivatives are set to zero).

To calculate the derivatives: Let ck be the color value at the point pk, where k=0, ... ,n.

  1. First compute the secant lines:
    Δ k = c k + 1 c k p k + 1 p k
    	\Delta_k = {{c_{k+1}-c_k}\over{\lvert p_{k+1}-p_k\rvert}}
          
    If pk = pk+1 , set Δ k = 0 .
  2. The provisional derivative at pk is then
    δ k = Δ k 1 + Δ k 2
    	$ \delta_k = {\Delta_{k-1} + \Delta_k\over 2}  $
          
    for k=1, ... , n1. The derivatives for k=0 and k=n are calculated later (see below).
  3. If Δ k 1 and Δ k are of opposite sign then set δ k = 0 . (This is a local minima or maxima.) Skip the remaining steps.
  4. If δ k > 3 × Δ k 1 then set δ k = 3 × Δ k 1 . This step and the following step ensure that the interpolation is monotonic.
  5. If δ k > 3 × Δ k then set δ k = 3 × Δ k .
  6. Find the end point derivatives: If n>2 then:
    δ 0 = 2 × Δ 0 δ 1
    	$ \delta_1 = 2\times\Delta_1 - \delta_2  $
          
    δ n = 2 × Δ n 1 δ n 1
    	$ \delta_n = 2\times\Delta_{n-1} - \delta_{n-1}  $
          
    else δ 1 = δ n = Δ 0 .

The typical method for dealing with the start or end of a bicubic interpolation is to add an extra point before and an extra point after the given points. The value of the point before (after) is assigned either the value of the first (last) point or a value so that the secant before (after) is the same as the secant after (before) the first (last) point. The method described here does not rely on the addition of points but instead fits a quadratic curve to the color values and the already determined derivative at the other edge of the patch. This produces an interpolation that does not have an inflection point inside the patch.

Bicubic interpolation will produce smooth patch boundaries when a mesh is laid out on a rectangular grid and where the patch edges are linear. If the grid is distorted or the patch edges are not lines (i.e. they are Bézier curves), it is still possible to produce non-smooth transitions across patch boundaries.

Mesh gradients are defined by a meshgradient element.

meshgradient
Categories:
Gradient element, never-rendered element, paint server element
Content model:
Any number of the following elements, in any order:animate, animateTransform, meshrow, script, set
Attributes:
DOM Interfaces:

13.3.4.3. Attributes

gradientUnits

Defines the coordinate system for attributes x and y.

Value
userSpaceOnUse | objectBoundingBox
initial value
objectBoundingBox
Animatable
yes
userSpaceOnUse

If gradientUnits="userSpaceOnUse", x and y represent values in the coordinate system that results from taking the current user coordinate system in place at the time when the gradient element is referenced (i.e., the user coordinate system for the element referencing the gradient element via a fill or stroke property) or when the mesh is rendered on its own (i.e. not as a paint server) and then applying the transform specified by attribute transform. Percentages represent values relative to the current SVG viewport.

objectBoundingBox

Path data to be interpreted as fraction of bounding box (between 0 and 1) agreed to during the 16 July 2015 Weekly Teleconference.

If gradientUnits="objectBoundingBox", the user coordinate system for attributes x and y, and for mesh path data is established using the bounding box of the element to which the gradient is applied (see Object bounding box units) and then applying the transform specified by attribute transform. For the x and y attributes, percentages represent values relative to the bounding box for the object. For mesh path data, coordinates represent fractions of the bounding box.

When a mesh is rendered on its own (i.e., not as a paint server) the current SVG viewport is used in place of the bounding box.

transform

Contains the definition of an optional additional transformation from the mesh coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse'). This allows for things such as skewing the gradient. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations.

Value
<transform-list>
initial value
identity transform
Animatable
yes
x

x and y define the starting point of the mesh grid.

Value
<length>
initial value
0%
Animatable
yes
y

See x.

Value
<length>
initial value
0%
Animatable
yes
href

A URL reference to a template element, which must be a different meshgradient element to be valid.

Refer to the process for using paint servers as templates, and to the common handling defined for URL reference attributes and deprecated XLink attributes.

The specified attributes that will be copied from the template are:

Processing of template child content is the same as for linearGradient except that all meshrow, meshpatch, and stop elements are considered and cloned into the shadow tree.

Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.

Value
URL [URL]
initial value
empty
Animatable
yes
type

Determines the type of interpolation to use when painting a patch.

Value
bilinear | bicubic
initial value
bilinear
Animatable
no

Mesh rows are defined by a meshrow element.

meshrow
Categories:
None
Content model:
Any number of the following elements, in any order:meshpatch, script, style
Attributes:
DOM Interfaces:

Mesh patches are defined by a meshpatch element.

meshpatch
Categories:
None
Content model:
Any number of descriptive elements, script and from two to four stop elements.
Attributes:
DOM Interfaces:

13.3.5. Gradient stops

The vector (linear and radial gradients) or array (mesh gradients) of colors to use in a gradient is defined by the stop elements that are child elements to a linearGradient, radialGradient, or meshpatch element.

In SVG 1.1, the above read: "The ramp of colors..." but "ramp" is used nowhere else in this section.

stop
Categories:
None
Content model:
Any number of the following elements, in any order:
    animate, script, set, style
    Attributes:
    DOM Interfaces:

    13.3.5.1. Attributes

    offset

    Indicates were the gradient stop is placed. For linear gradients, the offset attribute represents a location along the gradient vector. For radial gradients, it represents a fractional distance from the edge of the innermost/smallest circle to the edge of the outermost/largest circle. This attribute does not apply to mesh gradients.

    Value
    <number> | <percentage>
    initial value
    0
    Animatable
    yes
    <number>
    A number usually ranging from 0 to 1.
    <percentage>
    A percentage usually ranging from 0% to 100%.
    path

    Gives the path for one side of a mesh gradient patch. This attribute applies only to mesh gradients.

    Value
    mesh path data
    initial value
    see notes below
    Animatable
    yes

    Mesh path data consists of a single 'l', 'L', 'c', or 'C' path command (as defined for the d property). See the mesh section above for how the path data is interpreted.

    13.3.5.2. Properties

    stop-color

    The stop-color property indicates what color to use at that gradient stop. The keyword currentColor and ICC colors can be specified in the same manner as within a <paint> specification for the fill and stroke properties.

    With respect to gradients, SVG treats the 'transparent' keyword differently than CSS. SVG does not calculate gradients in pre-multiplied space, so 'transparent' really means transparent black. Specifying a stop-color with the value 'transparent' is equivalent to specifying a stop-color with the value 'black' and a stop-opacity with the value '0'.

    Value
    currentColor | <color> <icccolor>
    Initial
    black
    Applies to
    stop elements
    Inherited
    no
    Percentages
    N/A
    Media
    visual
    Animatable
    yes
    stop-opacity

    The stop-opacity property defines the opacity of a given gradient stop.

    Value
    <opacity-value>
    Initial
    1
    Applies to
    stop elements
    Inherited
    no
    Percentages
    N/A
    Media
    visual
    Animatable
    yes
    <opacity-value>
    The opacity of the 'stopColor'. Any values outside the range 0.0 (fully transparent) to 1.0 (fully opaque) must be clamped to this range. The value of 'stop-opacity' is independent of the opacity used to render the paint via fill or stroke. The opacity value used for the gradient calculation is the product of the value of stop-opacity and the opacity of the value of stop-color. For stop-color value types of that don't include explicit opacity information, the opacity of that component must be treated as 1.

    13.3.5.3. Notes on gradient stops

    13.4. Patterns

    A pattern is used to fill or stroke an object using a pre-defined graphic object which can be replicated ("tiled") at fixed intervals in x and y to cover the areas to be painted. Patterns are defined using a pattern element and then referenced by properties fill and stroke on a given graphics element to indicate that the given element shall be filled or stroked with the pattern.

    Attributes x, y, width, height and patternUnits define a reference rectangle somewhere on the infinite canvas. The reference rectangle has its top/left at (xy) and its bottom/right at (x + widthy + height). The tiling theoretically extends a series of such rectangles to infinity in X and Y (positive and negative), with rectangles starting at (x + m*widthy + n* height) for each possible integer value for m and n.

    pattern
    Categories:
    Container element, never-rendered element, paint server element
    Content model:
    Any number of the following elements, in any order:a, clipPath, cursor, filter, foreignObject, image, marker, mask, script, style, switch, text, view
    Attributes:
    DOM Interfaces:

    13.4.1. Attributes

    patternUnits

    Defines the coordinate system for attributes x, y, width and height.

    Value
    userSpaceOnUse | objectBoundingBox
    initial value
    objectBoundingBox
    Animatable
    yes
    userSpaceOnUse

    If patternUnits="userSpaceOnUse", x, y, width and height represent values in the coordinate system that results from taking the current user coordinate system in place at the time when the pattern element is referenced (i.e., the user coordinate system for the element referencing the pattern element via a fill or stroke property) and then applying the transform specified by attribute patternTransform. Percentages represent values relative to the current SVG viewport.

    objectBoundingBox

    If patternUnits="objectBoundingBox", the user coordinate system for attributes x, y, width and height is established using the bounding box of the element to which the pattern is applied (see Object bounding box units) and then applying the transform specified by attribute patternTransform. Percentages represent values relative to the bounding box for the object.

    patternContentUnits

    Defines the coordinate system for the contents of the pattern. Note that this attribute has no effect if attribute viewBox is specified.

    Value
    userSpaceOnUse | objectBoundingBox
    initial value
    userSpaceOnUse
    Animatable
    yes
    userSpaceOnUse

    If patternContentUnits="userSpaceOnUse", the user coordinate system for the contents of the pattern element is the coordinate system that results from taking the current user coordinate system in place at the time when the pattern element is referenced (i.e., the user coordinate system for the element referencing the pattern element via a fill or stroke property) and then applying the transform specified by attribute patternTransform.

    objectBoundingBox

    If patternContentUnits="objectBoundingBox", the user coordinate system for the contents of the pattern element is established using the bounding box of the element to which the pattern is applied (see Object bounding box units) and then applying the transform specified by attribute patternTransform.

    patternTransform

    Contains the definition of an optional additional transformation from the pattern coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse' or 'objectBoundingBox'). This allows for things such as skewing the pattern tiles. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations, including the implicit transformation necessary to convert from object bounding box units to local coordinate system.

    Value
    <transform-list>
    initial value
    identity transform
    Animatable
    yes
    x

    x, y, width and height indicate how the pattern tiles are placed and spaced. These attributes represent coordinates and values in the coordinate space specified by the combination of attributes patternUnits and patternTransform.

    Value
    <length>
    initial value
    0
    Animatable
    yes
    y

    See x.

    Value
    <length>
    initial value
    0
    Animatable
    yes
    width

    See x.

    Value
    <length>
    initial value
    0
    Animatable
    yes

    A negative value is an error (see Error processing). A value of zero disables rendering of the element (i.e., no paint is applied).

    height

    See x.

    Value
    <length>
    initial value
    0
    Animatable
    yes

    A negative value is an error (see Error processing). A value of zero disables rendering of the element (i.e., no paint is applied).

    href

    A URL reference to a template element, which must be a different pattern element to be valid.

    Refer to the process for using paint servers as templates, and to the common handling defined for URL reference attributes and deprecated XLink attributes.

    The specified attributes that will be copied from the template are:

    Value
    URL [URL]
    initial value
    empty
    Animatable
    yes

    13.4.2. Notes on patterns

    SVG's user agent style sheet sets the overflow property for pattern elements to hidden, which causes a rectangular clipping path to be created at the bounds of the pattern tile. Unless the overflow property is overridden, any graphics within the pattern which goes outside of the pattern rectangle will be clipped. Example pattern01 below shows the effect of clipping to the pattern tile.

    Note that if the overflow property is set to to visible the rendering behavior for the pattern outside the bounds of the pattern is currently undefined. A future version of SVG may require the overflow to be shown. SVG implementers are encouraged to render the overflow as this is the behavior expected by authors. If overflow is rendered, the pattern tiles should be rendered left to right in rows and the rows from top to bottom.

    See GitHub Issue 129

    The contents of the pattern are relative to a new coordinate system. If there is a viewBox attribute, then the new coordinate system is fitted into the region defined by the x, y, width, height and patternUnits attributes on the pattern element using the standard rules for viewBox and preserveAspectRatio. If there is no viewBox attribute, then the new coordinate system has its origin at (xy), where x is established by the x attribute on the pattern element, and y is established by the y attribute on the pattern element. Thus, in the following example:

    <pattern x="10" y="10" width="20" height="20">
      <rect x="5" y="5" width="10" height="10"/>
    </pattern>
    

    the rectangle has its top/left located 5 units to the right and 5 units down from the origin of the pattern tile.

    The viewBox attribute introduces a supplemental transformation which is applied on top of any transformations necessary to create a new pattern coordinate system due to attributes x, y, width, height and patternUnits.

    Event attributes and event listeners attached to the contents of a pattern element are not processed; only the rendering aspects of pattern elements are processed.

    Example pattern01 shows how to fill a rectangle by referencing a pattern paint server. Note how the blue stroke of each triangle has been slightly clipped at the top and the left. This is due to SVG's user agent style sheet setting the overflow property for pattern elements to hidden, which causes the pattern to be clipped to the bounds of the pattern tile.

    <?xml version="1.0" standalone="no"?>
    <svg xmlns="http://www.w3.org/2000/svg"
         version="1.1"
         viewBox="0 0 300 200" >
    
      <title>Example pattern01</title>
      <desc>Fill an ellipse using a pattern paint server.</desc>
    
      <defs>
        <pattern id="TrianglePattern"
    	     patternUnits="userSpaceOnUse"
                 x="0" y="0" width="50" height="50"
                 viewBox="0 0 10 10" >
          <path d="M 0 0 L 7 0 L 3.5 7 z"
    	    fill="plum"
    	    stroke="blue" />
        </pattern> 
      </defs>
    
      <!-- The ellipse is filled using a triangle pattern paint server -->
      <ellipse fill="url(#TrianglePattern)"
    	   stroke="black"
    	   stroke-width="2"
               cx="150" cy="100" rx="125" ry="75" />
    </svg>
    Example pattern01 — fill a rectangle by referencing a pattern paint server

    Example pattern01

    View this example as SVG (SVG-enabled browsers only)

    13.5. Hatches

    Hatches are new in SVG 2. They were added to allow the kinds of patterns required for mapping, engraving, etc. where continuous lines are needed.

    SVG 2 Requirement: Support hatches.
    Resolution: SVG 2 should support hatchings without the artifacts that patterns currently impose.
    Purpose: To allow the kinds of patterns required for mapping, engraving, etc. where continuous lines are required.
    Owner: Tav (no action)
    Status: Done

    A hatch is used to fill or stroke an object using one or more pre-defined paths that are repeated at fixed intervals in a specified direction to cover the areas to be painted. Hatches are defined using a hatch element and then referenced by properties fill and stroke on a given graphics element to indicate that the given element shall be filled or stroked with the hatch. Paths are defined by hatchpath elements.

    Attributes x, y, pitch, rotate, and hatchUnits define an infinitely long reference strip on the infinite canvas. The strip has one edge at (xy) and its other edge at a distance of pitch in the direction defined by rotate. This one-dimension tiling theoretically extends a series of such strips in the direction of 'rotate' to infinity (positive and negative), with strips starting at (x + m*pitch*cos(rotate), y + m*pitch*sin(rotate) for each possible integer value of m.

    A diagram showing the layout of a series of strips.

    Three adjacent strips separated by dashed lines showing their relationship to each other for a given pitch and rotate. The reference line determines the origin of hatchpaths.

    hatch
    Categories:
    Never-rendered element, paint server element
    Content model:
    Any number of the following elements, in any order:hatchpath, script, style
    Attributes:
    DOM Interfaces:

    13.5.1. Attributes

    hatchUnits

    Defines the coordinate system for attributes x, y, pitch and rotate.

    Value
    userSpaceOnUse | objectBoundingBox
    initial value
    objectBoundingBox
    Animatable
    yes
    userSpaceOnUse

    If hatchUnits="userSpaceOnUse", x, y, pitch, and rotate represent values in the coordinate system that results from taking the current user coordinate system in place at the time when the hatch element is referenced (i.e., the user coordinate system for the element referencing the hatch element via a fill or stroke property) and then applying the transform specified by attribute transform. Percentages represent values relative to the current SVG viewport.

    objectBoundingBox

    If hatchUnits="objectBoundingBox", the user coordinate system for attributes x, y, pitch, and rotate is established using the bounding box of the element to which the hatch is applied (see Object bounding box units) and then applying the transform specified by attribute transform. Percentages represent values relative to the bounding box for the object.

    hatchContentUnits

    Defines the coordinate system for the contents of the hatch.

    Value
    userSpaceOnUse | objectBoundingBox
    initial value
    userSpaceOnUse
    Animatable
    yes
    userSpaceOnUse

    If hatchContentUnits="userSpaceOnUse", the user coordinate system for the contents of the hatch element is the coordinate system that results from taking the current user coordinate system in place at the time when the hatch element is referenced (i.e., the user coordinate system for the element referencing the hatch element via a fill or stroke property) and then applying the transform specified by attribute transform.

    objectBoundingBox

    If hatchContentUnits="objectBoundingBox", the user coordinate system for the contents of the hatch element is established using the bounding box of the element to which the hatch is applied (see Object bounding box units) and then applying the transform specified by attribute transform.

    transform

    Contains the definition of an optional additional transformation from the hatch coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse' or 'objectBoundingBox'). This allows for things such as skewing the hatch strips. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations, including the implicit transformation necessary to convert from object bounding box units to local coordinate system.

    Value
    <transform-list>
    initial value
    identity transform
    Animatable
    yes
    x

    x, y, pitch and rotate indicate how the hatch strips are placed and spaced. These attributes represent coordinates and values in the coordinate space specified by the combination of attributes hatchUnits and transform.

    Value
    <length>
    initial value
    0
    Animatable
    yes
    y

    See x.

    Value
    <length>
    initial value
    0
    Animatable
    yes
    pitch

    See x.

    Value
    <length>
    initial value
    0
    Animatable
    yes

    A negative value is an error (see Error processing). A value of zero disables rendering of the element (i.e., no paint is applied).

    rotate

    See x.

    Value
    <angle>
    initial value
    0
    Animatable
    yes

    Changed name from 'angle' to 'rotate' at Tokyo F2F.

    href

    A URL reference to a template element, which must be a different hatch element to be valid.

    Refer to the process for using paint servers as templates, and to the common handling defined for URL reference attributes and deprecated XLink attributes.

    The specified attributes that will be copied from the template are:

    Value
    URL [URL]
    initial value
    empty
    Animatable
    yes

    13.5.2. Notes on hatches

    SVG's user agent style sheet sets the overflow property for hatch elements to hidden, which causes an infinite strip clipping path to be created at the bounds of the hatch strip. Unless the overflow property is overridden, any graphics within the hatch which goes outside of the hatch strip will be clipped. Note that if the overflow property is set to visible the area outside must be rendered (NB this is different from a pattern element). Strips with higher x (larger m) values must be rendered after strips with lower x (lower m) values.

    The contents of the hatch are relative to a new coordinate system. The new coordinate system has its origin at (xy), where x is established by the x attribute on the hatch element, and y is established by the y attribute on the hatch element. The coordinate system is rotated around the origin by the angle given by the rotate attribute.

    The viewBox and preserveAspectRatio attributes are not useful and have been removed (as compared to the pattern element).

    Event listeners attached to the contents of a hatch element are not processed; only the rendering aspects of hatch elements are processed.

    The following illustrates a very simple hatch fill:

    <hatch hatchUnits="userSpaceOnUse" pitch="5" rotate="135">
      <hatchpath stroke="#a080ff" stroke-width="2"/>
    </hatch>
    

    13.5.3. Hatch paths

    Hatch paths are defined by a hatchpath element.

    hatchpath
    Categories:
    None
    Content model:
    Any number of the following elements, in any order:script, style
    Attributes:
    DOM Interfaces:

    13.5.3.1. Attributes

    d

    Defines a single path in the hatch.

    Note that the d attribute is not a presentation attribute for the d property.

    Value
    Path data
    initial value
    An infinite line, see below
    Animatable
    yes
    offset

    Defines the point along the reference line where a path begins.

    Value
    <length>
    initial value
    0
    Animatable
    yes

    13.5.3.2. Notes on hatch paths

    Hatch paths are defined with the same Path data used in the d property. The path is defined relative to the origin of each strip translated in the x direction by the offset (the y direction is aligned along the infinite axis of the strip).

    A diagram showing the coordinate system for the 'd' attribute.

    The coordinate system for path data relative to a strip.

    If a d attribute is not provided, the path defaults to an infinitely long line aligned with the y-axis of the reference strip and passing through a point offset distance in the x direction from the strip origin (see above).

    If a d attribute is given, the hatch path is constructed by repeating the d data, each time with an offset along the y-axis determined by the y value of the last path data point. (The offset must be positive, a negative or zero offset value results in the hatch path not being rendered.) A hatch path need not start with a "moveto" path instruction. If missing, the first path instruction uses for its current point a value of (x,0) where x is the x value of the last data point given in the path. If the first path command is not a "moveto" and the last not a "closepath", the last point of each repeating section is joined to the first point of the next repeating section with the current value of stroke-linejoin.

    A hatch path can have any of the stroke style properties applied to it, however only solid color paint servers are allowed for the stroke property.

    Limiting 'stroke' to solid paint servers was resolved at the Tokyo F2F.

    <hatch  hatchUnits="userSpaceOnUse" pitch="6" overflow="visible">
        <hatchpath stroke-width="1" d="C 0,4 8,6 8,10 8,14 0,16 0,20"/>
    </hatch>
    A hatch example with squiggly lines filling a rectangle.

    A hatch fill with a continuous squiggly hatchpath.

    View this example as SVG (SVG 2-enabled browsers only)
     

    <hatch  hatchUnits="userSpaceOnUse" pitch="20">
        <hatchpath stroke="#a080ff" stroke-width="2" d="L 0,0 10,50"/>
    </hatch>
    A hatch example with a zigzag line.

    A hatch fill with a zigzag hatchpath. The d path data describes two line segments, the first starting at (10, 0). The repeating sections are joined.

    View this example as SVG (SVG 2-enabled browsers only)
     

    <hatch  hatchUnits="userSpaceOnUse" pitch="20">
        <hatchpath stroke="#a080ff" stroke-width="2" d="M 0,0 10,50"/>
    </hatch>
    A hatch example with diagonal lines segments filling a rectangle.

    A hatch fill with diagonal line segments. The repeating sections are not joined.

    View this example as SVG (SVG 2-enabled browsers only)
     

    <hatch  hatchUnits="userSpaceOnUse" pitch="20">
        <hatchpath stroke="#a080ff" stroke-width="2"/>
        <hatchpath stroke="#a080ff" stroke-width="2" offset="5" stroke-dasharray="10 4 2 4"/>
    </hatch>
    A hatch example with two alternating lines, one dashed.

    A hatch fill with two hatchpaths, one dashed.

    View this example as SVG (SVG 2-enabled browsers only)
     

    13.6. DOM interfaces

    13.6.1. Interface SVGSolidcolorElement

    An SVGSolidcolorElement object represents an solidcolor element in the DOM.

    interface SVGSolidcolorElement : SVGElement {
    };

    13.6.2. Interface SVGGradientElement

    The SVGGradientElement interface is used as a base interface for gradient paint server element interfaces.

    interface SVGGradientElement : SVGElement {
    
      // Spread Method Types
      const unsigned short SVG_SPREADMETHOD_UNKNOWN = 0;
      const unsigned short SVG_SPREADMETHOD_PAD = 1;
      const unsigned short SVG_SPREADMETHOD_REFLECT = 2;
      const unsigned short SVG_SPREADMETHOD_REPEAT = 3;
    
      [SameObject] readonly attribute SVGAnimatedEnumeration gradientUnits;
      [SameObject] readonly attribute SVGAnimatedTransformList gradientTransform;
      [SameObject] readonly attribute SVGAnimatedEnumeration spreadMethod;
    };
    
    SVGGradientElement implements SVGURIReference;
    SVGGradientElement implements SVGUnitTypes;

    The numeric spread method type constants defined on SVGGradientElement are used to represent the keyword values that the ‘spreadMethod’ attribute can take. Their meanings are as follows:

    ConstantMeaning
    SVG_SPREADMETHOD_PADThe pad keyword.
    SVG_SPREADMETHOD_REFLECTThe reflect keyword.
    SVG_SPREADMETHOD_REPEATThe repeat keyword.
    SVG_SPREADMETHOD_UNKNOWNSome other value.

    The gradientUnits IDL attribute reflects the ‘gradientUnits’ content attribute. The numeric type values for ‘gradientUnits’ attributes on gradient elements are as follows:

    ValueNumeric type value
    userSpaceOnUse SVG_UNIT_TYPE_USERSPACEONUSE
    objectBoundingBox SVG_UNIT_TYPE_OBJECTBOUNDINGBOX

    The gradientTransform IDL attribute reflects the computed value of the transform property and either the ‘transform’ presentation attribute, for meshgradient elements, or the 'gradientTransform' presentation attribute for linearGradient and radialGradient elements.

    The spreadMethod IDL attribute reflects the ‘spreadMethod’ content attribute. The numeric type values for ‘spreadMethod’ attributes on gradient elements are as described above in the numeric spread type constant table.

    13.6.3. Interface SVGLinearGradientElement

    An SVGLinearGradientElement object represents an linearGradient in the DOM.

    interface SVGLinearGradientElement : SVGGradientElement {
      [SameObject] readonly attribute SVGAnimatedLength x1;
      [SameObject] readonly attribute SVGAnimatedLength y1;
      [SameObject] readonly attribute SVGAnimatedLength x2;
      [SameObject] readonly attribute SVGAnimatedLength y2;
    };

    The x1, y1, x2 and y2 IDL attributes reflect the x1, y1, x2 and y2 content attributes, respectively

    13.6.4. Interface SVGRadialGradientElement

    An SVGRadialGradientElement object represents an radialGradient in the DOM.

    interface SVGRadialGradientElement : SVGGradientElement {
      [SameObject] readonly attribute SVGAnimatedLength cx;
      [SameObject] readonly attribute SVGAnimatedLength cy;
      [SameObject] readonly attribute SVGAnimatedLength r;
      [SameObject] readonly attribute SVGAnimatedLength fx;
      [SameObject] readonly attribute SVGAnimatedLength fy;
      [SameObject] readonly attribute SVGAnimatedLength fr;
    };

    The cx, cy, r, fx, fy and fr IDL attributes reflect the cx, cy, r, fx, fy and fr content attributes, respectively

    13.6.5. Interface SVGMeshGradientElement

    The SVGMeshGradientElement interface corresponds to the mesh element.
    interface SVGMeshGradientElement : SVGGradientElement {
    };

    Note that the SVGMeshGradientElement does not have any reflecting IDL attributes for its x, y, ‘transform’, href and type attributes.

    13.6.6. Interface SVGMeshrowElement

    An SVGMeshrowElement object represents a meshrow element in the DOM.

    interface SVGMeshrowElement : SVGElement {
    };

    13.6.7. Interface SVGMeshpatchElement

    An SVGMeshpatchElement object represents a meshpatch element in the DOM.

    interface SVGMeshpatchElement : SVGElement {
    };

    13.6.8. Interface SVGStopElement

    An SVGStopElement object represents a stop element in the DOM.

    interface SVGStopElement : SVGElement {
      [SameObject] readonly attribute SVGAnimatedNumber offset;
    };

    The offset IDL attribute reflects the offset content attribute.

    Note that SVGStopElement does not have a reflecting IDL attribute for its path attribute.

    13.6.9. Interface SVGPatternElement

    An SVGPatternElement object represents a pattern element in the DOM.

    interface SVGPatternElement : SVGElement {
      [SameObject] readonly attribute SVGAnimatedEnumeration patternUnits;
      [SameObject] readonly attribute SVGAnimatedEnumeration patternContentUnits;
      [SameObject] readonly attribute SVGAnimatedTransformList patternTransform;
      [SameObject] readonly attribute SVGAnimatedLength x;
      [SameObject] readonly attribute SVGAnimatedLength y;
      [SameObject] readonly attribute SVGAnimatedLength width;
      [SameObject] readonly attribute SVGAnimatedLength height;
    };
    
    SVGPatternElement implements SVGFitToViewBox;
    SVGPatternElement implements SVGURIReference;
    SVGPatternElement implements SVGUnitTypes;

    The patternUnits and patternContentUnits IDL attributes reflect the patternUnits and patternContentUnits content attributes, respectively. The numeric type values for patternUnits and patternContentUnits are as follows:

    ValueNumeric type value
    userSpaceOnUse SVG_UNIT_TYPE_USERSPACEONUSE
    objectBoundingBox SVG_UNIT_TYPE_OBJECTBOUNDINGBOX

    The patternTransform IDL attribute reflects the computed value of the transform property and the ‘patternTransform’ presentation attribute.

    The x, y, width and height IDL attributes reflect the x, y, width and height content attributes, respectively.

    13.6.10. Interface SVGHatchElement

    interface SVGHatchElement : SVGElement {
    };

    Note that SVGHatchElement does not have any reflecting IDL attributes for its x, y, pitch, rotate, hatchUnits, hatchContentUnits, ‘transform’ or href attributes.

    13.6.11. Interface SVGHatchpathElement

    interface SVGHatchpathElement : SVGElement {
    };

    Note that SVGHatchpathElement does not have any reflecting IDL attributes for its d or offset attributes.

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Chapter 14: Scripting and Interactivity

    14.1. Introduction

    SVG content can be interactive (i.e., responsive to user-initiated events) by utilizing the following features in the SVG language:

    This chapter describes:

    Related information can be found in other chapters:

    14.2. Supported events

    SVG 2 Requirement: Support anchor change events.
    Resolution: SVG 2 will consider adding HTML document wide events (including hashchange) apply to SVG documents where they make sense.
    Purpose: To allow authors to use the same set of event listener attributes on a root SVG element that they can on an HTML body or root element.
    Owner: Cameron (ACTION-3278)
    SVG 2 Requirement: Have event listener attributes on an appropriate interface.
    Resolution: SVG 2 will move all events listener attributes to Element, in accordance with the similar move in HTML.
    Purpose: To align with HTML.
    Owner: Cameron (ACTION-3283)
    SVG 2 Requirement: Introduce evt as an alias to event in event handlers.
    Resolution: We decide to resolve ISSUE-2176 by introducing evt as an alias to event in event handlers.
    Purpose: To align with HTML.
    Owner: Cameron (ACTION-3093)
    SVG 2 Requirement: Support drag & drop functionality.
    Resolution: SVG 2 may require drag & drop functionality, and we'll investigate HTML5's functionality for that.
    Purpose: To allow easier drag & drop in SVG, and to align with HTML.
    Owner: Erik (ACTION-3328)

    The following aspects of SVG are affected by events:

    A number of events defined in SVG 1.1, SVGLoad, SVGError etc, have been replaced with the equivalent unprefixed events defined in DOM 3 Events and HTML.

    There should be some more modern examples of using events in svg, e.g touch events (w reference to touch events spec). Device orientation events might also be of interest.

    The following table lists the events defined by this specification, or that have further requirements or clarifications compared to the specification(s) where they are defined.

    The Event name in the first column is the name to use within SVG's animation elements to define the events which can start or end animations. The DOM3 Event name in the second column is the name to use when defining DOM 3 event listeners ([DOM3EVENTS], section 4.3).

    For events not listed in the table, such as events introduced in HTML or DOM 3 Events, the respective event type is the name to use within SVG's animation elements.

    Requirements in the table on whether an event of a given type bubbles or is cancelable apply only to events that are created and dispatched by the user agent. Events of those types created from script using the createEvent method on the Document interface can be made to bubble or be cancelable with the initEvent method.

    Event name and description DOM3 Event name Event category Event attribute name

    load

    The load event is dispatched only to structurally external elements and to the Window, when the corresponding external resources have finished loading. Note that due to it's relationship with Window the load event on svg elements is only dispatched when all resources in the document have been completely loaded.

    The load event and the error event on structurally external elements are mutually exclusive, only one of these events must be dispatched when processing the element in question.

    load events do not bubble and are not cancelable.

    In previous SVG specifications the load event was called SVGLoad and could be dispatched immediately after parsing an element but before the related resource(s) were fully loaded.

    (same) none onload

    unload

    Only applicable to outermost svg elements. The unload event occurs when the DOM implementation removes a document from a window or frame.

    unload events do not bubble and are not cancelable.

    (same) none onunload

    error

    The error event occurs when a structurally external element does not load properly or when an error occurs during script execution.

    error events bubble but are not cancelable.

    (same) none onerror

    beginEvent

    Occurs when an animation element begins. For details, see the description of Interface TimeEvent in the SMIL Animation specification.

    none none onbegin

    endEvent

    Occurs when an animation element ends. For details, see the description of Interface TimeEvent in the SMIL Animation specification.

    none none onend

    repeatEvent

    Occurs when an animation element repeats. It is raised each time the element repeats, after the first iteration. For details, see the description of Interface TimeEvent in the SMIL Animation specification.

    none none onrepeat

    Details on the parameters passed to event listeners for the event types for UI Events can be found in the ([ DOM3EVENTS]) and ([UIEVENTS]) specifications where the keybard event definition in UIEVENTS takes precedence over that in DOM3EVENTS. For other event types, the parameters passed to event listeners are described elsewhere in this specification.

    Likewise, event-value timing specifiers used in animation element begin and end attributes are resolved to concrete times only in response to "bubbling" and "at target" phase events dispatched to the relevant element.

    14.3. User interface events

    On user agents which support interactivity, it is common for authors to define SVG documents such that they are responsive to user interface events. Among the set of possible user events are pointer events, keyboard events, and document events.

    In response to user interface (UI) events, the author might start an animation, perform a hyperlink to another Web page, highlight part of the document (e.g., change the color of the graphics elements which are under the pointer), initiate a "roll-over" (e.g., cause some previously hidden graphics elements to appear near the pointer) or launch a script which communicates with a remote database.

    14.4. Pointer events

    User interface events that occur because of user actions performed on a pointer device are called pointer events.

    Many systems support pointer devices such as a mouse or trackball. On systems which use a mouse, pointer events consist of actions such as mouse movements and mouse clicks. On systems with a different pointer device, the pointing device often emulates the behavior of the mouse by providing a mechanism for equivalent user actions, such as a button to press which is equivalent to a mouse click.

    For each pointer event, the SVG user agent determines the target element of a given pointer event. The target element is the topmost graphics element whose relevant graphical content is under the pointer at the time of the event. (See property pointer-events for a description of how to determine whether an element's relevant graphical content is under the pointer, and thus in which circumstances that graphic element can be the target element for a pointer event.) When an element is not displayed (i.e., when the display property on that element or one of its ancestors has a value of none), that element cannot be the target of pointer events.

    If a target element for the pointer event exists, then the event is dispatched to that element according to the normal event flow ([DOM3EVENTS], section 1.2). For shadow trees created by the use element or via script, the event must follow the Shadow DOM event dispatching algorithm [SHADOWDOM]

    If a target element for the pointer event does not exist, then the event is ignored.

    14.5. Hit-testing and processing order for user interface events

    hit-testing
    The process of determining whether a pointer intersects a given graphics element. Hit-testing is used in determining which element to dispatch a mouse event to, which might be done in response to the user moving the pointing device, or by changes in the position, shape and other attributes of elements in the document. Hit-testing is also known as hit detection or picking. See also the definition of the pointer-events property.

    There are two distinct aspects of pointer-device interaction with an element or area:

    1. hit-testing, to determine if a pointer event (such as a mouse movement or mouse click) occurred within the interaction area of an element, and the subsequent DOM event flow;
    2. functional processing of actions associated with any relevant element.

    14.5.1. Hit-testing

    Determining whether a pointer event results in a positive hit-test depends upon the position of the pointer, the size and shape of the graphics element, and the computed value of the pointer-events property on the element. The definition of the pointer-events property below describes the exact region that is sensitive to pointer events for a given type of graphics element.

    Note that the svg element is not a graphics element, and in a Conforming SVG Stand-Alone File a outermost svg element will never be the target of pointer events, though events can bubble to this element. If a pointer event does not result in a positive hit-test on a graphics element, then it should evoke any user-agent-specific window behavior, such as a presenting a context menu or controls to allow zooming and panning of an SVG document fragment.

    This specification does not define the behavior of pointer events on the outermost svg element for SVG images which are embedded by reference or inclusion within another document, e.g., whether the outermost svg element embedded in an HTML document intercepts mouse click events; future specifications may define this behavior, but for the purpose of this specification, the behavior is implementation-specific.

    14.5.2. Event processing

    An element which is the target of a user interface event may have particular interaction behaviors, depending upon the type of element and whether it has explicit associated interactions, such as scripted event listeners, CSS pseudo-classes matches, or declarative animations with event-based timing. The algorithm and order for processing user interface events for a given target element, after dispatching the DOM event, is as follows:

    1. If an event handler registered on this element invokes the preventDefault() DOM method, then no further processing for this element is performed, and the event follows the event dispatch and DOM event flow processing as described in DOM Level 3 Events [DOM3EVENTS] (or its successor);
    2. If the element has an associated title or description, such as a title element, and the user agent supports the display of such information (e.g. via a tooltip or status-bar message), that information should be displayed, as appropriate to the type of pointer event;
    3. If the element matches any relevant dynamic pseudo-class selectors appropriate to the type of pointer event, such as :hover, :active, or :focus as described in [CSS21], section 5.11, then the relevant class properties are applied;
    4. If the element and the event type are associated with the activation or cancelation of declarative animation though the use of event-value timing specifiers, any corresponding instance times must be resolved, and any conseqential actions of this instance time resolution (such as immediately starting or stopping the animation) must be performed;
    5. If the element is a hyperlink (e.g., it is a descendant element of an a element), and the pointer event is of a type that activates that hyperlink (e.g. via a mouse click), and if the hyperlink traversal changes the context of the content (e.g. opens a different document, or moves the pointer away from this element by moving to another part of the same document), then no further processing for this element is performed;
    6. If the element is a text content element, and the event type is one which the user agent recognizes as part of a text-selection operation (e.g., a mouse click and drag, or a double-click), then the text selection algorithm is performed;
    7. If the event type is one which the user agent associates with the evocation of special user-interface controls (e.g., a right-click or command-click evoking a context menu), the user agent should evoke such user-agent-specific behavior, such as presenting a context menu or controls to allow zooming and panning of an SVG document fragment.

    14.6. The ‘pointer-events’ property

    In different circumstances, authors may want to control under what conditions particular graphic elements can become the target of pointer events. For example, the author might want a given element to receive pointer events only when the pointer is over the stroked perimeter of a given shape. In other cases, the author might want a given element to ignore pointer events under all circumstances so that graphical elements underneath the given element will become the target of pointer events.

    The effects of masking and clipping differ with respect to pointer events. A clip path is a geometric boundary, and a given point is clearly either inside or outside that boundary; thus, pointer events must be captured normally over the rendered areas of a clipped element, but must not be captured over the clipped areas, as described in the definition of clipping paths. By contrast, a mask is not a binary transition, but a pixel operation, and different behavior for fully transparent and almost-but-not-fully-transparent may be confusingly arbitrary; as a consequence, for elements with a mask applied, pointer events must still be captured even in areas where the mask goes to zero opacity. If an author wishes to achieve an effect where the transparent parts of a mask allow pointer events to pass to an element below, a combination of masking and clipping may be used.

    The filter property has no effect on pointer events processing, and must in this context be treated as if the filter wasn't specified.

    For example, suppose a circle with a stroke of red (i.e., the outline is solid red) and a fill of none (i.e., the interior is not painted) is rendered directly on top of a rectangle with a fill of blue. The author might want the circle to be the target of pointer events only when the pointer is over the perimeter of the circle. When the pointer is over the interior of the circle, the author might want the underlying rectangle to be the target element of pointer events.

    The pointer-events property specifies under what circumstances a given element can be the target element for a pointer event. It affects the circumstances under which the following are processed:

    Name: pointer-events
    Value: bounding-box | visiblePainted | visibleFill | visibleStroke | visible | painted | fill | stroke | all | none
    Initial: visiblePainted
    Applies to: container elements, graphics elements and text content child elements
    Inherited: yes
    Percentages: N/A
    Media: visual
    Computed value: as specified
    Animatable: yes
    bounding-box
    The given element must be a target element for pointer events when the pointer is over the bounding box of the element.
    visiblePainted
    The given element can be the target element for pointer events when the visibility property is set to visible and when the pointer is over a "painted" area. The pointer is over a painted area if it is over the interior (i.e., fill) of the element and the fill property has an actual value other than none or it is over the perimeter (i.e., stroke) of the element and the stroke property is set to a value other than none.
    visibleFill
    The given element can be the target element for pointer events when the visibility property is set to visible and when the pointer is over the interior (i.e., fill) of the element. The value of the fill property does not affect event processing.
    visibleStroke
    The given element can be the target element for pointer events when the visibility property is set to visible and when the pointer is over the perimeter (i.e., stroke) of the element. The value of the stroke property does not affect event processing.
    visible
    The given element can be the target element for pointer events when the visibility property is set to visible and the pointer is over either the interior (i.e., fill) or the perimeter (i.e., stroke) of the element. The values of the fill and stroke do not affect event processing.
    painted
    The given element can be the target element for pointer events when the pointer is over a "painted" area. The pointer is over a painted area if it is over the interior (i.e., fill) of the element and the fill property has an actual value other than none or it is over the perimeter (i.e., stroke) of the element and the stroke property has an actual value other than none. The value of the visibility property does not affect event processing.
    fill
    The given element can be the target element for pointer events when the pointer is over the interior (i.e., fill) of the element. The values of the fill and visibility properties do not affect event processing.
    stroke
    The given element can be the target element for pointer events when the pointer is over the perimeter (i.e., stroke) of the element. The values of the stroke and visibility properties do not affect event processing.
    all
    The given element can be the target element for pointer events whenever the pointer is over either the interior (i.e., fill) or the perimeter (i.e., stroke) of the element. The values of the fill, stroke and visibility properties do not affect event processing.
    none
    The given element does not receive pointer events.

    For text elements, hit-testing is performed on a character cell basis:

    For raster images, hit-testing is either performed on a whole-image basis (i.e., the rectangular area for the image is one of the determinants for whether the image receives the event) or on a per-pixel basis (i.e., the alpha values for pixels under the pointer help determine whether the image receives the event):

    Note that for raster images, the values of properties opacity, fill-opacity, stroke-opacity, fill and stroke do not affect event processing.

    14.7. Magnification and panning

    SVG 2 Requirement: Support level of detail control.
    Resolution: We will support Level of Detail control in SVG 2.
    Purpose: Control visibility of elements based on zoom level (useful, for example, in mapping).
    Owner: Doug (no action)
    Note: See Tiling and Layering Module for SVG 1.2 Tiny.

    Magnification represents a complete, uniform transformation on an SVG document fragment, where the magnify operation scales all graphical elements by the same amount. A magnify operation has the effect of a supplemental scale and translate transformation placed at the outermost level on the SVG document fragment (i.e., outside the outermost svg element).

    Panning represents a translation (i.e., a shift) transformation on an SVG document fragment in response to a user interface action.

    SVG user agents that operate in interaction-capable user environments are required to support the ability to magnify and pan.

    The outermost svg element in an SVG document fragment has attribute zoomAndPan, which takes the possible values of disable and magnify, with the default being magnify.

    The zoomAndPan attribute is at risk, it has no known implementations and is unlikely to be implemented. See Github issue #56.

    Name Value Initial value Animatable
    zoomAndPan [ disable | magnify ] disable no

    If disable, the user agent shall disable any magnification and panning controls and not allow the user to magnify or pan on the given document fragment.

    If magnify, in environments that support user interactivity, the user agent shall provide controls to allow the user to perform a "magnify" operation on the document fragment.

    If a zoomAndPan attribute is assigned to an inner svg element, the zoomAndPan setting on the inner svg element will have no effect on the SVG user agent.

    14.8. Cursors

    Some interactive display environments provide the ability to modify the appearance of the pointer, which is also known as the cursor. Three types of cursors are available:

    The cursor property is used to specify which cursor to use. The cursor property can be used to reference standard built-in cursors by specifying a keyword such as crosshair or a custom cursor. Custom cursors are referenced via a <url> and can point to either an external resource such as a platform-specific cursor file or to a cursor element, which can be used to define a platform-independent cursor.

    14.8.1. The effect of the ‘cursor’ property

    See the CSS Basic User Interface Module Level 3 specification for the definition of cursor. [CSS3UI]

    SVG uses the cursor property to specify the type of cursor to be displayed for the pointing device when it is over a region of an element that is sensitive to pointer events, according to the value of the pointer-events property. SVG extends the definition of cursor from the CSS Basic User Interface Module Level 3 specification as follows:

    14.8.2. The ‘cursor’ element

    The cursor element can be used to define a platform-independent custom cursor. A recommended approach for defining a platform-independent custom cursor is to create a PNG image [PNG] and define a cursor element that references the PNG image and identifies the exact position within the image which is the pointer position (i.e., the hot spot).

    The PNG format is recommended because it supports the ability to define a transparency mask via an alpha channel. If a different image format is used, this format should support the definition of a transparency mask (two options: provide an explicit alpha channel or use a particular pixel color to indicate transparency). If the transparency mask can be determined, the mask defines the shape of the cursor; otherwise, the cursor is an opaque rectangle. Typically, the other pixel information (e.g., the R, G and B channels) defines the colors for those parts of the cursor which are not masked out. Note that cursors usually contain at least two colors so that the cursor can be visible over most backgrounds.

    cursor
    Categories:
    None
    Content model:
    Any number of the following elements, in any order:script, style
    Attributes:
    DOM Interfaces:

    Attribute definitions:

    Name Value Initial value Animatable
    x, y <length> 0 yes
    The x- and y-coordinates of the position in the cursor's coordinate system which represents the precise position that is being pointed to.
    Name Value Initial value Animatable
    href URL [URL] (none) yes
    A URL reference to the file or element which provides the image of the cursor. Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.

    SVG user agents are required to support PNG format images as targets of the href attribute.

    <!doctype html>
    <body>
      <style>
      body,html { cursor: auto; }
      circle { pointer-events: all; stroke: black; fill: yellow; stroke-width: 4px; }
      circle:hover { fill: blue; }
      svg { width: 200px; height: 200px; }
      text { font: 32px sans-serif; text-anchor: middle; }
    
      #test1 { cursor: url(cursor.svg) 8 1, auto; }
      #test2 { cursor: url(#cursor), auto; }
      </style>
      <svg id="test1" viewBox="0 0 200 200">
        <circle cx="100" cy="100" r="75"/>
        <text x="100" y="100">SVG<tspan x="100" dy="1em">cursor</tspan></text>
      </svg>
      <svg id="test2" viewBox="0 0 200 200">
        <cursor id="cursor" xlink:href="cursor.png" x="4" y="0"/>
        <circle cx="100" cy="100" r="75" />
        <text x="100" y="100">PNG<tspan x="100" dy="1em">cursor</tspan></text>
      </svg>
    </body>

    View this example as SVG (SVG-enabled browsers only)

    14.9. Focus

    SVG uses the same focus model as HTML, modified for SVG as described in this section. At most one element in each document is focused at a time; if the document as a whole has system focus, this element becomes the target of all keyboard events.

    When an element is focused, the element matches the CSS :focus pseudo-class. Interactive user agents must visually indicate focus (usually with an outline) when the focus changes because of a user input event from the keyboard or other non-pointing device and may indicate focus at all times. Authors may use the :focus pseudo-class to replace the visual indication with one more suitable to the graphic, (such as a stroke on a shape) but should not use it to remove visual indications of focus completely.

    The following SVG elements are focusable in an interactive document. Any instance of such an element in a use-element shadow tree is also focusable. For the purpose of the HTML focus model, interactive user agents must treat them as focusable areas whose tabindex focus flag should be set:

    In the case of user-agent supplied controls, the element may have more than one focusable area, for each sub-control.

    In addition, all a elements that are valid links are focusable, and their tabindex focus flag must be set unless the user agent normally provides an alternative method of keyboard traversal of links.

    For compatibility with content that used the SVG Tiny 1.2 focusable attribute, user agents should treat an element with a value of true for that attribute as focusable. In new content, authors should either omit the focusable attribute or use it only in combination with a corresponding tabindex value of 0.

    User agents may treat other elements as focusable, particularly if keyboard interaction is the only or primary means of user input. In particular, user agents may support using keyboard focus to reveal title element text as tooltips, and may allow focus to reach elements which have been assigned listeners for mouse, pointer, or focus events. Authors should not rely on this behavior; all interactive elements should directly support keyboard interaction.

    The sequential focus order is generated from the set of all focusable elements, processing tabindex attributes on SVG elements in the same way as tabindex attributes on HTML elements. Content within a use-element shadow tree is inserted in the focus order as if it was child content of the use element.

    A non-rendered element can never receive focus, regardless of the value of the tabindex attribute, If a script programmatically assigns focus to a non-rendered or otherwise un-focusable element, the focusing call is aborted. Note, however, that an element that is not visible or onscreen may still be rendered.

    When the user agent supports scrolling or panning of the SVG document, and focus moves to an element that is currently outside the SVG viewport, the user agent should scroll or pan the document until the focused element is within the SVG viewport.

    As in HTML, an SVG element that is focusable but does not have a defined activation behavior has an activation behaviour that does nothing (unless a script specifically responds to it).

    This means that an element that is only focusable because of its tabindex attribute will fire a click event in response to a non-mouse activation (e.g. hitting the "enter" key while the element has focus).

    For documents that contain a mix of inline HTML and SVG, focus is handled for the document as a whole (with a combined sequential focus order), not with each inline SVG or HTML fragment as an isolated subdocument.

    For example, in the following document, pressing Tab would cycle the focus between elements A, B and C, in that order.

    <!DOCTYPE html>
    <button id="A" tabindex="1">First thing</button>
    <button id="C" tabindex="2">Third thing</button>
    <svg width="200" height="200">
      <text id="B" tabindex="1" x="100" y="100">Second thing</text>
    </svg>

    Note that SVG elements do not have an equivalent of HTML's accesskey attribute.

    14.10. Event attributes

    event attribute
    An event attribute always has a name that starts with "on" followed by the name of the event for which it is intended. It specifies some script to run when the event of the given type is dispatched to the element on which the attribute is specified.

    For every event type that the user agent supports, SVG supports that as an event attribute, following the same requirements as for event handler content attributes [HTML]. The event attributes are available on all SVG elements.

    The contents of event attributes are always interpreted as ECMAScript, as if processed with the media type 'application/ecmascript'. [RFC2046][RFC4329]

    Event attributes are not animatable.

    14.10.1. Animation event attributes

    Below are the definitions for the animation event attributes. These can be specified on the animation elements.

    Attribute definitions:

    Name Value Initial value Animatable
    onbegin, onend, onrepeat (see below) (none) no
    Specifies some script to execute when "bubbling" or "at target" phase listeners for the corresponding event are fired on the element the attribute is specified on. See supported events table to determine which event each of these event attributes corresponds to. There are no restrictions on the values of this attribute.

    14.11. The ‘script’ element

    SVG 2 Requirement: Consider allowing async/defer on script.
    Resolution: SVG 2 will allow async/defer on ‘script’.
    Purpose: To align with HTML.
    Owner: Cameron (ACTION-3280)
    SVG 2 Requirement: Incorporate SVG Tiny 1.2 script processing model.
    Resolution: SVG 2 will define how inline scriptable content will be processed, in a compatible way to HTML5
    Purpose: To have consistent script running behavior across HTML and SVG.
    Owner: Cameron (ACTION-3282)

    A script element is equivalent to the script element in HTML and thus is the place for scripts (e.g., ECMAScript). Any functions defined within any script element have a "global" scope across the entire current document.

    The script's text content is never directly rendered; the display value for the script element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.

    Before attempting to execute the script element the resolved media type value for type must be inspected. If the SVG user agent does not support the scripting language then the script element must not be executed.

    This example defines a function circle_click which is called by the onclick event attribute on the circle element. The drawing below on the left is the initial image. The drawing below on the right shows the result after clicking on the circle.

      <?xml version="1.0" standalone="no"?>
      <svg width="6cm" height="5cm" viewBox="0 0 600 500"
           xmlns="http://www.w3.org/2000/svg">
        <desc>Example script01 - invoke an ECMAScript function from an onclick event
        </desc>
        <!-- ECMAScript to change the radius with each click -->
        <script type="application/ecmascript"> <![CDATA[
          function circle_click(evt) {
            var circle = evt.target;
            var currentRadius = circle.getAttribute("r");
            if (currentRadius == 100)
              circle.setAttribute("r", currentRadius*2);
            else
              circle.setAttribute("r", currentRadius*0.5);
          }
        ]]> </script>
    
        <!-- Outline the drawing area with a blue line -->
        <rect x="1" y="1" width="598" height="498" fill="none" stroke="blue"/>
    
        <!-- Act on each click event -->
        <circle onclick="circle_click(evt)" cx="300" cy="225" r="100"
                fill="red"/>
    
        <text x="300" y="480"
              font-family="Verdana" font-size="35" text-anchor="middle">
    
          Click on circle to change its size
        </text>
      </svg>
      
    An example demonstrating the effect of the onclick event handler on an SVG shape.
    An example demonstrating how to invoke an ECMAScript function from an onclick event — before first click  An example demonstrating how to invoke an ECMAScript function from an onclick event — after first click

    View this example as SVG (SVG-enabled browsers only)

    script
    Categories:
    Never-rendered element, structurally external element
    Content model:
    Character data.
    Attributes:
    DOM Interfaces:

    Attribute definitions:

    Name Value Initial value Animatable
    crossorigin [ anonymous | use-credentials ]? (see HTML definition of attribute) yes

    The crossorigin attribute is a CORS settings attribute, and unless otherwise specified follows the same processing rules as in html [HTML].

    Name Value Initial value Animatable
    type (see below) application/ecmascript no
    Identifies the scripting language for the given script element. The value must be a valid media type, per Multipurpose Internet Mail Extensions (MIME) Part Two [RFC2046]. If a type is not provided, then the default scripting language assumed is ECMAScript, as if processed with the ‘application/ecmascript’ media type.
    Name Value Initial value Animatable
    href URL [URL] (none) no
    An URL reference to an external resource containing the script code. Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.

    The URL is processed and the resource is fetched as described in the Linking chapter.

    14.12. DOM interfaces

    14.12.1. Interface SVGCursorElement

    An SVGCursorElement object represents a cursor element in the DOM.

    interface SVGCursorElement : SVGElement {
      [SameObject] readonly attribute SVGAnimatedLength x;
      [SameObject] readonly attribute SVGAnimatedLength y;
    };
    
    SVGCursorElement implements SVGURIReference;

    The x and y IDL attributes reflect the x and y content attributes.

    14.12.2. Interface SVGScriptElement

    An SVGScriptElement object represents a script element in the DOM.

    interface SVGScriptElement : SVGElement {
      attribute DOMString type;
      attribute DOMString? crossOrigin;
    };
    
    SVGScriptElement implements SVGURIReference;

    The type IDL attribute reflects the type content attribute.

    The crossOrigin IDL attribute reflects the crossorigin content attribute.

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Chapter 15: Linking

    15.1. References

    15.1.1. Overview

    On the Internet, resources are identified using URLs (Internationalized Resource Identifiers). For example, an SVG file called someDrawing.svg located at http://example.com might have the following URL:

    http://example.com/someDrawing.svg
    

    An URL can also address a particular element within an XML document by including an URL fragment identifier as part of the URL. An URL which includes an URL fragment identifier consists of an optional base URL, followed by a "#" character, followed by the URL fragment identifier. For example, the following URL can be used to specify the element whose ID is "Lamppost" within file someDrawing.svg:

    http://example.com/someDrawing.svg#Lamppost
    

    15.1.2. Definitions

    URL reference
    An URL reference is an Internationalized Resource Identifier, as defined in Internationalized Resource Identifiers [RFC3987]. See References and References and the ‘defs’ element.
    URL reference with fragment identifier
    An Internationalized Resource Identifier [RFC3987] that can include an <absoluteURL> or <relativeURL> and a identifier of the fragment in that resource. See References and the ‘defs’ element. URL reference with fragment identifiers are commonly used to reference paint servers.
    same-document URL reference
    A URL reference with fragment identifier where the non-fragment part of the URL refers to the current document.
    circular reference
    URL references that directly or indirectly reference themselves are treated as invalid circular references. What constitutes a circular reference will depend on how the referenced resource is used, and may include a reference to an ancestor of the current element.
    unresolved reference
    A reference that is still being processed, and has not yet resulted in either an error or an identified resource.
    invalid reference

    Any of the following are invalid references:

    • A circular reference.
    • A URL reference that results in an error during processing.
    • A URL reference that cannot be resolved.
    • A URL references to elements which are inappropriate targets for the given reference shall be treated as invalid references (see Valid URL targets for appropriate targets). For example, the clip-path property can only refer to clipPath elements. The property setting clip-path:url(#MyElement) is an invalid reference if the referenced element is not a clipPath.

    Invalid references may or may not be an error (see Error processing), depending on whether the referencing property or attribute defines fallback behavior.

    15.1.3. URLs and URIs

    Internationalized Resource Identifiers (URLs) are a more generalized complement to Uniform Resource Identifiers (URIs). An URL is a sequence of characters from the Universal Character Set [UNICODE]. A URI is constructed from a much more restricted set of characters. All URIs are already conformant URLs. A mapping from URLs to URIs is defined by the URL specification, which means that URLs can be used instead of URIs in XML documents, to identify resources. URLs can be converted to URIs for resolution on a network, if the protocol does not support URLs directly.

    Previous versions of SVG, following XLink, defined an URL reference type as a URI or as a sequence of characters which must result in an URL after a particular escaping procedure was applied. The escaping procedure was repeated in the XLink 1.0 specification [XLINK], and in the W3C XML Schema Part 2: Datatypes specification [SCHEMA2]. This copying introduced the possibility of error and divergence, but was done because the URL specification was not yet standardized.

    In this specification, the correct term URL is used for this "URI or sequence of characters plus an algorithm" and the escaping method, which turns URLs into URIs, is defined by reference to the URL specification [RFC3987], which has since become an IETF Proposed Standard. Other W3C specifications are expected to be revised over time to remove these duplicate descriptions of the escaping procedure and to refer to URL directly.

    15.1.4. Syntactic forms: URL and <url>

    In SVG, most structural relationships between two elements are specified using a URL value in an ‘href’ attribute. However, many presentation attributes allow both URLs and text strings as content. To disambiguate a text string from a relative URL, the <url> production is used for presentation attributes, and their corresponding CSS properties [CSS3VALUES]. This is simply a URL delimited with a functional notation.

    SVG makes extensive use of URL references, both absolute and relative, to other objects. For example, a linearGradient element may be based on another gradient element, so that only the differences between the two need to be specified, by referencing the source gradient with a URL in the href attribute:

    <linearGradient id="SourceGradient">...</linearGradient>
    <linearGradient id="MyGradient"
                    href="#SourceGradient">...</linearGradient>

    To fill a rectangle with that gradient, you use a URL reference to the linear gradient element as the value of the fill property for the rectangle, as in the following example:

    <rect fill="url(#MyGradient)"/>

    15.1.5. URL reference attributes

    URL references are normally specified with an ‘href’ attribute. The value of this attribute forms a reference for the desired resource (or secondary resource, if there is a fragment identifier). The value of the ‘href’ attribute must be a URL.

    Because it is impractical for any application to check that a value is an URL reference, this specification follows the lead of the URL Specification in this matter and imposes no such conformance testing requirement on SVG authoring tools. An invalid URL does not make an SVG document non-conforming. SVG user agents are only required to process URLs when needed, as specified in Processing of URL references.

    15.1.6. Deprecated XLink URL reference attributes

    In previous versions of SVG, the ‘href’ attribute was specified in the XLink namespace [XLINK] namespace. This usage is now deprecated and instead URL references should be specified using the ‘href’ attribute without a namespace.

    For backwards compatibility, the deprecated xlink:href attribute is defined below along with the xlink:title attribute which has also been deprecated.

    Attribute definitions:

    Name Value Initial value Animatable
    xlink:href URL [URL] (none) (see below)

    For backwards compatibility, elements with an ‘href’ attribute also recognize an ‘href’ attribute in the XLink namespace [XLINK].

    When the ‘href’ attribute is present in both the XLink namespace and without a namespace, the value of the attribute without a namespace shall be used. The attribute in the XLink namespace shall be ignored.

    A Conforming SVG Generator must generate ‘href’ attributes without a namespace. However, it may also generate ‘href’ attributes in the XLink namespace to provide backwards compatibility.

    This attribute is Animatable if and only if the corresponding ‘href’ attribute is defined to be animatable.

    Name Value Initial value Animatable
    xlink:title <anything> (none) no

    Deprecated attribute to describe the meaning of a link or resource in a human-readable fashion. New content should use a ‘title’ child element rather than a ‘xlink:title’ attribute.

    The use of this information is highly dependent on the type of processing being done. It may be used, for example, to make titles available to applications used by visually impaired users, or to create a table of links, or to present help text that appears when a user lets a mouse pointer hover over a starting resource.

    The ‘title’ attribute, if used, must be in the XLink namespace. Refer to the XML Linking Language (XLink) [XLINK].

    When using the deprecated XLink attributes xlink:href or xlink:title an explicit XLink namespace declaration must be provided [XML-NS], One simple way to provide such an XLink namespace declaration is to include an ‘xmlns’ attribute for the XLink namespace on the svg element for content that uses XLink attributes. For example:

    <svg xmlns:xlink="http://www.w3.org/1999/xlink" ...>
      <image xlink:href="foo.png" .../>
    </svg>
    

    15.1.7. Processing of URL references

    URLs are processed to identify a resource at the time they are needed, as follows:

    Legacy xlink:href attributes are processed at the time a corresponding href attribute would be processed, but only if no such href attribute exists on the element.

    Processing a URL involves three steps: generating the absolute URL; fetching the document (if required); identifying the target element (if required).

    A URL reference is unresolved until processing either results in an invalid reference or in the identification of the target resource. Unresolved references in the non-presentation attributes of structurally external elements prevent the load eventfrom firing. User agents may place time limits on the resolution of references that are not same-document URL references, after which the reference is treated as a network error (and therefore as an invalid reference).

    For same-document URL references in a dynamic document, modifications or animations of attributes or properties, or removal of elements from the DOM, may cause an URL reference to return to the unresolved state. The user agent must once again attempt to resolve the URI to identify the referenced resource.

    15.1.7.1. Generating the absolute URL

    If the URL reference is relative, its absolute version must be computed before use. The absolute URL should be generated using one of the following methods:

    The ‘xml:base’ attribute will only have an effect in XML documents; this includes SVG documents and XHTML documents but not HTML documents that are not XML. In contrast, a base element affects relative URLs in any SVG or HTML document, by altering the document base URL.

    If the protocol, such as HTTP, does not support URLs directly, the URL must be converted to a URI by the user agent, as described in section 3.1 of the URL specification [RFC3987].

    After generating the absolute URL:

    As defined in CSS Values and Units, a fragment-only URL in a style property must be treated as a same-document URL reference, regardless of the file in which the property was declared.

    15.1.7.2. Fetching the document

    SVG properties and attributes may reference other documents. When processing such a URL, the user agent should fetch the referenced document as described in this section, except under the following conditions:

    When fetching external resources, user agents must use a potentially CORS-enabled request as defined in HTML [HTML] with the corsAttributeState as follows:

    base

    The request's origin is computed using the same rules as HTML, with an SVG script element treated like an HTML script element, and an SVG image element treated like an HTML img element. The default origin behaviour must be set to taint.

    A future SVG specification may enable CORS references on other SVG elements with href attributes.

    If the fetching algorithm results in an error or an empty response body, the reference URL is treated as an invalid reference.

    If a valid response is returned, and the valid URL targets for the reference include specific element types, the user agent must continue by Processing the subresource document. Otherwise (if only entire-document the URL references are valid), then the fetched document is the referenced resource.

    15.1.7.3. Processing the subresource document

    Otherwise, the subresource must be parsed to identify the target element. If the fetched document is a type that the user agent can parse to create a document object model, it must process it in secure static mode (meaning, do not fetch any additional external resources and do not run scripts or play animations or video). The document model generated for an external subresource reference must be immutable (read-only) and cannot be modified.

    If a document object model can be generated from the fetched file, processing the URL must continue as indicated in Identifying the target element with the parsed subresource document as the referenced document. The user agent may commence the target-identification process prior to completely parsing the document.

    User agents may maintain a list of external resource URLs and their associated parsed documents, and may re-use the documents for subsequent references, so long as doing so does not violate the processing mode, caching, and CORS requirements on the resource.

    15.1.7.4. Identifying the target element

    For URL references to a specific element, whether the reference is valid depends on whether the element can be located within the referenced document and whether it is of an allowed type.

    Using the referenced document identified in previous processing steps (either an external subresource document or the current document), the target element is identified as follows:

    The target element provides the referenced resource if (and only if) it is a valid URL target for the reference.

    15.1.7.5. Valid URL targets

    The valid target element types for href (or xlink:href) attributes are based on the element that has the attribute, as follows:

    The valid target element types for style properties defined in this specification are as follows:

    If the resolved target element type (or document type) is not allowed for the URL reference, it is an invalid reference.

    SVG provides an a element, to indicate links (also known as hyperlinks or Web links). An a element forms a link if it has a href or xlink:href attribute; without these attributes the a element is an inactive placeholder for a link.

    SVG 1.1 defined links in terms of the XLink specification ([XLink]), using attributes defined in the XLink namespace. SVG 2 uses an alternative set of attributes in the default namespace that are consistent with HTML links, and deprecates the XLink attributes.

    The a element may contain any element that its parent may contain, except for another a element; the same element is used for both graphical and textual linked content. Links may not be nested; if an a element is a descendent of another hyperlink element (whether in the SVG namespace or another namespace), user agents must ignore its href attribute and treat it as inactive. The invalid a element must still be rendered as a generic container element.

    The rendering of invalid nested links is at risk, and will likely be synchronized with any decisions regarding the rendering of unknown elements.

    For pointer events processing, a linked hit region is defined for each separate rendered element contained within the a element (according to the value of their pointer-events property), rather than for the bounding box of the a element itself. User agents must also ensure that all links are focusable and can be activated by keyboard commands.

    The remote resource (the destination for the link) is defined by a URL specified by the href attribute on the a element. The remote resource may be any Web resource (e.g., an image, a video clip, a sound bite, a program, another SVG document, an HTML document, an element within the current document, an element within a different document, etc.). In response to user activation of a link (by clicking with the mouse, through keyboard input, voice commands, etc.), user agents should attempt to fetch the specified resource document and either display it or make it available as a downloaded file.

    Example link01 assigns a link to an ellipse.

    <?xml version="1.0" standalone="no"?>
    <svg width="5cm" height="3cm" viewBox="0 0 5 3" version="1.1"
         xmlns="http://www.w3.org/2000/svg">
      <desc>Example link01 - a link on an ellipse
      </desc>
      <rect x=".01" y=".01" width="4.98" height="2.98" 
            fill="none" stroke="blue"  stroke-width=".03"/>
      <a href="http://www.w3.org">
        <ellipse cx="2.5" cy="1.5" rx="2" ry="1"
                 fill="red" />
      </a>
    </svg>
    Example link01 — a link on an ellipse

    Example link01

    View this example as SVG (SVG-enabled browsers only)

    If the above SVG file is viewed by a user agent that supports both SVG and HTML, then clicking on the ellipse will cause the current window or frame to be replaced by the W3C home page.

    a
    Categories:
    Container element, renderable element
    Content model:
    Descriptive content, plus any element or text allowed by its parent's content model, except for another a element. If the parent is a switch element, use the content model of the nearest ancestor that isn't a switch.
    Attributes:
    DOM Interfaces:

    Attribute definitions:

    Name Value Initial value Animatable
    href URL [URL] (none) yes
    The location of the referenced object, expressed as an URL reference. Refer to the common handling defined for URL reference attributes.
    Name Value Initial value Animatable
    target _self | _parent | _top | _blank | <XML-Name> _self yes

    This attribute should be used when there are multiple possible targets for the ending resource, such as when the parent document is embedded within an HTML or XHTML document, or is viewed with a tabbed browser. This attribute specifies the name of the browsing context (e.g., a browser tab or an SVG, HTML, or XHTML iframe or object element) into which a document is to be opened when the link is activated:

    _self
    The current SVG image is replaced by the linked content in the same browsing context as the current SVG image.
    _parent
    The immediate parent browsing context of the SVG image is replaced by the linked content, if it exists and can be securely accessed from this document.
    _top
    The content of the full active window or tab is replaced by the linked content, if it exists and can be securely accessed from this document
    _blank
    A new un-named window or tab is requested for the display of the linked content, if this document can securely do so. If the user agent does not support multiple windows/tabs, the result is the same as _top.
    <XML-Name>
    Specifies the name of the browsing context (tab, inline frame, object, etc.) for display of the linked content. If a context with this name already exists, and can be securely accessed from this document, it is re-used, replacing the existing content. If it does not exist, it is created (the same as '_blank', except that it now has a name). The name must be a valid XML Name [XML11], and should not start with an underscore (U+005F LOW LINE character), to meet the requirements of a valid browsing context name from HTML.

    The normative definitions for browsing contexts and security restrictions on navigation actions between browsing contexts is HTML 5 [HTML], specifically the chapter on loading web pages.

    Previous versions of SVG defined the special target value '_replace'. It was never well implemented, and the distinction between '_replace' and '_self' has been made redundant by changes in the HTML definition of browsing contexts. Use '_self' to replace the current SVG document.

    The value '_new' is not a legal value for target. Use '_blank' to open a document in a new tab/window.

    Name Value Initial value Animatable
    download any value (meaning is conveyed by presence or absence of attribute) (none) no
    rel space-separated keyword tokens [HTML] (none) yes
    rev space-separated keyword tokens [HTML] (none) yes
    hreflang A BCP 47 language tag string [HTML] (none) yes
    type A MIME type string [HTML] (none) yes
    These attributes further describe the targetted resource and its relationship to the current document. Allowed values and meaning are as defined for the a element in HTML.

    15.3. Linking into SVG content: URL fragments and SVG views

    Because SVG content often represents a picture or drawing of something, a common need is to link into a particular view of the document, where a view indicates the initial transformations so as to present a closeup of a particular section of the document.

    15.3.1. SVG fragment identifiers

    SVG 2 Requirement: Merge the SVG 1.1 SE text and the SVG Tiny 1.2 text on fragment identifiers link traversal and add media fragments.
    Resolution: SVG 2 will have media fragment identifiers.
    Purpose: To align with Media Fragments URI.
    Owner: Cyril (ACTION-3442)

    To link into a particular view of an SVG document, the URL reference with fragment identifier needs to be a correctly formed SVG fragment identifier. An SVG fragment identifier defines the meaning of the "selector" or "fragment identifier" portion of URLs that locate resources of MIME media type "image/svg+xml".

    An SVG fragment identifier can come in the following forms:

    15.3.2. SVG fragment identifiers definitions

    An SVG fragment identifier is defined as follows:

    SVGFragmentIdentifier ::= BareName *( "&" timesegment ) |
                              SVGViewSpec *( "&" timesegment ) |
                              spacesegment *( "&" timesegment ) |
                              timesegment *( "&" spacesegment )
    
    BareName ::= XML_Name
    SVGViewSpec ::= 'svgView(' SVGViewAttributes ')'
    SVGViewAttributes ::= SVGViewAttribute |
                          SVGViewAttribute ';' SVGViewAttributes
    
    SVGViewAttribute ::= viewBoxSpec |
                         preserveAspectRatioSpec |
                         transformSpec |
                         zoomAndPanSpec
    viewBoxSpec ::= 'viewBox(' ViewBoxParams ')'
    preserveAspectRatioSpec = 'preserveAspectRatio(' AspectParams ')'
    transformSpec ::= 'transform(' TransformParams ')'
    zoomAndPanSpec ::= 'zoomAndPan(' ZoomAndPanParams ')'
    

    where:

    SVG view box parameters are applied in order, as defined in CSS Transforms specification (e.g. SVG view is transformed as defined in ViewBoxParams, then as defined in TransformParams).

    Spaces are allowed in fragment specifications. Commas are used to separate numeric values within an SVG view specification (e.g., #svgView(viewBox(0,0,200,200))) and semicolons are used to separate attributes (e.g., #svgView(viewBox(0,0,200,200);preserveAspectRatio(none))).

    Fragment identifiers may be url-escaped according to the rules defined in CSS Object Model (CSSOM) specification. For example semicolons can be escaped as %3B to allow animating a (semi-colon separated) list of URLs because otherwise the semicolon would be interpreted as a list separator.

    The four types of SVGViewAttribute may occur in any order, but each type may only occur at most one time in a correctly formed SVGViewSpec.

    When a source document performs a link into an SVG document, for example via an HTML anchor element ([HTML4], section 12.2; i.e., <a href=...> element in HTML) or an XLink specification [XLINK], then the SVG fragment identifier specifies the initial view into the SVG document, as follows:

    15.3.3. Predefined views: the ‘view’ element

    The ‘view’ element is defined as follows:

    view
    Categories:
    None
    Content model:
    Any number of the following elements, in any order:script, style
    Attributes:
    DOM Interfaces:

    We have resolved to remove viewTarget attribute.

    Resolution: Paris 2015 F2F Day 3.

    Owner: BogdanBrinza.

    15.4. DOM interfaces

    15.4.1. Interface SVGAElement

    An SVGElement object represents an a element in the DOM.

    interface SVGAElement : SVGGraphicsElement {
      [SameObject] readonly attribute SVGAnimatedString target;
      [SameObject] readonly attribute SVGAnimatedString download;
      [SameObject] readonly attribute SVGAnimatedString rel;
      [SameObject] readonly attribute SVGAnimatedString relList;
      [SameObject] readonly attribute DOMTokenList rev;
      [SameObject] readonly attribute SVGAnimatedString hreflang;
      [SameObject] readonly attribute SVGAnimatedString type;
    };
    
    SVGAElement implements SVGURIReference;
    SVGAElement implements HTMLHyperlinkElementUtils;

    The target, download, rel, rev, hreflang, type, IDL attributes reflect the content attributes of the same name.

    The relList IDL attribute reflects the rel content attribute as a token list.

    15.4.2. Interface SVGViewElement

    An SVGViewElement object represents a view element in the DOM.

    interface SVGViewElement : SVGElement {};
    
    SVGViewElement implements SVGFitToViewBox;
    SVGViewElement implements SVGZoomAndPan;
    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix A: SVG Document Object Model (DOM)

    This appendix is normative.

    SVG 2 Requirement: Improve the DOM.
    Resolution: We will generally improve the SVG DOM for SVG 2.
    Purpose: Help authors use the SVG DOM by making it less Java-oriented.
    Owner: Cameron (ACTION-3273)
    Note: See SVG 2 DOM Wiki page.
    SVG 2 Requirement: Improve the SVG path DOM APIs.
    Resolution: We will improve the SVG path DOM APIs in SVG 2.
    Purpose: Clean up SVGPathSegList interface, and possibly share an API with Canvas.
    Owner: Cameron (no action)

    A.1. SVG DOM overview

    The SVG DOM is defined in terms of Web IDL interfaces. All IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

    The SVG DOM builds upon a number of DOM specifications. In particular:

    All SVG DOM objects that directly correspond to an attribute, e.g. the SVGAnimatedLength ry in an SVGRectElement, are live. This means that any changes made to the attribute are immediately reflected in the corresponding SVG DOM object.

    A.1.1. SVG DOM object initialization

    The SVG DOM allows attributes to be accessed even though they haven't been specified explicitly in the document markup. When this happens an appropriate object is created, initialized and returned. This newly constructed object does not affect rendering until it is modified for the first time. Modifications made to the corresponding attribute are immediately reflected in the object.

    For example, if lineElement.x1.baseVal is accessed and the ‘x1’ attribute was not specified in the document, the returned SVG DOM object would represent the value 0 user units.

    For cases where an attribute has a default value the returned SVG DOM object that must reflect that value, and for all other cases the object is initialized as described below. If a particular SVG DOM interface is not listed below that means that the object initialization shall be done using the values for the objects that the interface contains, e.g DOMString in the case of SVGAnimatedString.

    SVGTextContentElement.textLength
    Initialized with the return-value of getComputedTextLength on the same element.
    DOMString
    Initialized as the empty string ("").
    float
    long
    short
    Initialized as 0.
    boolean
    Initialized as false.
    SVGLength
    Initialized as 0 user units (SVG_LENGTHTYPE_NUMBER).
    SVGLengthList
    SVGNumberList
    SVGPointList
    SVGStringList
    SVGTransformList
    Initialized as the empty list.
    SVGAngle
    Initialized as 0 in unspecified units (SVG_ANGLETYPE_UNSPECIFIED).
    SVGZoomAndPan
    Initialized as 0 (SVG_ZOOMANDPAN_UNKNOWN).
    SVGPreserveAspectRatio
    Initialized as 'xMidYMid meet'.

    A.2. Elements in the SVG DOM

    Every Element object that corresponds to an SVG element (that is, an element with namespace URI "http://www.w3.org/2000/svg" and a local name that is one of the elements defined in this specification) must also implement the DOM interface identified in element definition. For example, in The ‘rect’ element, the SVGRectElement interface is identified. This means that every Element object whose namespace URI is "http://www.w3.org/2000/svg" and whose local name is "rect" must also implement SVGRectElement.

    A.3. Naming conventions

    The SVG DOM follows similar naming conventions to the Document Object Model HTML ([DOM1], chapter 2).

    All names are defined as one or more English words concatenated together to form a single string. Property or method names start with the initial keyword in lowercase, and each subsequent word starts with a capital letter. For example, a property that returns document meta information such as the date the file was created might be named "fileDateCreated". In the ECMAScript binding, properties are exposed as properties of a given object.

    For attributes with the CDATA data type, the case of the return value is that given in the source document.

    A.4. Relationship with DOM Level 3 Events

    The SVG DOM supports select all interfaces defined in, and all the event types from, DOM Level 3 Events [DOM3EVENTS].

    While event listeners can be registered using an addEventListener call on any element in the DOM, the use of event attributes on elements where those attributes are disallowed will not result in their being invoked if the relevant event is dispatched to the element. For example, if the onclick attribute were specified on a title element, its contents would never be run in response to a click event:

    <svg xmlns="http://www.w3.org/2000/svg">
      <title onclick="alert('Hello')">Invalid event attribute</title>
      <script>
        // Find the 'title' element.
        var title = document.getElementsByTagNameNS("http://www.w3.org/2000/svg", "title")[0];
    
        // Create and initialize a 'click' event.
        var event = document.createEvent("MouseEvent");
        event.initMouseEvent("click", true, false, this, 1, 0, 0, 0, 0, false,
                             false, false, false, 0, null);
    
        // Dispatch the event to the 'title' element.  Since onclick="" is not
        // allowed on 'title', the alert will not show.
        title.dispatchEvent(event);
      </script>
    </svg>
    

    See the Attribute Index for details on which elements a given event attribute is allowed to be specified on.

    Implementors may view the setting of event attributes as the creation and registration of an EventListener on the EventTarget. Such event listeners are invoked only for the "bubbling" and "at target" phases, as if false were specified for the useCapture argument to addEventListener. This EventListener behaves in the same manner as any other which may be registered on the EventTarget.

    If the attribute representing the event listener is changed, this may be viewed as the removal of the previously registered EventListener and the registration of a new one. Futhermore, no specification is made as to the order in which event attributes will receive the event with regards to the other EventListeners on the EventTarget.

    In ECMAScript, one way to establish an event listener is to define a function and pass that function to the addEventListener method:

    function myAction1(evt) {
      // process the event
    }
    // ... later ...
    myElement.addEventListener("click", myAction1, false)
    

    In ECMAScript, the character data content of an event attribute becomes the definition of the ECMAScript function which gets invoked in response to the event. As with all registered ECMAScript event listener functions, this function receives an Event object as a parameter, and the name of the Event object is evt. For example, it is possible to write:

    <rect onclick="MyClickHandler(evt)" .../>
    

    which will pass the Event object evt into function MyClickHandler.

    A.5. Relationship with DOM Level 2 CSS

    The section describes the facilities from DOM Level 2 CSS ([DOM2STYLE], chapter 2) that are part of the SVG DOM.

    A.5.1. User agents that support styling with CSS

    For visual media ([CSS21], section 7.3.1), user agents must support all of the required interfaces defined in DOM Level 2 CSS. All of the interfaces that are optional for DOM Level 2 CSS are also optional for user agents implementing the SVG DOM.

    A.6. Invalid values

    If a script sets a DOM attribute to an invalid value (e.g., a negative number for an attribute that requires a non-negative number or an out-of-range value for an enumeration), unless this specification indicates otherwise, no exception shall be raised on setting, but the given document fragment shall become technically in error as described in Error processing.

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix B: IDL Definitions

    This appendix is normative.

    This appendix contains the complete Web IDL for the SVG Document Object Model definitions.

    interface SVGElement : Element {
    
      [SameObject] readonly attribute SVGAnimatedString className;
    
      [SameObject] readonly attribute DOMStringMap dataset;
    
      readonly attribute SVGSVGElement? ownerSVGElement;
      readonly attribute SVGElement? viewportElement;
    
      attribute long tabIndex;
      void focus();
      void blur();
    };
    
    SVGElement implements GlobalEventHandlers;
    SVGElement implements SVGElementInstance;
    
    dictionary SVGBoundingBoxOptions {
      boolean fill = true;
      boolean stroke = false;
      boolean markers = false;
      boolean clipped = false;
    };
    
    interface SVGGraphicsElement : SVGElement {
      [SameObject] readonly attribute SVGAnimatedTransformList transform;
    
      DOMRect getBBox(optional SVGBoundingBoxOptions options);
      DOMMatrix? getCTM();
      DOMMatrix? getScreenCTM();
    };
    
    SVGGraphicsElement implements SVGTests;
    
    interface SVGGeometryElement : SVGGraphicsElement {
      [SameObject] readonly attribute SVGAnimatedNumber pathLength;
    
      boolean isPointInFill(DOMPoint point);
      boolean isPointInStroke(DOMPoint point);
      float getTotalLength();
      DOMPoint getPointAtLength(float distance);
    };
    
    interface SVGNumber {
      attribute float value;
    };
    
    interface SVGLength {
    
      // Length Unit Types
      const unsigned short SVG_LENGTHTYPE_UNKNOWN = 0;
      const unsigned short SVG_LENGTHTYPE_NUMBER = 1;
      const unsigned short SVG_LENGTHTYPE_PERCENTAGE = 2;
      const unsigned short SVG_LENGTHTYPE_EMS = 3;
      const unsigned short SVG_LENGTHTYPE_EXS = 4;
      const unsigned short SVG_LENGTHTYPE_PX = 5;
      const unsigned short SVG_LENGTHTYPE_CM = 6;
      const unsigned short SVG_LENGTHTYPE_MM = 7;
      const unsigned short SVG_LENGTHTYPE_IN = 8;
      const unsigned short SVG_LENGTHTYPE_PT = 9;
      const unsigned short SVG_LENGTHTYPE_PC = 10;
    
      readonly attribute unsigned short unitType;
               attribute float value;
               attribute float valueInSpecifiedUnits;
               attribute DOMString valueAsString;
    
      void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits);
      void convertToSpecifiedUnits(unsigned short unitType);
    };
    
    interface SVGAngle {
    
      // Angle Unit Types
      const unsigned short SVG_ANGLETYPE_UNKNOWN = 0;
      const unsigned short SVG_ANGLETYPE_UNSPECIFIED = 1;
      const unsigned short SVG_ANGLETYPE_DEG = 2;
      const unsigned short SVG_ANGLETYPE_RAD = 3;
      const unsigned short SVG_ANGLETYPE_GRAD = 4;
    
      readonly attribute unsigned short unitType;
               attribute float value;
               attribute float valueInSpecifiedUnits;
               attribute DOMString valueAsString;
    
      void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits);
      void convertToSpecifiedUnits(unsigned short unitType);
    };
    
    interface SVGNumberList {
    
      readonly attribute unsigned long length;
      readonly attribute unsigned long numberOfItems;
    
      void clear();
      SVGNumber initialize(SVGNumber newItem);
      getter SVGNumber getItem(unsigned long index);
      SVGNumber insertItemBefore(SVGNumber newItem, unsigned long index);
      SVGNumber replaceItem(SVGNumber newItem, unsigned long index);
      SVGNumber removeItem(unsigned long index);
      SVGNumber appendItem(SVGNumber newItem);
      setter void (unsigned long index, SVGNumber newItem);
    };
    
    interface SVGLengthList {
    
      readonly attribute unsigned long length;
      readonly attribute unsigned long numberOfItems;
    
      void clear();
      SVGLength initialize(SVGLength newItem);
      getter SVGLength getItem(unsigned long index);
      SVGLength insertItemBefore(SVGLength newItem, unsigned long index);
      SVGLength replaceItem(SVGLength newItem, unsigned long index);
      SVGLength removeItem(unsigned long index);
      SVGLength appendItem(SVGLength newItem);
      setter void (unsigned long index, SVGLength newItem);
    };
    
    interface SVGAnimatedBoolean {
               attribute boolean baseVal;
      readonly attribute boolean animVal;
    };
    
    interface SVGAnimatedEnumeration {
               attribute unsigned short baseVal;
      readonly attribute unsigned short animVal;
    };
    
    interface SVGAnimatedInteger {
               attribute long baseVal;
      readonly attribute long animVal;
    };
    
    interface SVGAnimatedNumber {
               attribute float baseVal;
      readonly attribute float animVal;
    };
    
    interface SVGAnimatedLength {
      [SameObject] readonly attribute SVGLength baseVal;
      [SameObject] readonly attribute SVGLength animVal;
    };
    
    interface SVGAnimatedAngle {
      [SameObject] readonly attribute SVGAngle baseVal;
      [SameObject] readonly attribute SVGAngle animVal;
    };
    
    interface SVGAnimatedString {
               attribute DOMString baseVal;
      readonly attribute DOMString animVal;
    };
    
    interface SVGAnimatedRect {
      [SameObject] readonly attribute DOMRect baseVal;
      [SameObject] readonly attribute DOMRectReadOnly animVal;
    };
    
    interface SVGAnimatedNumberList {
      [SameObject] readonly attribute SVGNumberList baseVal;
      [SameObject] readonly attribute SVGNumberList animVal;
    };
    
    interface SVGAnimatedLengthList {
      [SameObject] readonly attribute SVGLengthList baseVal;
      [SameObject] readonly attribute SVGLengthList animVal;
    };
    
    interface SVGStringList {
    
      readonly attribute unsigned long length;
      readonly attribute unsigned long numberOfItems;
    
      void clear();
      DOMString initialize(DOMString newItem);
      getter DOMString getItem(unsigned long index);
      DOMString insertItemBefore(DOMString newItem, unsigned long index);
      DOMString replaceItem(DOMString newItem, unsigned long index);
      DOMString removeItem(unsigned long index);
      DOMString appendItem(DOMString newItem);
      setter void (unsigned long index, DOMString newItem);
    };
    
    [NoInterfaceObject]
    interface SVGUnitTypes {
      // Unit Types
      const unsigned short SVG_UNIT_TYPE_UNKNOWN = 0;
      const unsigned short SVG_UNIT_TYPE_USERSPACEONUSE = 1;
      const unsigned short SVG_UNIT_TYPE_OBJECTBOUNDINGBOX = 2;
    };
    
    [NoInterfaceObject]
    interface SVGTests {
      [SameObject] readonly attribute SVGStringList requiredExtensions;
      [SameObject] readonly attribute SVGStringList systemLanguage;
    };
    
    [NoInterfaceObject]
    interface SVGFitToViewBox {
      [SameObject] readonly attribute SVGAnimatedRect viewBox;
      [SameObject] readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;
    };
    
    [NoInterfaceObject]
    interface SVGZoomAndPan {
    
      // Zoom and Pan Types
      const unsigned short SVG_ZOOMANDPAN_UNKNOWN = 0;
      const unsigned short SVG_ZOOMANDPAN_DISABLE = 1;
      const unsigned short SVG_ZOOMANDPAN_MAGNIFY = 2;
    
      attribute unsigned short zoomAndPan;
    };
    
    [NoInterfaceObject]
    interface SVGURIReference {
      [SameObject] readonly attribute SVGAnimatedString href;
    };
    
    partial interface Document {
      readonly attribute SVGSVGElement rootElement;
    };
    
    interface SVGSVGElement : SVGGraphicsElement {
    
      [SameObject] readonly attribute SVGAnimatedLength x;
      [SameObject] readonly attribute SVGAnimatedLength y;
      [SameObject] readonly attribute SVGAnimatedLength width;
      [SameObject] readonly attribute SVGAnimatedLength height;
    
      attribute float currentScale;
      [SameObject] readonly attribute DOMPointReadOnly currentTranslate;
    
      NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement? referenceElement);
      NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement? referenceElement);
      boolean checkIntersection(SVGElement element, DOMRectReadOnly rect);
      boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect);
    
      void deselectAll();
    
      SVGNumber createSVGNumber();
      SVGLength createSVGLength();
      SVGAngle createSVGAngle();
      DOMPoint createSVGPoint();
      DOMMatrix createSVGMatrix();
      DOMRect createSVGRect();
      SVGTransform createSVGTransform();
      SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix);
    
      Element getElementById(DOMString elementId);
    
      // Deprecated methods that have no effect when called,
      // but which are kept for compatibility reasons.
      unsigned long suspendRedraw(unsigned long maxWaitMilliseconds);
      void unsuspendRedraw(unsigned long suspendHandleID);
      void unsuspendRedrawAll();
      void forceRedraw();
    };
    
    SVGSVGElement implements SVGFitToViewBox;
    SVGSVGElement implements SVGZoomAndPan;
    SVGSVGElement implements WindowEventHandlers;
    
    interface SVGGElement : SVGGraphicsElement {
    };
    
    interface SVGUnknownElement : SVGGraphicsElement {
    };
    
    interface SVGDefsElement : SVGGraphicsElement {
    };
    
    interface SVGDescElement : SVGElement {
    };
    
    interface SVGMetadataElement : SVGElement {
    };
    
    interface SVGTitleElement : SVGElement {
    };
    
    interface SVGSymbolElement : SVGGraphicsElement {
    };
    
    SVGSymbolElement implements SVGFitToViewBox;
    
    interface SVGUseElement : SVGGraphicsElement {
      [SameObject] readonly attribute SVGAnimatedLength x;
      [SameObject] readonly attribute SVGAnimatedLength y;
      [SameObject] readonly attribute SVGAnimatedLength width;
      [SameObject] readonly attribute SVGAnimatedLength height;
      [SameObject] readonly attribute SVGElement? instanceRoot;
      [SameObject] readonly attribute SVGElement? animatedInstanceRoot;
    };
    
    SVGUseElement implements SVGURIReference;
    
    
    interface SVGElementInstance : ShadowRoot {
    
    };
    
    [NoInterfaceObject]
    interface SVGElementInstance {
      [SameObject] readonly attribute SVGElement? correspondingElement;
      [SameObject] readonly attribute SVGUseElement? correspondingUseElement;
    };
    
    
    [Constructor (Animation source, Animatable newTarget) ]
    interface ShadowAnimation : Animation {
      [SameObject] readonly attribute Animation sourceAnimation;
    };
    
    interface SVGSwitchElement : SVGGraphicsElement {
    };
    
    [NoInterfaceObject]
    interface GetSVGDocument {
      Document getSVGDocument();
    };
    
    interface SVGStyleElement : SVGElement {
      attribute DOMString type;
      attribute DOMString media;
      attribute DOMString title;
    };
    
    SVGStyleElement implements LinkStyle;
    
    interface SVGTransform {
    
      // Transform Types
      const unsigned short SVG_TRANSFORM_UNKNOWN = 0;
      const unsigned short SVG_TRANSFORM_MATRIX = 1;
      const unsigned short SVG_TRANSFORM_TRANSLATE = 2;
      const unsigned short SVG_TRANSFORM_SCALE = 3;
      const unsigned short SVG_TRANSFORM_ROTATE = 4;
      const unsigned short SVG_TRANSFORM_SKEWX = 5;
      const unsigned short SVG_TRANSFORM_SKEWY = 6;
    
      readonly attribute unsigned short type;
      [SameObject] readonly attribute DOMMatrix matrix;
      readonly attribute float angle;
    
      void setMatrix(DOMMatrixReadOnly matrix);
      void setTranslate(float tx, float ty);
      void setScale(float sx, float sy);
      void setRotate(float angle, float cx, float cy);
      void setSkewX(float angle);
      void setSkewY(float angle);
    };
    
    interface SVGTransformList {
    
      readonly attribute unsigned long length;
      readonly attribute unsigned long numberOfItems;
    
      void clear();
      SVGTransform initialize(SVGTransform newItem);
      getter SVGTransform getItem(unsigned long index);
      SVGTransform insertItemBefore(SVGTransform newItem, unsigned long index);
      SVGTransform replaceItem(SVGTransform newItem, unsigned long index);
      SVGTransform removeItem(unsigned long index);
      SVGTransform appendItem(SVGTransform newItem);
      setter void (unsigned long index, SVGTransform newItem);
    
      // Additional methods not common to other list interfaces.
      SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix);
      SVGTransform? consolidate();
    };
    
    interface SVGAnimatedTransformList {
      [SameObject] readonly attribute SVGTransformList baseVal;
      [SameObject] readonly attribute SVGTransformList animVal;
    };
    
    interface SVGPreserveAspectRatio {
    
      // Alignment Types
      const unsigned short SVG_PRESERVEASPECTRATIO_UNKNOWN = 0;
      const unsigned short SVG_PRESERVEASPECTRATIO_NONE = 1;
      const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMIN = 2;
      const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMIN = 3;
      const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMIN = 4;
      const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMID = 5;
      const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMID = 6;
      const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMID = 7;
      const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMAX = 8;
      const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMAX = 9;
      const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMAX = 10;
    
      // Meet-or-slice Types
      const unsigned short SVG_MEETORSLICE_UNKNOWN = 0;
      const unsigned short SVG_MEETORSLICE_MEET = 1;
      const unsigned short SVG_MEETORSLICE_SLICE = 2;
    
      attribute unsigned short align;
      attribute unsigned short meetOrSlice;
    };
    
    interface SVGAnimatedPreserveAspectRatio {
      [SameObject] readonly attribute SVGPreserveAspectRatio baseVal;
      [SameObject] readonly attribute SVGPreserveAspectRatio animVal;
    };
    
    interface SVGPathElement : SVGGeometryElement {
    
    };
    
    interface SVGRectElement : SVGGeometryElement {
      [SameObject] readonly attribute SVGAnimatedLength x;
      [SameObject] readonly attribute SVGAnimatedLength y;
      [SameObject] readonly attribute SVGAnimatedLength width;
      [SameObject] readonly attribute SVGAnimatedLength height;
      [SameObject] readonly attribute SVGAnimatedLength rx;
      [SameObject] readonly attribute SVGAnimatedLength ry;
    };
    
    interface SVGCircleElement : SVGGeometryElement {
      [SameObject] readonly attribute SVGAnimatedLength cx;
      [SameObject] readonly attribute SVGAnimatedLength cy;
      [SameObject] readonly attribute SVGAnimatedLength r;
    };
    
    interface SVGEllipseElement : SVGGeometryElement {
      [SameObject] readonly attribute SVGAnimatedLength cx;
      [SameObject] readonly attribute SVGAnimatedLength cy;
      [SameObject] readonly attribute SVGAnimatedLength rx;
      [SameObject] readonly attribute SVGAnimatedLength ry;
    };
    
    interface SVGLineElement : SVGGeometryElement {
      [SameObject] readonly attribute SVGAnimatedLength x1;
      [SameObject] readonly attribute SVGAnimatedLength y1;
      [SameObject] readonly attribute SVGAnimatedLength x2;
      [SameObject] readonly attribute SVGAnimatedLength y2;
    };
    
    interface SVGMeshElement : SVGGeometryElement {};
    
    SVGMeshElement implements SVGURIReference;
    
    [NoInterfaceObject]
    interface SVGAnimatedPoints {
      [SameObject] readonly attribute SVGPointList points;
      [SameObject] readonly attribute SVGPointList animatedPoints;
    };
    
    interface SVGPointList {
    
      readonly attribute unsigned long length;
      readonly attribute unsigned long numberOfItems;
    
      void clear();
      DOMPoint initialize(DOMPoint newItem);
      getter DOMPoint getItem(unsigned long index);
      DOMPoint insertItemBefore(DOMPoint newItem, unsigned long index);
      DOMPoint replaceItem(DOMPoint newItem, unsigned long index);
      DOMPoint removeItem(unsigned long index);
      DOMPoint appendItem(DOMPoint newItem);
      setter void (unsigned long index, DOMPoint newItem);
    };
    
    interface SVGPolylineElement : SVGGeometryElement {
    };
    
    SVGPolylineElement implements SVGAnimatedPoints;
    
    interface SVGPolygonElement : SVGGeometryElement {
    };
    
    SVGPolygonElement implements SVGAnimatedPoints;
    
    interface SVGTextContentElement : SVGGraphicsElement {
    
      // lengthAdjust Types
      const unsigned short LENGTHADJUST_UNKNOWN = 0;
      const unsigned short LENGTHADJUST_SPACING = 1;
      const unsigned short LENGTHADJUST_SPACINGANDGLYPHS = 2;
    
      [SameObject] readonly attribute SVGAnimatedLength textLength;
      [SameObject] readonly attribute SVGAnimatedEnumeration lengthAdjust;
    
      long getNumberOfChars();
      float getComputedTextLength();
      float getSubStringLength(unsigned long charnum, unsigned long nchars);
      DOMPoint getStartPositionOfChar(unsigned long charnum);
      DOMPoint getEndPositionOfChar(unsigned long charnum);
      DOMRect getExtentOfChar(unsigned long charnum);
      float getRotationOfChar(unsigned long charnum);
      long getCharNumAtPosition(DOMPoint point);
      void selectSubString(unsigned long charnum, unsigned long nchars);
    };
    
    interface SVGTextPositioningElement : SVGTextContentElement {
      [SameObject] readonly attribute SVGAnimatedLengthList x;
      [SameObject] readonly attribute SVGAnimatedLengthList y;
      [SameObject] readonly attribute SVGAnimatedLengthList dx;
      [SameObject] readonly attribute SVGAnimatedLengthList dy;
      [SameObject] readonly attribute SVGAnimatedNumberList rotate;
    };
    
    interface SVGTextElement : SVGTextPositioningElement {
    };
    
    interface SVGTSpanElement : SVGTextPositioningElement {
    };
    
    interface SVGTextPathElement : SVGTextContentElement {
    
      // textPath Method Types
      const unsigned short TEXTPATH_METHODTYPE_UNKNOWN = 0;
      const unsigned short TEXTPATH_METHODTYPE_ALIGN = 1;
      const unsigned short TEXTPATH_METHODTYPE_STRETCH = 2;
    
      // textPath Spacing Types
      const unsigned short TEXTPATH_SPACINGTYPE_UNKNOWN = 0;
      const unsigned short TEXTPATH_SPACINGTYPE_AUTO = 1;
      const unsigned short TEXTPATH_SPACINGTYPE_EXACT = 2;
    
      [SameObject] readonly attribute SVGAnimatedLength startOffset;
      [SameObject] readonly attribute SVGAnimatedEnumeration method;
      [SameObject] readonly attribute SVGAnimatedEnumeration spacing;
    };
    
    SVGTextPathElement implements SVGURIReference;
    
    interface SVGImageElement : SVGGraphicsElement {
      [SameObject] readonly attribute SVGAnimatedLength x;
      [SameObject] readonly attribute SVGAnimatedLength y;
      [SameObject] readonly attribute SVGAnimatedLength width;
      [SameObject] readonly attribute SVGAnimatedLength height;
      [SameObject] readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;
      attribute DOMString? crossOrigin;
    };
    
    SVGImageElement implements SVGURIReference;
    
    interface SVGForeignObjectElement : SVGGraphicsElement {
      [SameObject] readonly attribute SVGAnimatedLength x;
      [SameObject] readonly attribute SVGAnimatedLength y;
      [SameObject] readonly attribute SVGAnimatedLength width;
      [SameObject] readonly attribute SVGAnimatedLength height;
    };
    
    interface SVGMarkerElement : SVGElement {
    
      // Marker Unit Types
      const unsigned short SVG_MARKERUNITS_UNKNOWN = 0;
      const unsigned short SVG_MARKERUNITS_USERSPACEONUSE = 1;
      const unsigned short SVG_MARKERUNITS_STROKEWIDTH = 2;
    
      // Marker Orientation Types
      const unsigned short SVG_MARKER_ORIENT_UNKNOWN = 0;
      const unsigned short SVG_MARKER_ORIENT_AUTO = 1;
      const unsigned short SVG_MARKER_ORIENT_ANGLE = 2;
    
      [SameObject] readonly attribute SVGAnimatedLength refX;
      [SameObject] readonly attribute SVGAnimatedLength refY;
      [SameObject] readonly attribute SVGAnimatedEnumeration markerUnits;
      [SameObject] readonly attribute SVGAnimatedLength markerWidth;
      [SameObject] readonly attribute SVGAnimatedLength markerHeight;
      [SameObject] readonly attribute SVGAnimatedEnumeration orientType;
      [SameObject] readonly attribute SVGAnimatedAngle orientAngle;
      attribute DOMString orient;
    
      void setOrientToAuto();
      void setOrientToAngle(SVGAngle angle);
    };
    
    SVGMarkerElement implements SVGFitToViewBox;
    
    interface SVGSolidcolorElement : SVGElement {
    };
    
    interface SVGGradientElement : SVGElement {
    
      // Spread Method Types
      const unsigned short SVG_SPREADMETHOD_UNKNOWN = 0;
      const unsigned short SVG_SPREADMETHOD_PAD = 1;
      const unsigned short SVG_SPREADMETHOD_REFLECT = 2;
      const unsigned short SVG_SPREADMETHOD_REPEAT = 3;
    
      [SameObject] readonly attribute SVGAnimatedEnumeration gradientUnits;
      [SameObject] readonly attribute SVGAnimatedTransformList gradientTransform;
      [SameObject] readonly attribute SVGAnimatedEnumeration spreadMethod;
    };
    
    SVGGradientElement implements SVGURIReference;
    SVGGradientElement implements SVGUnitTypes;
    
    interface SVGLinearGradientElement : SVGGradientElement {
      [SameObject] readonly attribute SVGAnimatedLength x1;
      [SameObject] readonly attribute SVGAnimatedLength y1;
      [SameObject] readonly attribute SVGAnimatedLength x2;
      [SameObject] readonly attribute SVGAnimatedLength y2;
    };
    
    interface SVGRadialGradientElement : SVGGradientElement {
      [SameObject] readonly attribute SVGAnimatedLength cx;
      [SameObject] readonly attribute SVGAnimatedLength cy;
      [SameObject] readonly attribute SVGAnimatedLength r;
      [SameObject] readonly attribute SVGAnimatedLength fx;
      [SameObject] readonly attribute SVGAnimatedLength fy;
      [SameObject] readonly attribute SVGAnimatedLength fr;
    };
    
    interface SVGMeshGradientElement : SVGGradientElement {
    };
    
    interface SVGMeshrowElement : SVGElement {
    };
    
    interface SVGMeshpatchElement : SVGElement {
    };
    
    interface SVGStopElement : SVGElement {
      [SameObject] readonly attribute SVGAnimatedNumber offset;
    };
    
    interface SVGPatternElement : SVGElement {
      [SameObject] readonly attribute SVGAnimatedEnumeration patternUnits;
      [SameObject] readonly attribute SVGAnimatedEnumeration patternContentUnits;
      [SameObject] readonly attribute SVGAnimatedTransformList patternTransform;
      [SameObject] readonly attribute SVGAnimatedLength x;
      [SameObject] readonly attribute SVGAnimatedLength y;
      [SameObject] readonly attribute SVGAnimatedLength width;
      [SameObject] readonly attribute SVGAnimatedLength height;
    };
    
    SVGPatternElement implements SVGFitToViewBox;
    SVGPatternElement implements SVGURIReference;
    SVGPatternElement implements SVGUnitTypes;
    
    interface SVGHatchElement : SVGElement {
    };
    
    interface SVGHatchpathElement : SVGElement {
    };
    
    interface SVGCursorElement : SVGElement {
      [SameObject] readonly attribute SVGAnimatedLength x;
      [SameObject] readonly attribute SVGAnimatedLength y;
    };
    
    SVGCursorElement implements SVGURIReference;
    
    interface SVGScriptElement : SVGElement {
      attribute DOMString type;
      attribute DOMString? crossOrigin;
    };
    
    SVGScriptElement implements SVGURIReference;
    
    interface SVGAElement : SVGGraphicsElement {
      [SameObject] readonly attribute SVGAnimatedString target;
      [SameObject] readonly attribute SVGAnimatedString download;
      [SameObject] readonly attribute SVGAnimatedString rel;
      [SameObject] readonly attribute SVGAnimatedString relList;
      [SameObject] readonly attribute DOMTokenList rev;
      [SameObject] readonly attribute SVGAnimatedString hreflang;
      [SameObject] readonly attribute SVGAnimatedString type;
    };
    
    SVGAElement implements SVGURIReference;
    SVGAElement implements HTMLHyperlinkElementUtils;
    
    interface SVGViewElement : SVGElement {};
    
    SVGViewElement implements SVGFitToViewBox;
    SVGViewElement implements SVGZoomAndPan;
    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix C: Implementation Requirements

    This appendix is normative.

    C.1. Introduction

    The following are notes about implementation requirements corresponding to various features in the SVG language.

    C.2. Error processing

    There are various scenarios where an SVG document fragment is technically in error:

    A document can go in and out of error over time. For example, document changes from the SVG DOM or from animation can cause a document to become in error and a further change can cause the document to become correct again.

    The following error processing shall occur when a document is in error:

    Because of situations where a block of scripting changes might cause a given SVG document fragment to go into and out of error, error processing shall occur only at times when document presentation (e.g., rendering to the display device) is updated.

    C.3. Clamping values which are restricted to a particular range

    Some numeric attribute and property values have restricted ranges, such as color component values. When out-of-range values are provided, the user agent shall defer any error checking until after presentation time, as composited actions might produce intermediate values which are out-of-range but final values which are within range.

    Color values are not in error if they are out-of-range, even if final computations produce an out-of-range color value at presentation time. It is recommended that user agents clamp color values to the nearest color value (possibly determined by simple clipping) which the system can process as late as possible (e.g., presentation time), although it is acceptable for user agents to clamp color values as early as parse time. Thus, implementation dependencies might preclude consistent behavior across different systems when out-of-range color values are used.

    Opacity values out-of-range are not in error and should be clamped to the range 0 to 1 at the time which opacity values have to be processed (e.g., at presentation time or when it is necessary to perform intermediate filter effect calculations).

    C.4. Elliptical arc implementation notes

    C.4.1. Elliptical arc syntax

    An elliptical arc is a particular path command. As such, it is described by the following parameters in order:

    (x1y1) are the absolute coordinates of the current point on the path, obtained from the last two parameters of the previous path command.

    rx and ry are the radii of the ellipse (also known as its semi-major and semi-minor axes).

    φ is the angle from the x-axis of the current coordinate system to the x-axis of the ellipse.

    fA is the large arc flag, and is 0 if an arc spanning less than or equal to 180 degrees is chosen, or 1 if an arc spanning greater than 180 degrees is chosen.

    fS is the sweep flag, and is 0 if the line joining center to arc sweeps through decreasing angles, or 1 if it sweeps through increasing angles.

    (x2y2) are the absolute coordinates of the final point of the arc.

    This parameterization of elliptical arcs will be referred to as endpoint parameterization. One of the advantages of endpoint parameterization is that it permits a consistent path syntax in which all path commands end in the coordinates of the new "current point". The following notes give rules and formulas to help implementers deal with endpoint parameterization.

    C.4.2. Out-of-range parameters

    Arbitrary numerical values are permitted for all elliptical arc parameters, but where these values are invalid or out-of-range, an implementation must make sense of them as follows:

    If the endpoints (x1y1) and (x2y2) are identical, then this is equivalent to omitting the elliptical arc segment entirely.

    If rx = 0 or ry = 0 then this arc is treated as a straight line segment (a "lineto") joining the endpoints.

    If rx or ry have negative signs, these are dropped; the absolute value is used instead.

    If rx, ry and φ are such that there is no solution (basically, the ellipse is not big enough to reach from (x1y1) to (x2y2)) then the ellipse is scaled up uniformly until there is exactly one solution (until the ellipse is just big enough).

    φ is taken mod 360 degrees.

    Any nonzero value for either of the flags fA or fS is taken to mean the value 1.

    This forgiving yet consistent treatment of out-of-range values ensures that:

    C.4.3. Parameterization alternatives

    An arbitrary point (xy) on the elliptical arc can be described by the 2-dimensional matrix equation:

    (F.6.3.1)
    ( x y ) = ( cosφ -sinφ sinφ cosφ ) · ( rxcosθ rysinθ ) + ( cx cy )
        x = rx*cos(θ)*cos(φ) - ry*sin(θ)*sin(φ) + cx
        y = rx*cos(θ)*sin(φ) + ry*sin(θ)*cos(φ) + cy
      

    (cxcy) are the coordinates of the center of the ellipse.

    rx and ry are the radii of the ellipse (also known as its semi-major and semi-minor axes).

    φ is the angle from the x-axis of the current coordinate system to the x-axis of the ellipse.

    θ is the angle around the arc that the point (xy) lies at, and ranges from:

    • θ1 which is the start angle of the elliptical arc prior to the stretch and rotate operations.
    • θ2 which is the end angle of the elliptical arc prior to the stretch and rotate operations.
    • Δθ which is the difference between these two angles.

    If one thinks of an ellipse as a circle that has been stretched and then rotated, then θ1, θ2 and Δθ are the start angle, end angle and sweep angle, respectively of the arc prior to the stretch and rotate operations. This leads to an alternate parameterization which is common among graphics APIs, which will be referred to as center parameterization. In the next sections, formulas are given for mapping in both directions between center parameterization and endpoint parameterization.

    C.4.4. Conversion from center to endpoint parameterization

    Given the following variables:

    cx cy rx ry φ θ1 Δθ

    the task is to find:

    x1 y1 x2 y2 fA fS

    This can be achieved using the following formulas:

    x 1 y 1 = cos φ - sin φ sin φ cos φ r x   cos θ 1 r y   sin θ 1 + c x c y
    (F.6.4.1)
    x 2 y 2 = cos φ - sin φ sin φ cos φ r x   cos θ 1 + Δ θ r y   sin θ 1 + Δ θ + c x c y
    (F.6.4.2)
    f A = 1     if     Δ θ > 180 ° 0     if     Δ θ 180 °
    (F.6.4.3)
    f S = 1    if    Δ θ   >   0 ° 0    if    Δ θ   <   0 °
    (F.6.4.4)

    C.4.5. Conversion from endpoint to center parameterization

    Given the following variables:

    x1 y1 x2 y2 fA fS rx ry φ

    the task is to find:

    cx cy θ1 Δθ

    The equations simplify after a translation which places the origin at the midpoint of the line joining (x1y1) to (x2y2), followed by a rotation to line up the coordinate axes with the axes of the ellipse. All transformed coordinates will be written with primes. They are computed as intermediate values on the way toward finding the required center parameterization variables. This procedure consists of the following steps:

    C.4.6. Correction of out-of-range radii

    This section formalizes the adjustments to out-of-range rx and ry mentioned in F.6.2. Algorithmically these adjustments consist of the following steps:

    C.5. Text selection implementation notes

    The following implementation notes describe the algorithm for deciding which characters are selected during a text selection operation.

    As the text selection operation occurs (e.g., while the user clicks and drags the mouse to identify the selection), the user agent determines a start selection position and an end selection position, each of which represents a position in the text string between two characters. After determining start selection position and end selection position, the user agent selects the appropriate characters, where the resulting text selection consists of either:

    On systems with pointer devices, to determine the start selection position, the SVG user agent determines which boundary between characters corresponding to rendered glyphs is the best target (e.g., closest) based on the current pointer location at the time of the event that initiates the selection operation (e.g., the mouse down event). The user agent then tracks the completion of the selection operation (e.g., the mouse drag, followed ultimately by the mouse up). At the end of the selection operation, the user agent determines which boundary between characters is the best target (e.g., closest) for the end selection position.

    If no character reordering has occurred due to bidirectionality, then the selection consists of all characters between the start selection position and end selection position. For example, if a text element contains the string "abcdef" and the start selection position and end selection positions are 0 and 3 respectively (assuming the left side of the "a" is position zero), then the selection will consist of "abc".

    When the user agent is implementing selection of bidirectional text, and when the selection starts (or ends) between characters which are not contiguous in logical order, then there might be multiple potential combinations of characters that can be considered part of the selection. The algorithms to choose among the combinations of potential selection options shall choose the selection option which most closely matches the text string's visual rendering order.

    When multiple characters map inseparably to a given set of one or more glyphs, the user agent can either disallow the selection to start in the middle of the glyph set or can attempt to allocate portions of the area taken up by the glyph set to the characters that correspond to the glyph.

    For systems which support pointer devices such as a mouse, the user agent is required to provide a mechanism for selecting text even when the given text has associated event handlers or links, which might block text selection due to event processing precedence rules (see Pointer events). One implementation option: For platforms which support a pointer device such as a mouse, the user agent may provide for a small additional region around character cells which initiates text selection operations but does not initiate event handlers or links.

    C.6. Printing implementation notes

    For user agents which support both zooming on display devices and printing, it is recommended that the default printing option produce printed output that reflects the display device's current view of the current SVG document fragment (assuming there is no media-specific styling), taking into account any zooming and panning done by the user, the current state of animation, and any document changes due to DOM and scripting. Thus, if the user zooms into a particular area of a map on the display device and then requests a hardcopy, the hardcopy should show the same view of the map as appears on the display device. If a user pauses an animation and prints, the hardcopy should show the same graphics as the currently paused picture on the display device. If scripting has added or removed elements from the document, then the hardcopy should reflect the same changes that would be reflected on the display.

    When an SVG document is rendered on a static-only device such as a printer which does not support SVG's animation and scripting and facilities, then the user agent shall ignore any animation and scripting elements in the document and render the remaining graphics elements according to the rules in this specification.

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix D: Conformance Criteria

    This appendix is normative.

    D.1. Introduction

    In order to ensure that SVG-family documents are maximally portable among SVG-family user agents, this specification rigidly defines conformance requirements for both, as well as for SVG-family document types. While the conformance definitions can be found in this appendix, they necessarily reference normative text within this document and within other related specifications. It is only possible to fully comprehend the conformance requirements of SVG through a complete reading of all normative references.

    D.2. Conforming SVG Document Fragments

    An SVG document fragment is a Conforming SVG Document Fragment if it adheres to the specification described in this document (Scalable Vector Graphics (SVG) Specification) and also:

    SVG document fragments can be included within parent XML documents using the XML namespace facilities described in Namespaces in XML [XML-XS]. Note, however, that since a Conforming SVG Document Fragment must have an svg element as its root, the use of an individual non-svg element from the SVG namespace is disallowed. Thus, the SVG part of the following document is not conforming:

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE SomeParentXMLGrammar PUBLIC "-//SomeParent" "http://SomeParentXMLGrammar.dtd">
    <ParentXML>
      <!-- Elements from ParentXML go here -->
      <!-- The following is not conforming -->
      <z:rect xmlns:z="http://www.w3.org/2000/svg"
              x="0" y="0" width="10" height="10" />
      <!-- More elements from ParentXML go here -->
    </ParentXML>

    Instead, for the SVG part to become a Conforming SVG Document Fragment, the file could be modified as follows:

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE SomeParentXMLGrammar PUBLIC "-//SomeParent" "http://SomeParentXMLGrammar.dtd">
    <ParentXML>
      <!-- Elements from ParentXML go here -->
      <!-- The following is conforming -->
      <z:svg xmlns:z="http://www.w3.org/2000/svg"
             width="100px" height="100px">
        <z:rect x="0" y="0" width="10" height="10"/>
      </z:svg>
      <!-- More elements from ParentXML go here -->
    </ParentXML>
    

    The SVG language or these conformance criteria provide no designated size limits on any aspect of SVG content. There are no maximum values on the number of elements, the amount of character data, or the number of characters in attribute values.

    D.3. Conforming SVG Stand-Alone Files

    A file is a Conforming SVG Stand-Alone File if:

    D.4. Conforming SVG Generators

    A Conforming SVG Generator is a program which:

    Additionally, an authoring tool which is a Conforming SVG Generator conforms to all of the Priority 1 accessibility guidelines from the document Authoring Tool Accessibility Guidelines 1.0 [ATAG] that are relevant to generators of SVG content. (Priorities 2 and 3 are encouraged but not required for conformance.)

    SVG generators are encouraged to follow W3C developments in the area of internationalization. Of particular interest is the W3C Character Model and the concept of Webwide Early Uniform Normalization, which promises to enhance the interchangability of Unicode character data across users and applications. Future versions of the SVG specification are likely to require support of the W3C Character Model in Conforming SVG Generators.

    On occasions when expression of the information exceeding single precision is desired for some use cases such as maps and technical drawings, it is encouraged that the following generation steps are utilized.

    Although the real number precision of SVG is single-precision, presentation with an effective precision higher than single-precision may be obtained by generating SVG content that takes advantage of the fact that at least double-precision floating point must be used when generating a CTM (See CTM generation processing in the Conforming SVG Viewers section). The steps for generating content that takes advantage of this are:

    1. Split content into tiles such that the number of significant digits required to position and size each object within a tile is within the range of single precision floats. Besides, in this description, the coordinate system which the original content has originally will be called source space.
    2. Generate a coordinate transformation matrix per tile to transform from source space to tile space, where tile space is a coordinate system with origin (0,0) at the top left of the the tile. Each element of the transformation matrix must be within the range of single precision.
    3. Transform the contents of each tile from source space to tile space using the generated coordinate transformation matrix. The result is that the parameters of each object can now be expressed with significant digits within the range of single precision floats.
    4. For each tile, generate an inverse transformation matrix for the conversion of tile space to source space. This is used as a transform attribute of the element for the tile of the next step.
    5. Arrange each tile as a separate user coordinate system in SVG. For example, the tiles may be expressed a g elements with an transform attribute having the transformation matrix generated by the previous step. And the split graphics generated by the third step will be placed as children of it.
    Example Splitting vector graphics bigger than a tile
    Before Splitting       After Splitting
    Example Before splitting       Example After Splitting
    Example Improving Significant Digits
    Step 1 : Splitting content       Step 5 : Arranging tiles with smaller effective digits and appropriate translate
    Example Split content into tiles       Example Translate and assign split contents
    This example provides the significant figure of eight digits using tiles with the user coordinate system of seven digits.

    D.5. Conforming SVG Servers

    Conforming SVG Servers must meet all the requirements of a Conforming SVG Generator. In addition, Conforming SVG Servers using HTTP or other protocols that use Internet Media types must serve SVG stand-alone files with the media type "image/svg+xml".

    Also, if the SVG file is compressed with gzip or deflate, Conforming SVG Servers must indicate this with the appropriate header, according to what the protocol supports. Specifically, for content compressed by the server immediately prior to transfer, the server must use the "Transfer-Encoding: gzip" or "Transfer-Encoding: deflate" headers as appropriate, and for content stored in a compressed format on the server (e.g. with the file extension "svgz"), the server must use the "Content-Encoding: gzip" or "Content-Encoding: deflate" headers as appropriate.

    Note: Compression of stored content (the "entity," in HTTP terms) is distinct from automatic compression of the message body, as defined in HTTP/1.1 TE/ Transfer Encoding ([RFC2616], sections 14.39 and 14.41).

    D.6. Conforming SVG DOM Subtree

    A DOM subtree rooted at a given element is a Conforming SVG DOM Subtree if, once serialized to XML, is a Conforming SVG Document Fragment. If the DOM subtree cannot be serialized to XML, such as when a Comment node's data contains the substring "--", then the subtree is not a Conforming SVG DOM Subtree.

    D.7. Conforming SVG Interpreters

    An SVG Interpreter is a program which can parse and process SVG document fragments. Examples of SVG Interpreters are server-side transcoding tools (e.g., a tool which converts SVG content into modified SVG content) or analysis tools (e.g., a tool which extracts the text content from SVG content). An SVG viewer also satisfies the requirements of an SVG interpreter in that it can parse and process SVG document fragments, where processing consists of rendering the SVG content to the target medium.

    A Conforming SVG Interpreter must be able to parse and process all XML constructs defined within XML 1.0 [XML10] and Namespaces in XML [XML-NS].

    A Conforming SVG Interpreter must parse any SVG document correctly. It is not required to interpret the semantics of all features correctly.

    A Conforming SVG Interpreter must be able to support at least one of the following processing modes defined in the SVG integration specification [SVG-INTEGRATION]:

    Note: A transcoder from SVG into another graphics representation, such as an SVG-to-raster transcoder, represents a viewer, and thus viewer conformance criteria apply.

    D.8. Conforming SVG Viewers

    Action: Look at the performance class requirements and decide whether to remove points or move them into general requirements. (heycam)
    Spec that calculation of CTMs should use double precision. (stakagi)
    Resolution: Remove performance class requirements from SVG 2. ( ConformingHighQualitySVGViewers )
    Purpose: To modulate the tradeoff of a numerical precision in use cases of the technical drawing and mapping, and the performance of user agent.
    Owner: heycam, stakagi

    An SVG viewer is a program which can parse and process an SVG document fragment and render the contents of the document onto some sort of output medium such as a display or printer; thus, an SVG Viewer is also an SVG Interpreter.

    A Conforming SVG Viewer must be able to support at least one of the following processing modes defined in the SVG integration specification [SVG-INTEGRATION]:

    Specific criteria that must apply to a Conforming SVG Viewer:

    Although anti-aliasing support is not a strict requirement for a Conforming SVG Viewer, it is highly recommended for display devices. Lack of anti-aliasing support will generally result in poor results on display devices.

    A Conforming SVG Viewer that supports processing modes that include interaction must support the following additional features:

    A Conforming SVG Viewer that supports processing modes that include script execution must support the following additional features:

    The Web Accessibility Initiative is defining User Agent Accessibility Guidelines 1.0 [UAAG]. Viewers are encouraged to conform to the Priority 1 accessibility guidelines defined in this document, and preferably also Priorities 2 and 3. Once the guidelines are completed, a future version of this specification is likely to require conformance to the Priority 1 guidelines in Conforming SVG Viewers.

    A Conforming SVG Viewer must be able to apply styling properties to SVG content using presentation attributes.

    If the user agent supports Cascading Style Sheets, level 2 revision 1 [CSS21], a Conforming SVG Viewer must support CSS styling of SVG content and must support all features from CSS 2.1 that are described in this specification as applying to SVG (see Styling). The supported features from CSS 2.1 must be implemented in accordance with the conformance definitions from the CSS 2.1 specification ([CSS21], section 3.2).

    If the user agent includes an HTML or XHTML viewing capability or can apply CSS/XSL styling properties to XML documents, then a Conforming SVG Viewer must support resources of MIME type "image/svg+xml" wherever raster image external resources can be used, such as in the HTML or XHTML ‘img’ element and in CSS/XSL properties that can refer to raster image resources (e.g., ‘background-image’).

    D.8.1. Conforming High-Quality SVG Viewer

    A higher order concept is that of a Conforming High-Quality SVG Viewer.

    A Conforming High-Quality SVG Viewer must support the following additional features:

    A Conforming High-Quality SVG Viewer that supports processing modes that include script execution, declarative animation, or interaction must support the following additional features:

    A Conforming High-Quality SVG Viewer that supports processing modes that include interaction must support the following additional features:

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix E: Accessibility Support

    This appendix is informative, not normative.

    E.1. SVG Accessibility Features

    This appendix highlights the accessibility features of SVG and accessibility related specifications used to support SVG and the associated W3C Web Content Accessibility Guidelines (WCAG) 2.0 [WCAG2] requirements they are designed to support.

    [WCAG2] Create content that can be presented in different ways (for example simpler layout) without losing information or structure: Information and Relationships.
    • Support for aria-labelledby for label relationships.
    • Support for aria-describedby for description relationships.
    • Support for aria-owns for structural relationships.
    • Support for aria-controls for control relationships where an element controls the content and or behavior of another element.
    • The g for defined groupings.
    • Support for the WAI-ARIA group and radiogroup roles.
    [WCAG2] Time Based Media: Provide alternatives for time-based media.
    • The audio and video elements support the HTML5 ‘track’ element to provide alternatives for time-based media
    [WCAG2] Keyboard Accessible: Make all functionality available from the keyboard.
    [WCAG2] Navigable: Provide ways to help users navigate, find content, and determine where they are.
    • To enable bypassing of blocks of content SVG supports the: WAI-ARIA landmark roles.
    • Supports title to provide page titles.
    • Supports tabindex to provide a sequential focus navigation order.
    • Supports the a element, enabling authors to supply the link purpose both from its content.
    • Supports headings and labels through the use of the heading role with aria-level, aria-labelledby and aria-label.
    • Support visible focus by rendering visible focus on focused elements in the tab order.
    [WCAG2] Readable: Make text content readable and understandable.
    • Supports the language of the page as well as its parts through the lang attribute.
    [WCAG2] Compatible: Maximize compatibility with current and future user agents, including assistive technologies.
    WAI-ARIA Support and text alternatives

    E.2. Supporting SVG Accessibility Specifications and Guidelines

    This section enumerates the SVG accessibility-related specifications and authoring guidelines.

    Related SVG Accessibility Specifications for User Agents
    Related Specifications for Content Authors
    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix F: References

    F.1. Normative references

    [ARIA]
    Accessible Internet Applications (WAI-ARIA) 1.1, J. Craig, M. Cooper, S. McCarron, eds. World Wide Web Consortium, 19 November 2015.
    This edition of WAI-ARIA is https://www.w3.org/TR/2015/WD-wai-aria-1.1-20151119/.
    The latest edition of WAI-ARIA is available at http://www.w3.org/TR/wai-aria-1.1/.
    [ARIA-GRAPHICS]
    WAI-ARIA Graphics Module, A. Bellamy-Royds, F. Esch, R. Schwerdtfeger, L. Watson, eds. World Wide Web Consortium, 3 December 2015.
    This edition of the WAI-ARIA Graphics Module is https://www.w3.org/TR/2015/WD-graphics-aria-1.0-20151203/.
    The latest edition of the WAI-ARIA Graphics Module is available at https://www.w3.org/TR/graphics-aria-1.0/.
    [ATAG]
    Authoring Tool Accessibility Guidelines 1.0, J. Treviranus, J. Richards, I. Jacobs, C. McCathieNevile, eds. World Wide Web Consortium, 03 February 2000.
    This edition of ATAG 1.0 is http://www.w3.org/TR/2000/REC-ATAG10-20000203/.
    The latest edition of ATAG 1.0 is available at http://www.w3.org/TR/ATAG10/.
    [BCP47]
    Tags for Identifying Languages (BCP 47), Phillips, M. Davis, eds. IETF, September 2009.
    Available at http://www.rfc-editor.org/rfc/bcp/bcp47.txt.
    [COLORIMETRY]
    Colorimetry, Third Edition, Commission Internationale de l'Eclairage, CIE Publication 15:2004, ISBN 3-901-906-33-9.
    Available at http://www.cie.co.at/publ/abst/15-2004.html.
    [COMPOSITING-BLENDING]
    Compositing and Blending Level 1, R. Cabanier, N. Andronikos, eds. World Wide Web Consortium, 13 January 2015. W3C Candidate Recommendation. (Work in progress.)
    This edition of Compositing and Blending Level 1 is http://www.w3.org/TR/2015/CR-compositing-1-20150113/.
    The latest edition of Compositing and Blending Level 1 is available at http://www.w3.org/TR/compositing-1/.
    [CSS21]
    Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification, B. Bos, T. Çelik, I. Hickson, H. Lie, eds. World Wide Web Consortium, 07 June 2011.
    This edition of CSS 2.1 is http://www.w3.org/TR/2011/REC-CSS2-20110607/.
    The latest edition of CSS 2 is available at http://www.w3.org/TR/CSS2/.
    [css-cascade-4]
    CSS Cascading and Inheritance Level 4, Elika Etemad; Tab Atkins Jr., eds. World Wide Web Consoritum, 14 January 2016.
    This edition of CSS Cascading and Inheritance is http://www.w3.org/TR/2011/REC-css3-color-20110607/.
    The latest edition of CSS Cascading and Inheritance is available at https://www.w3.org/TR/css-cascade-4/.
    [CSS3COLOR]
    CSS Color Module Level 3, T. Çelik, C. Lilley, L. D. Baron, eds. World Wide Web Consoritum, 07 June 2011.
    This edition of CSS3 Color is http://www.w3.org/TR/2011/REC-css3-color-20110607/.
    The latest edition of CSS3 Color is available at http://www.w3.org/TR/css3-color/.
    [CSS3FONTS]
    CSS Fonts Module Level 3, J. Daggett, ed. World Wide Web Consortium, 3 October 2013.
    This edition of CSS3 Fonts is http://www.w3.org/TR/2013/CR-css-fonts-3-20131003/
    The latest editor's draft is available at http://dev.w3.org/csswg/css3-fonts/.
    [CSS3INLINE]
    CSS Inline Layout Module Level 3, Dave Cramer, Elika J. Etemad, Steve Zilles, eds. World Wide Web Consortium, 17 September 2015.
    The latest editor's draft is available at http://dev.w3.org/csswg/css-inline/.
    [CSS3TEXT]
    CSS Text Module Level 3, Elika J. Etemad, Koji Ishii, eds. World Wide Web Consortium, 10 October 2013.
    The latest editor's draft is available at http://dev.w3.org/csswg/css-text-3/.
    [CSS4TEXT]
    CSS Text Module Level 4, Elika J. Etemad, Koji Ishii, Alan Stearns, eds. World Wide Web Consortium, 22 September 2015.
    The latest editor's draft is available at http://drafts.csswg.org/css-text-4/.
    [CSS3TEXTDECOR]
    CSS Text Decoration Module Level 3, Elika J. Etemad, Koji Ishii, eds. World Wide Web Consortium, 1 August 2013.
    The latest editor's draft is available at http://dev.w3.org/csswg/css-text-decor-3/.
    [CSS-MASKING]
    CSS Masking Module Level 1, D. Schulze, B. Birtles, T. Atkins, eds. World Wide Web Consortium, 26 August 2014. W3C Candidate Recommendation. (Work in progress.)
    This edition of CSS Masking Module Level 1 is http://www.w3.org/TR/2014/CR-css-masking-1-20140826/.
    The latest edition of CSS Masking Module Level 1 is available at http://www.w3.org/TR/css-masking-1/.
    [CSS3UI]
    CSS Basic User Interface Module Level 3 (CSS3 UI), T. Çelik, ed. World Wide Web Consortium, 7 July 2015.
    This edition of CSS3 UI is https://www.w3.org/TR/2015/CR-css-ui-3-20150707/.
    The latest edition of CSS3 UI is available at http://www.w3.org/TR/css-ui-3/.
    [CSS3TRANSFORMS]
    CSS Transforms, S. Fraser, D. Jackson, D. Hyatt, C. Marrin, E. O'Connor, D. Schulze, A. Gregor, eds. World Wide Web Consortium, 3 April 2012. W3C Working Draft. (Work in progress.)
    This edition of CSS Transforms is http://www.w3.org/TR/2012/WD-css3-transforms-20120403/.
    The latest edition of CSS Transforms is available at http://www.w3.org/TR/css3-transforms/.
    [CSS3VALUES]
    CSS Values and Units Level 3, H. Lie, T. Atkins, E. Etemad, eds. World Wide Web Consortium, 8 March 2012. W3C Working Draft. (Work in progress.)
    This edition of CSS3 Values and Units is http://www.w3.org/TR/2012/WD-css3-values-20120308/.
    The latest edition of CSS3 Values and Units is available at http://www.w3.org/TR/css3-values/.
    [CSS3IMAGES]
    CSS Image Values and Replaced Content Module Level 3, E. Etemad, T. Atkins, eds. World Wide Web Consortium, 17 April 2012.
    The latest edition of CSS4 Images is available at http://www.w3.org/TR/css3-images/.
    [CSS4IMAGES]
    CSS Image Values and Replaced Content Module Level 4, E. Etemad, T. Atkins, eds. World Wide Web Consortium, 21 July 2012.
    The latest edition of CSS4 Images is available at http://dev.w3.org/csswg/css4-images/.
    [CSSSHAPES1]
    CSS Shapes Module Level 1, Vincent Hardy, Rossen Atanassov, Alan Stearns, eds. World Wide Web Consortium, 20 March 2014.
    The latest edition of CSS Shapes 1 is available at http://www.w3.org/TR/css-shapes-1/.
    [CSSSHAPES2]
    CSS Shapes Module Level 2, Alan Stearns ed. World Wide Web Consortium, 17 March 2014.
    The latest edition of CSS Shapes 2 is available at http://dev.w3.org/csswg/css-shapes-2/.
    [CSSWRITINGMODES3]
    CSS Writing Modes Level 3, Elika J. Etemad, Koji Ishii eds. World Wide Web Consortium, 15 December 2015.
    The latest edition of CSS Writing Modes Level 3 is available at http://dev.w3.org/csswg/css3-writing-modes/.
    [css-scoping-1]
    CSS Scoping Module Level 1, Tab Atkins Jr.; Elika Etemad. 3 April 2014. W3C Working Draft. URL: https://www.w3.org/TR/css-scoping-1/ ED: http://dev.w3.org/csswg/css-scoping/
    [DOM3EVENTS]
    Document Object Model (DOM) Level 3 Events Specification, Gary Kacmarcik, Travis Leithead, Jacob Rossi, Doug Schepers, Björn Höhrmann, Philippe Le Hégaret, Tom Pixley, eds. World Wide Web Consortium, 15 November 2013.
    This edition of DOM 2 Events is http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/.
    The latest edition of DOM 2 Events is available at http://www.w3.org/TR/DOM-Level-3-Events/.
    [DOM2STYLE]
    Document Object Model (DOM) Level 2 Style Specification, C. Wilson, P. Le Hégaret, V. Apparao, eds. World Wide Web Consortium, 13 November 2000.
    This edition of DOM Level 2 Style is http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113/.
    The latest edition of DOM Level 2 Style is available at http://www.w3.org/TR/DOM-Level-2-Style/.
    [DOM2VIEWS]
    Document Object Model (DOM) Level 2 Views Specification, A. Le Hors, L. Cable, eds. World Wide Web Consortium, 13 November 2000.
    This edition of DOM 2 Views is http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113/.
    The latest edition of DOM 2 Views is available at http://www.w3.org/TR/DOM-Level-2-Views/.
    [DOM4]
    DOM4, A. van Kesteren, A. Gregor, Ms2ger, A. Russell, R. Berjon, eds. World Wide Web Consortium, 04 February 2014.
    This edition of DOM4 is http://www.w3.org/TR/2014/WD-dom-20140204/.
    The latest edition of DOM4 is available at http://www.w3.org/TR/dom/.
    [ECMA-262]
    ECMAScript Language Specification, 5th Edition, M. Cowlishaw, ed. Ecma International, December 2009.
    Available at http://www.ecma-international.org/publications/standards/Ecma-262.htm.
    [FILTERS]
    Filter Effects Module Level 1, D. Jackson, E. Dahlström, D. Schulze, eds. World Wide Web Consortium, 25 November 2014. W3C Working Draft. (Work in progress.)
    This edition of Filter Effects 1.0 is http://www.w3.org/TR/2014/WD-filter-effects-1-20141125/.
    The latest edition of Filter Effects Module Level 1 is available at http://www.w3.org/TR/filter-effects-1/.
    [HTML]
    HTML 5.1, S. Pieters, A. van Kesteren, P. Jägenstedt, D. Denicola, I. Hickson (WHATWG), and S. Faulkner, T. Leithead, E. Navara, E. O'Connor, R. Berjon (W3C), eds. World Wide Web Consortium, 08 October 2015. W3C Working Draft.
    This edition of HTML 5.1 is http://www.w3.org/TR/2015/WD-html51-20151008/.
    The latest version of HTML 5.1 is available at http://www.w3.org/TR/html51/.
    [ICC42]
    Specification ICC.1:2004-10, File Format for Color Profiles, Profile Version 4.2.0.0 with errata incorporated, 5/22/20006, International Color Consortium, 2006.
    Available at http://www.color.org/ICC1v42_2006-05.pdf.
    This specification is substantially identical to ISO 15076-1:2005.
    The ICC list some approved revisions to ICC.1:2004-10.
    [ISO8601]
    Data elements and interchange formats - Information interchange - Representation of dates and times, International Organization for Standardization, 2004. Available at http://www.iso.org/iso/catalogue_detail?csnumber=40874.
    [JPEG]
    ISO/IEC 10918-1:1994/Cor 1:2005: Information Technology — Digital Compression And Coding Of Continuous-tone Still Images, International Organization for Standardization, September 2005.
    Available at http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=18902.
    An older version is available at http://www.w3.org/Graphics/JPEG/itu-t81.pdf.
    [EDITING]
    HTML Editing APIs, A. Gregor, ed.
    Available at https://dvcs.w3.org/hg/editing/raw-file/tip/editing.html.
    [MEDIAFRAGMENTSURI]
    Media Fragments URI 1.0 (basic), R. Troncy, E. Mannens, S. Pfeiffer, D. Van Deursen, eds. World Wide Web Consoritum, 25 September 2012.
    This edition of Media Fragments URI is http://www.w3.org/TR/2012/REC-media-frags-20120925/.
    The latest edition of Media Fragments URI is available at http://www.w3.org/TR/media-frags/.
    [PNG]
    Portable Network Graphics (PNG) Specification (Second Edition): Information technology — Computer graphics and image processing — Portable Network Graphics (PNG): Functional specification, ISO/IEC 15948:2003 (E), D. Duce, ed. World Wide Web Consortium, 10 November 2003.
    This edition of PNG is http://www.w3.org/TR/2003/REC-PNG-20031110/.
    The latest edition of PNG is available at http://www.w3.org/TR/PNG/.
    [RFC1951]
    DEFLATE Compressed Data Format Specification version 1.3, P. Deutsch, May 1996.
    Available at http://www.ietf.org/rfc/rfc1951.txt.
    [RFC1952]
    GZIP file format specification version 4.3, P. Deutsch, May 1996.
    Available at http://www.ietf.org/rfc/rfc1952.txt.
    [RFC2046]
    Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types, N. Freed and N. Borenstein, November 1996. (Note that this RFC obsoletes RFC 1521, RFC 1522 and RFC 1590.)
    Available at http://www.ietf.org/rfc/rfc2046.txt.
    [RFC2119]
    Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997.
    Available at http://www.ietf.org/rfc/rfc2119.txt.
    [RFC2397]
    The "data" URL scheme, L. Masinter, August 1998.
    Available at http://www.ietf.org/rfc/rfc2397.
    [RFC2616]
    Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk Nielsen, L. Masinter, P. Leach and T. Berners-Lee, June 1999. (Note that this RFC obsoletes RFC 2068.)
    Available at http://www.ietf.org/rfc/rfc2616.
    [RFC3023]
    XML Media Types, M. Murata, S. St. Laurent, D. Kohn, January 2001.
    Available at http://www.ietf.org/rfc/rfc3023.
    [RFC3986]
    Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, January 2005. (Note that RFC 3986 updates RFC 1738 and obsoletes RFC 2732, RFC 2396 and RFC 1808.)
    Available at http://tools.ietf.org/html/rfc3986.
    [URL]
    URL Standard, A. van Kesteren, S. Ruby.
    Available at https://url.spec.whatwg.org/.
    [RFC3987]
    Internationalized Resource Identifiers (IRIs), M. Dürst, M. Suignard, January 2005.
    Available at http://tools.ietf.org/html/rfc3987.
    [RFC4329]
    Scripting Media Types, B. Höhrmann, April 2006.
    Available at http://www.ietf.org/rfc/rfc4329.txt.
    [SHADOWDOM]
    Shadow DOM, D. Glazkov, eds. 14 May 2013.
    This edition of Shadow DOM is http://www.w3.org/TR/2013/WD-shadow-dom-20130514/.
    The latest edition of Shadow DOM is available at http://www.w3.org/TR/shadow-dom/.
    [SMIL]
    Synchronized Multimedia Integration Language (SMIL 3.0), D. Bulterman et al., eds. 01 December 2008.
    This edition of SMIL is http://www.w3.org/TR/2008/REC-SMIL3-20081201/.
    The latest edition of SMIL is available at http://www.w3.org/TR/smil/.
    [SMILANIM]
    SMIL Animation, P. Schmitz, A. Cohen. World Wide Web Consortium, 04 September 2001.
    This edition of SMIL Animation is http://www.w3.org/TR/2001/REC-smil-animation-20010904/.
    The latest edition of SMIL Animation is available at http://www.w3.org/TR/smil-animation/.
    [SRGB]
    IEC 61966-2-1/Amd 1:2003 : Multimedia systems and equipment — Colour measurement and management — Part 2-1: Colour management — Default RGB colour space — sRGB, International Electrotechnical Commission, 2003.
    Available at https://webstore.iec.ch/publication/6168.
    See also http://www.color.org/chardata/rgb/srgb.xalter for technical data and color profiles.
    [SVG-AAM]
    WAI-ARIA User Agent Implementation Guide, Rich Schwerdtfeger,et al., eds. World Wide Web Consortium, 26 February 2015.
    This edition of the SVG Accessibility API Mappings specification is http://www.w3.org/TR/2015/WD-svg-aam-1.0-20150226/.
    The latest edition of the WAI-ARIA Implementation Guide is available at http://www.w3.org/TR/svg-aam-1.0/.
    [STD68]
    Augmented BNF for Syntax Specifications: ABNF, D. Crocker, P. Overell, January 2008.
    Available at http://tools.ietf.org/html/std68.
    [UAX9]
    Unicode Bidirectional Algorithm, The Unicode Standard Annex #9. The Unicode Consortium, 2010.
    Available at http://www.unicode.org/reports/tr9/.
    [UIEVENTS]
    UI Events, Gary Kacmarcik, Travis Leithead, eds. World Wide Web Consortium, 5 November 2013.
    This edition of UI Events is http://www.w3.org/TR/2013/WD-uievents-20131105/.
    The latest edition of UI Events is available at http://www.w3.org/TR/uievents/.
    [UNICODE]
    The Unicode Standard, Version 8.0.0, The Unicode Consortium, Mountain View, CA, 2011. ISBN 978-1-936213-10-8.
    Available at http://www.unicode.org/versions/Unicode8.0.0.
    [WAAPI]
    Web Animations, Brian Birtles; Shane Stephens; Alex Danilo; Tab Atkins Jr. 7 July 2015. W3C Working Draft. URL: https://www.w3.org/TR/web-animations-1/ ED: https://w3c.github.io/web-animations/
    [WEBIDL]
    Web IDL, C. McCormack, B. Zbarsky, eds. World Wide Web Consortium, work in progress.
    The latest editor's draft is available at https://heycam.github.io/webidl/.
    [WOFF]
    WOFF File Format 1.0, J. Kew, T. Leming , E. van Blokland, eds. World Wide Web Consortium, 13 December 2012.
    This edition of WOFF is http://www.w3.org/TR/2012/REC-WOFF-20121213/.
    The latest edition of WOFF is available at http://www.w3.org/TR/WOFF/.
    XML Linking Language (XLink) Version 1.1, S. DeRose, E. Maler, D. Orchard, N. Walsh, eds. World Wide Web Consortium, 06 May 2010.
    This edition of XLink 1.1 is http://www.w3.org/TR/2010/REC-xlink11-20100506/.
    The latest edition of XLink 1.1 is available at http://www.w3.org/TR/xlink11/.
    [XML10]
    Extensible Markup Language (XML) 1.0 (Fifth Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, F. Yergeau, eds. World Wide Web Consortium, 26 November 2008.
    This edition of XML 1.0 is http://www.w3.org/TR/2008/REC-xml-20081126/.
    The latest edition of XML 1.0 is available at http://www.w3.org/TR/xml/.
    [XML-BASE]
    XML Base (Second Edition), J. Marsh, R. Tobin, eds. World Wide Web Consortium, 28 January 2009.
    This edition of XML Base is http://www.w3.org/TR/2009/REC-xmlbase-20090128/.
    The latest edition of XML Base is available at http://www.w3.org/TR/xmlbase/.
    [XML-NS]
    Namespaces in XML 1.0 (Third Edition), T. Bray, D. Hollander, A. Layman, R. Tobin, H. Thompson, eds. World Wide Web Consortium, 8 December 2009.
    This edition of Namespaces in XML is http://www.w3.org/TR/2009/REC-xml-names-20091208/.
    The latest edition of Namespaces in XML is available at http://www.w3.org/TR/xml-names/.
    [XML-SS]
    Associating Style Sheets with XML documents, Version 1.0, J. Clark, ed. World Wide Web Consortium, 29 June 1999.
    This edition of XML Stylsheet is http://www.w3.org/1999/06/REC-xml-stylesheet-19990629/.
    The latest edition of XML Stylesheet is available at http://www.w3.org/TR/xml-stylesheet/.
    [XSL]
    Extensible Stylesheet Language (XSL) Version 1.1, A. Berglund, ed. World Wide Web Consortium, 05 December 2006.
    This edition of XSL is http://www.w3.org/TR/2006/REC-xsl11-20061205/.
    The latest edition of XSL is available at http://www.w3.org/TR/xsl/.

    F.2. Informative references

    [CHARMOD]
    Character Model for the World Wide Web 1.0: Fundametnals, M. Dürst, F. Yergeau, R. Ishida, M. Wolf, T. Texin, eds. World Wide Web Consortium, 15 February 2005.
    This edition of Charmod Fundamentals is http://www.w3.org/TR/2005/REC-charmod-20050215/.
    The latest edition of Charmod Fundamentals is available at http://www.w3.org/TR/charmod/.
    [CSS3ANIMATIONS]
    CSS Animations, D. Jackson, D. Hyatt, C. Marrin, S. Galineau, L. D. Baron, eds. World Wide Web Consortium, 3 April 2012. W3C Working Draft. (Work in progress.)
    This edition of CSS Animations is http://www.w3.org/TR/2012/WD-css3-animations-20120403/.
    The latest edition of CSS Animations is available at http://www.w3.org/TR/css3-animations/.
    [CSS3TRANSITIONS]
    CSS Transitions, D. Jackson, D. Hyatt, C. Marrin, L. D. Baron, eds. World Wide Web Consortium, 3 April 2012. W3C Working Draft. (Work in progress.)
    This edition of CSS Transitions is http://www.w3.org/TR/2012/WD-css3-transitions-20120403/.
    The latest edition of CSS Transitions is available at http://www.w3.org/TR/css3-transitions/.
    [DCORE]
    Dublin Core Metadata Initiative.
    Available at http://dublincore.org/.
    [DOM1]
    Document Object Model (DOM) Level 1 Specification, V. Apparao, S. Byrne, M. Champion, S. Isaacs, I. Jacobs, A. Le Hors, G. Nicol, J. Robie, R. Sutor, C. Wilson, L. Wood, eds. World Wide Web Consortium, 01 October 1998.
    This edition of DOM Level 1 is http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/.
    The latest edition of DOM Level 1 is available at http://www.w3.org/TR/REC-DOM-Level-1/.
    [FOLEY-VANDAM]
    Computer Graphics: Principles and Practice, Second Edition, J. D. Foley, A. van Dam, S. K. Feiner, J. F. Hughes, R. L. Phillips. Addison-Wesley, 1995.
    [HTML4]
    HTML 4.01 Specification, D. Raggett, A. Le Hors, I. Jacobs. World Wide Web Consortium, 24 December 1999.
    This edition of HTML 4 is http://www.w3.org/TR/1999/REC-html401-19991224/.
    The latest edition of HTML 4 is available at http://www.w3.org/TR/html4/.
    [MATHML]
    Mathematical Markup Language (MathML) Version 3.0, D. Carlisle, P. Ion, R. Miner, eds. World Wide Web Consortium, 21 October 2010.
    This edition of MathML 3 is http://www.w3.org/TR/2010/REC-MathML3-20101021/.
    The latest edition of MathML 3 is available at http://www.w3.org/TR/MathML3/.
    [OPENTYPE]
    OpenType Specification Version 1.6. July 2009.
    Available at http://www.microsoft.com/typography/otspec160/.
    (Note that this is technically equivalent to ISO/IEC 14496-22:2009 (Second Edition) "Open Font Format", available at http://standards.iso.org/ittf/PubliclyAvailableStandards/c052136_ISO_IEC_14496-22_2009(E).zip.)
    [RDF-PRIMER]
    RDF Primer, F. Manolas, E. Miller, eds. World Wide Web Consortium, 10 February 2004.
    This edition of RDF Primer is http://www.w3.org/TR/2004/REC-rdf-primer-20040210/.
    The latest edition of RDF Primer is available at http://www.w3.org/TR/rdf-primer/.
    [SCHEMA2]
    XML Schema Part 2: Datatypes Second Edition. P. Biron, A. Malhotra, eds. World Wide Web Consortium, 28 October 2004. (See also Processing XML 1.1 documents with XML Schema 1.0 processors.)
    This edition of XML Schema Part 2 is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.
    The latest edition of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2/.
    [SELECTORS]
    Selectors Level 3, T. Çelik, E. Etemad, D. Glazman, I. Hickson, P. Linss, J. Williams, eds. World Wide Web Consortium, 15 December 2009.
    This edition of Selectors Level 3 is http://www.w3.org/TR/2009/PR-css3-selectors-20091215/.
    The latest edition of Selectors Level 3 is available at http://www.w3.org/TR/css3-selectors/.
    [SVG10]
    Scalable Vector Graphics (SVG) 1.0, J. Ferraiolo, ed. 04 September 2001.
    This edition of SVG 1.0 is http://www.w3.org/TR/2003/REC-SVG11-20030114/.
    The latest edition of SVG 1.0 is available at http://www.w3.org/TR/SVG10/.
    [SVG-INTEGRATION]
    SVG Integration, C. McCormack, D. Schepers, D. Schulze. 17 April 2014.
    This edition of SVG Integration is https://www.w3.org/TR/2014/WD-svg-integration-20140417/.
    The latest edition of SVG Integration is available at https://www.w3.org/TR/svg-integration/.
    [UAAG]
    User Agent Accessibility Guidelines 1.0, I. Jacobs, J. Gunderson, E. Hansen, eds. 17 December 2002.
    This edition of UAAG is http://www.w3.org/TR/2002/REC-UAAG10-20021217/.
    The latest edition of UAAG is available at http://www.w3.org/TR/UAAG10/.
    [WCAG2]
    Web Content Accessibility Guidelines (WCAG) 2.0, B. Caldwell, M. Cooper, L. Reid, G. Vanderheiden, eds. World Wide Web Consortium, 11 December 2008.
    This edition of WCAG 2.0 is http://www.w3.org/TR/2008/REC-WCAG20-20081211/.
    The latest edition of WCAG 2.0 is available at http://www.w3.org/TR/WCAG20/.
    [XHTML]
    XHTML™ 1.0: The Extensible HyperText Markup Language (Second Edition), S. Pemberton, ed. World Wide Web Consortium, 1 August 2002.
    This edition of XHTML 1 is http://www.w3.org/TR/2002/REC-xhtml1-20020801/.
    The latest edition of XHTML 1 is available at http://www.w3.org/TR/xhtml1/.
    [XSLT]
    XSL Transformations (XSLT) Version 1.0, J. Clark, ed. World Wide Web Consortium, 16 November 1999.
    This edition of XSLT 1.0 is http://www.w3.org/TR/1999/REC-xslt-19991116.
    The latest edition of XSLT 1.0 is available at http://www.w3.org/TR/xslt.
    [XSLT2]
    XSL Transformations (XSLT) Version 2.0, M. Kay, ed. World Wide Web Consortium, 23 January 2007.
    This edition of XSLT 2.0 is http://www.w3.org/TR/2007/REC-xslt20-20070123/.
    The latest edition of XSLT 2.0 is available at http://www.w3.org/TR/xslt20/.
    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix G: Element Index

    This appendix is informative, not normative.

    The following are the elements in the SVG language:

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix H: Attribute Index

    This appendix is informative, not normative.

    H.1. Regular attributes

    The following table lists all of the attributes defined in the SVG language, except for the presentation attributes, which are treated in the Presentation attributes section below. For each attribute, the elements on which the attribute may be specified is also given.

    AttributeElements on which the attribute may be specifiedAnim.
    accumulateanimate, animateMotion, animateTransform
    additiveanimate, animateMotion, animateTransform
    amplitudefeFuncA, feFuncB, feFuncG, feFuncR
    aria-activedescendanta, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-atomica, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-autocompletea, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-busya, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-checkeda, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-colcounta, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-colindexa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-colspana, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-controlsa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-currenta, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-describedbya, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-detailsa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-disableda, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-dropeffecta, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-errormessagea, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-expandeda, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-flowtoa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-grabbeda, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-haspopupa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-hiddena, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-invalida, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-labela, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-labelledbya, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-levela, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-livea, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-modala, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-multilinea, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-multiselectablea, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-orientationa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-ownsa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-placeholdera, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-posinseta, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-presseda, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-readonlya, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-relevanta, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-requireda, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-roledescriptiona, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-rowcounta, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-rowindexa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-rowspana, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-selecteda, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-setsizea, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-sorta, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-valuemaxa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-valuemina, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-valuenowa, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    aria-valuetexta, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    attributeNameanimate, animateTransform, set
    azimuthfeDistantLight
    baseFrequencyfeTurbulence
    beginanimate, animateMotion, animateTransform, set
    begindiscard
    biasfeConvolveMatrix
    byanimate, animateMotion, animateTransform
    calcModeanimate, animateMotion, animateTransform
    classa, audio, canvas, circle, clipPath, defs, desc, ellipse, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDropShadow, feFlood, feGaussianBlur, feImage, feMerge, feMorphology, feOffset, feSpecularLighting, feTile, feTurbulence, filter, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mask, meshgradient, meshpatch, meshrow, path, pattern, polygon, polyline, radialGradient, rect, solidcolor, stop, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video
    clipPathUnitsclipPath
    crossoriginfeImage
    crossoriginimage
    crossoriginscript
    cxradialGradient
    cyradialGradient
    dhatchpath
    diffuseConstantfeDiffuseLighting
    divisorfeConvolveMatrix
    downloada
    duranimate, animateMotion, animateTransform, set
    dxfeDropShadow
    dxfeOffset
    dxtext
    dxtspan
    dyfeDropShadow
    dyfeOffset
    dytext
    dytspan
    edgeModefeConvolveMatrix
    edgeModefeGaussianBlur
    elevationfeDistantLight
    endanimate, animateMotion, animateTransform, set
    exponentfeFuncA, feFuncB, feFuncG, feFuncR
    fillanimate, animateMotion, animateTransform, set
    filterUnitsfilter
    frradialGradient
    fromanimate, animateMotion, animateTransform
    fxradialGradient
    fyradialGradient
    gradientTransformlinearGradient
    gradientTransformradialGradient
    gradientUnitslinearGradient
    gradientUnitsmeshgradient
    gradientUnitsradialGradient
    hatchContentUnitshatch
    hatchUnitshatch
    heightfeBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDropShadow, feFlood, feGaussianBlur, feImage, feMerge, feMorphology, feOffset, feSpecularLighting, feTile, feTurbulence
    heightfilter
    heightimage
    heightmask
    heightpattern
    hrefa
    hrefanimate, animateMotion, animateTransform, set
    hrefcursor
    hrefdiscard
    hreffeImage
    hrefhatch
    hrefimage
    hreflinearGradient
    hrefmesh
    hrefmeshgradient
    hrefmpath
    hrefpattern
    hrefradialGradient
    hrefscript
    hreftextPath
    hrefuse
    hreflanga
    ida, animate, animateMotion, animateTransform, audio, canvas, circle, clipPath, cursor, defs, desc, discard, ellipse, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDistantLight, feDropShadow, feFlood, feFuncA, feFuncB, feFuncG, feFuncR, feGaussianBlur, feImage, feMerge, feMergeNode, feMorphology, feOffset, fePointLight, feSpecularLighting, feSpotLight, feTile, feTurbulence, filter, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mask, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    infeBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDropShadow, feGaussianBlur, feMergeNode, feMorphology, feOffset, feSpecularLighting, feTile
    in2feBlend
    in2feComposite
    in2feDisplacementMap
    interceptfeFuncA, feFuncB, feFuncG, feFuncR
    k1feComposite
    k2feComposite
    k3feComposite
    k4feComposite
    kernelMatrixfeConvolveMatrix
    kernelUnitLengthfeConvolveMatrix
    kernelUnitLengthfeDiffuseLighting
    kernelUnitLengthfeSpecularLighting
    keyPointsanimateMotion
    keySplinesanimate, animateMotion, animateTransform
    keyTimesanimate, animateMotion, animateTransform
    langa, animate, animateMotion, animateTransform, audio, canvas, circle, clipPath, cursor, defs, desc, discard, ellipse, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDistantLight, feDropShadow, feFlood, feFuncA, feFuncB, feFuncG, feFuncR, feGaussianBlur, feImage, feMerge, feMergeNode, feMorphology, feOffset, fePointLight, feSpecularLighting, feSpotLight, feTile, feTurbulence, filter, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mask, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    lengthAdjusttext, textPath, tspan
    limitingConeAnglefeSpotLight
    markerHeightmarker
    markerUnitsmarker
    markerWidthmarker
    maskContentUnitsmask
    maskUnitsmask
    maxanimate, animateMotion, animateTransform, set
    mediastyle
    methodtextPath
    minanimate, animateMotion, animateTransform, set
    modefeBlend
    numOctavesfeTurbulence
    offsetfeFuncA, feFuncB, feFuncG, feFuncR
    offsethatchpath
    offsetstop
    onabortsvg
    onafterprint
    onbeforeprint
    onbeginanimate, animateMotion, animateTransform, set
    oncancela, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    oncanplaya, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    oncanplaythrougha, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onchangea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onclicka, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onclosea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    oncuechangea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondblclicka, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondraga, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondragenda, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondragentera, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondragexita, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondragleavea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondragovera, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondragstarta, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondropa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ondurationchangea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onemptieda, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onendanimate, animateMotion, animateTransform, set
    onendeda, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onerrora, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onerrorsvg
    onfocusa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onfocusina, audio, canvas, circle, defs, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video
    onfocusouta, audio, canvas, circle, defs, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video
    onhashchange
    oninputa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    oninvalida, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onkeydowna, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onkeypressa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onkeyupa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onloada, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onloadeddataa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onloadedmetadataa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onloadstarta, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onmessage
    onmousedowna, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onmouseentera, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onmouseleavea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onmousemovea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onmouseouta, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onmouseovera, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onmouseupa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onmousewheela, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onoffline
    ononline
    onpagehide
    onpageshow
    onpausea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onplaya, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onplayinga, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onpopstate
    onprogressa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onratechangea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onrepeatanimate, animateMotion, animateTransform, set
    onreseta, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onresizea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onresizesvg
    onscrolla, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onscrollsvg
    onseekeda, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onseekinga, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onselecta, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onshowa, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onstalleda, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onstorage
    onsubmita, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onsuspenda, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ontimeupdatea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ontogglea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onunload
    onunloadsvg
    onvolumechangea, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    onwaitinga, animate, animateMotion, animateTransform, audio, canvas, circle, cursor, defs, desc, ellipse, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    operatorfeComposite
    operatorfeMorphology
    orderfeConvolveMatrix
    orientmarker
    originanimateMotion
    pathanimateMotion
    pathstop
    pathtextPath
    pathLengthcircle, ellipse, line, path, polygon, polyline, rect
    patternContentUnitspattern
    patternTransformpattern
    patternUnitspattern
    pitchhatch
    playbackordersvg
    pointspolygon
    pointspolyline
    pointsAtXfeSpotLight
    pointsAtYfeSpotLight
    pointsAtZfeSpotLight
    preserveAlphafeConvolveMatrix
    preserveAspectRatiocanvas, feImage, image, marker, pattern, svg, symbol, view
    primitiveUnitsfilter
    rradialGradient
    radiusfeMorphology
    refXmarker
    refXsymbol
    refYmarker
    refYsymbol
    rela
    repeatCountanimate, animateMotion, animateTransform, set
    repeatDuranimate, animateMotion, animateTransform, set
    requiredExtensionsa, animate, animateMotion, animateTransform, audio, canvas, circle, clipPath, discard, ellipse, foreignObject, g, iframe, image, line, mask, mesh, path, polygon, polyline, rect, set, svg, switch, text, textPath, tspan, unknown, use, video
    restartanimate, animateMotion, animateTransform, set
    resultfeBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDropShadow, feFlood, feGaussianBlur, feImage, feMerge, feMorphology, feOffset, feSpecularLighting, feTile, feTurbulence
    reva
    rolea, audio, canvas, circle, cursor, discard, ellipse, foreignObject, g, iframe, image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video, view
    rotateanimateMotion
    rotatehatch
    rotatetext
    rotatetspan
    scalefeDisplacementMap
    seedfeTurbulence
    sidetextPath
    slopefeFuncA, feFuncB, feFuncG, feFuncR
    spacingtextPath
    specularConstantfeSpecularLighting
    specularExponentfeSpecularLighting
    specularExponentfeSpotLight
    spreadMethodlinearGradient
    spreadMethodradialGradient
    startOffsettextPath
    stdDeviationfeDropShadow
    stdDeviationfeGaussianBlur
    stitchTilesfeTurbulence
    stylea, audio, canvas, circle, clipPath, defs, desc, ellipse, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDropShadow, feFlood, feGaussianBlur, feImage, feMerge, feMorphology, feOffset, feSpecularLighting, feTile, feTurbulence, filter, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mask, meshgradient, meshpatch, meshrow, path, pattern, polygon, polyline, radialGradient, rect, solidcolor, stop, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video
    surfaceScalefeDiffuseLighting
    surfaceScalefeSpecularLighting
    systemLanguagea, animate, animateMotion, animateTransform, audio, canvas, circle, clipPath, discard, ellipse, foreignObject, g, iframe, image, line, mask, mesh, path, polygon, polyline, rect, set, svg, switch, text, textPath, tspan, unknown, use, video
    tabindexa, animate, animateMotion, animateTransform, audio, canvas, circle, clipPath, cursor, defs, desc, discard, ellipse, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDistantLight, feDropShadow, feFlood, feFuncA, feFuncB, feFuncG, feFuncR, feGaussianBlur, feImage, feMerge, feMergeNode, feMorphology, feOffset, fePointLight, feSpecularLighting, feSpotLight, feTile, feTurbulence, filter, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mask, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    tableValuesfeFuncA, feFuncB, feFuncG, feFuncR
    targeta
    targetXfeConvolveMatrix
    targetYfeConvolveMatrix
    textLengthtext
    textLengthtextPath, tspan
    timelinebeginsvg
    titlestyle
    toanimate, animateMotion, animateTransform
    toset
    transformhatch
    transformmeshgradient
    transformsvg
    typea
    typeanimateTransform
    typefeColorMatrix
    typefeFuncA, feFuncB, feFuncG, feFuncR
    typefeTurbulence
    typemeshgradient
    typescript
    typestyle
    valuesanimate, animateMotion, animateTransform
    valuesfeColorMatrix
    viewBoxmarker, pattern, svg, symbol, view
    widthfeBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDropShadow, feFlood, feGaussianBlur, feImage, feMerge, feMorphology, feOffset, feSpecularLighting, feTile, feTurbulence
    widthfilter
    widthimage
    widthmask
    widthpattern
    xcursor
    xfeBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDropShadow, feFlood, feGaussianBlur, feImage, feMerge, feMorphology, feOffset, feSpecularLighting, feTile, feTurbulence
    xfePointLight
    xfeSpotLight
    xfilter
    xhatch
    ximage
    xmask
    xmeshgradient
    xpattern
    xtext
    xtspan
    x1line
    x1linearGradient
    x2line
    x2linearGradient
    xChannelSelectorfeDisplacementMap
    xlink:hrefa, cursor, image, linearGradient, pattern, radialGradient, script, textPath, use
    xlink:hreffeImage
    xlink:titlea, cursor, image, linearGradient, pattern, radialGradient, script, textPath, use
    xml:spacea, animate, animateMotion, animateTransform, audio, canvas, circle, clipPath, cursor, defs, desc, discard, ellipse, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDistantLight, feDropShadow, feFlood, feFuncA, feFuncB, feFuncG, feFuncR, feGaussianBlur, feImage, feMerge, feMergeNode, feMorphology, feOffset, fePointLight, feSpecularLighting, feSpotLight, feTile, feTurbulence, filter, foreignObject, g, hatch, hatchpath, iframe, image, line, linearGradient, marker, mask, mesh, meshgradient, meshpatch, meshrow, metadata, mpath, path, pattern, polygon, polyline, radialGradient, rect, script, set, solidcolor, stop, style, svg, switch, symbol, text, textPath, title, tspan, unknown, use, video, view
    ycursor
    yfeBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDropShadow, feFlood, feGaussianBlur, feImage, feMerge, feMorphology, feOffset, feSpecularLighting, feTile, feTurbulence
    yfePointLight
    yfeSpotLight
    yfilter
    yhatch
    yimage
    ymask
    ymeshgradient
    ypattern
    ytext
    ytspan
    y1line
    y1linearGradient
    y2line
    y2linearGradient
    yChannelSelectorfeDisplacementMap
    zfePointLight
    zfeSpotLight
    zoomAndPansvg, view

    H.2. Presentation attributes

    As described in the Styling chapter, for each property there exists a corresponding presentation attribute. The table below lists the presentation attributes.

    alignment-baseline, writing-mode, clip, clip-path, clip-rule, color, color-interpolation, color-interpolation-filters, color-rendering, cursor, direction, display, dominant-baseline, fill, fill-opacity, fill-rule, filter, flood-color, flood-opacity, font-family, font-size, font-size-adjust, font-stretch, font-style, font-variant, font-weight, glyph-orientation-horizontal, glyph-orientation-vertical, image-rendering, letter-spacing, baseline-shift, marker-end, marker-mid, marker-start, mask, opacity, overflow, pointer-events, shape-rendering, solid-color, solid-opacity, stop-color, stop-opacity, stroke, stroke-dasharray, stroke-dashoffset, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-opacity, stroke-width, text-anchor, text-decoration, text-rendering, transform, unicode-bidi, vector-effect, visibility, word-spacing and lighting-color
    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix I: Property Index

    This appendix is informative, not normative.

    This table should not list properties defined in other specifications.

    The table lacks a column for the 'computed value'.

    The table should ideally be generated automatically from the definition of each property, to ensure that this is the complete list.

    Name Values Initial value Applies to Inh. Percentages Media Anim.
    alignment-baseline auto | baseline | before-edge | text-before-edge | middle | central | after-edge | text-after-edge | ideographic | alphabetic | hanging | mathematical see property description tspan, textPath elements no N/A visual yes
    baseline-shift baseline | sub | super | <percentage> | <length> baseline tspan, textPath elements no refer to the "line height" of the text element, which in the case of SVG is defined to be equal to the font size visual yes
    clip <shape> | auto auto elements which establish a new SVG viewport, pattern elements and marker elements no N/A visual yes
    clip-path <basic-shape> | <url> | none none container elements and graphics elements no N/A visual yes
    clip-rule nonzero | evenodd nonzero graphics elements within a clipPath element yes N/A visual yes
    color <color> depends on user agent elements to which properties fill, stroke, stop-color, flood-color, lighting-color apply yes N/A visual yes
    color-interpolation auto | sRGB | linearRGB sRGB container elements, graphics elements and animate yes N/A visual yes
    color-rendering auto | optimizeSpeed | optimizeQuality auto container elements, graphics elements and animate yes N/A visual yes
    cursor [ [<url> ,]* [ auto | crosshair | default | pointer | move | e-resize | ne-resize | nw-resize | n-resize | se-resize | sw-resize | s-resize | w-resize| text | wait | help ] ] auto container elements and graphics elements yes N/A visual, interactive yes
    direction ltr | rtl ltr text content elements yes N/A visual no
    display inline | block | list-item | run-in | compact | marker | table | inline-table | table-row-group | table-header-group | table-footer-group | table-row | table-column-group | table-column | table-cell | table-caption | none inline svg, g, switch, a, foreignObject, graphics elements (including the text element) and text sub-elements (i.e., tspan, textPath) no N/A all yes
    dominant-baseline auto | use-script | no-change | reset-size | ideographic | alphabetic | hanging | mathematical | central | middle | text-after-edge | text-before-edge auto text content elements no N/A visual yes
    fill <paint> (See Specifying paint) black shapes and text content elements yes N/A visual yes
    fill-opacity <opacity-value> 1 shapes and text content elements yes N/A visual yes
    fill-rule nonzero | evenodd nonzero shapes and text content elements yes N/A visual yes
    filter <filter-function-list> | none none container elements and graphics elements no N/A visual yes
    flood-color currentColor |
    <color> [<icccolor>]
    black feFlood elements no N/A visual yes
    flood-opacity <opacity-value> 1 feFlood elements no N/A visual yes
    font [ [ font-style || font-variant || font-weight ]? font-size [ / 'line-height' ]? font-family ] | caption | icon | menu | message-box | small-caption | status-bar see individual properties text content elements yes see individual properties visual yes [1]
    font-family [[ <family-name> | <generic-family> ],]* [ <family-name> | <generic-family>] depends on user agent text content elements yes N/A visual yes
    font-size <absolute-size> | <relative-size> | <length> | <percentage> medium text content elements yes, the computed value is inherited refer to parent element's font size visual yes
    font-size-adjust <number> | none none text content elements yes N/A visual yes [1]
    font-stretch normal | wider | narrower | ultra-condensed | extra-condensed | condensed | semi-condensed | semi-expanded | expanded | extra-expanded | ultra-expanded normal text content elements yes N/A visual yes
    font-style normal | italic | oblique normal text content elements yes N/A visual yes
    font-variant normal | small-caps normal text content elements yes N/A visual yes
    font-weight normal | bold | bolder | lighter | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 normal text content elements yes N/A visual yes
    glyph-orientation-horizontal <angle> | <number> 0deg text content elements yes N/A visual no
    glyph-orientation-vertical auto | <angle> | <number> auto text content elements yes N/A visual no
    image-rendering auto | optimizeSpeed | optimizeQuality auto images yes N/A visual yes
    letter-spacing normal | <length> normal text content elements yes N/A visual yes
    lighting-color currentColor |
    <color> [<icccolor>]
    white feDiffuseLighting and feSpecularLighting elements no N/A visual yes
    line-height normal | <number> | <length> | <percentage> normal text elements yes refer to font size of element itself visual yes
    marker see individual properties see individual properties path, line, polyline and polygon elements yes N/A visual yes
    marker-end
    marker-mid
    marker-start
    none | <url> none path, line, polyline and polygon elements yes N/A visual yes
    mask <url> | none none container elements and graphics elements no N/A visual yes
    opacity <opacity-value> 1 container elements and graphics elements no N/A visual yes
    overflow visible | hidden | scroll | auto see prose elements which establish a new SVG viewport, pattern elements and marker elements no N/A visual yes
    paint-order normal | [ fill || stroke || markers ] normal graphics elements and text content elements no N/A visual yes
    pointer-events bounding-box | visiblePainted | visibleFill | visibleStroke | visible |
    painted | fill | stroke | all | none
    visiblePainted container elements, graphics elements and text content child elements yes N/A visual yes
    shape-rendering auto | optimizeSpeed | crispEdges |
    geometricPrecision
    auto shapes yes N/A visual yes
    stop-color currentColor |
    <color> [<icccolor>]
    black stop elements no N/A visual yes
    stop-opacity <opacity-value> 1 stop elements no N/A visual yes
    stroke <paint> (See Specifying paint) none shapes and text content elements yes N/A visual yes
    stroke-dasharray none | <dasharray> none shapes and text content elements yes N/A visual yes [1]
    stroke-dashoffset <percentage> | <length> 0 shapes and text content elements yes refer to the size of the current SVG viewport visual yes
    stroke-linecap butt | round | square butt shapes and text content elements yes N/A visual yes
    stroke-linejoin miter | round | bevel miter shapes and text content elements yes N/A visual yes
    stroke-miterlimit <miterlimit> 4 shapes and text content elements yes N/A visual yes
    stroke-opacity <opacity-value> 1 shapes and text content elements yes N/A visual yes
    stroke-width <percentage> | <length> 1 shapes and text content elements yes refer to the size of the current SVG viewport visual yes
    text-anchor start | middle | end start text content elements yes N/A visual yes
    text-decoration none | [ underline || overline || line-through || blink ] none text content elements no (see prose) N/A visual yes
    text-rendering auto | optimizeSpeed | optimizeLegibility |
    geometricPrecision
    auto text elements yes N/A visual yes
    unicode-bidi normal | embed | bidi-override normal text content elements no N/A visual no
    vector-effect non-scaling-stroke | none none graphics elements no N/A visual yes
    visibility visible | hidden | collapse visible graphics elements (including the text element) and text sub-elements (i.e., tspan, textPath and a) yes N/A visual yes
    word-spacing normal | <length> normal text content elements yes N/A visual yes
    white-space normal | pre | nowrap | pre-wrap | pre-line normal text content elements yes N/A visual yes
    writing-mode lr-tb | rl-tb | tb-rl | lr | rl | tb lr-tb text elements yes N/A visual no
    1. [1] The font, font-size-adjust and stroke-dasharray properties are animatable but do not support additive animation.
    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix J: IDL Index

    This appendix is informative, not normative.

    The following is a list of all IDL interfaces defined in this specification:

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    Appendix K: Media Type Registration for image/svg+xml

    This appendix is normative.

    K.1. Introduction

    This appendix registers a new MIME media type, "image/svg+xml" in conformance with BCP 13 and W3CRegMedia.

    K.2. Registration of media type image/svg+xml

    Type name:

    image

    Subtype name:

    svg+xml

    Required parameters:

    None.

    Optional parameters:

    charset

    Same as application/xml media type, as specified in [RFC3023] or its successors.

    Encoding considerations:

    Same as for application/xml. See [RFC3023], section 3.2 or its successors.

    Security considerations:

    As with other XML types and as noted in [RFC3023] section 10, repeated expansion of maliciously constructed XML entities can be used to consume large amounts of memory, which may cause XML processors in constrained environments to fail.

    Several SVG elements may cause arbitrary URIs to be referenced. In this case, the security issues of [RFC3986], section 7, should be considered.

    In common with HTML, SVG documents may reference external media such as images, audio, video, style sheets, and scripting languages. Scripting languages are executable content. In this case, the security considerations in the Media Type registrations for those formats shall apply.

    In addition, because of the extensibility features for SVG and of XML in general, it is possible that "image/svg+xml" may describe content that has security implications beyond those described here. However, if the processor follows only the normative semantics of the published specification, this content will be outside the SVG namespace and shall be ignored. Only in the case where the processor recognizes and processes the additional content, or where further processing of that content is dispatched to other processors, would security issues potentially arise. And in that case, they would fall outside the domain of this registration document.

    Interoperability considerations:

    The published specification describes processing semantics that dictate behavior that must be followed when dealing with, among other things, unrecognized elements and attributes, both in the SVG namespace and in other namespaces.

    Because SVG is extensible, conformant "image/svg+xml" processors must expect that content received is well-formed XML, but it cannot be guaranteed that the content is valid to a particular DTD or Schema or that the processor will recognize all of the elements and attributes in the document.

    SVG has a published Test Suite and associated implementation report showing which implementations passed which tests at the time of the report. This information is periodically updated as new tests are added or as implementations improve.

    Published specification:

    This media type registration is extracted from Appendix P of the SVG 1.1 specification.

    Applications that use this media type:

    SVG is used by Web browsers, often in conjunction with HTML; by mobile phones and digital cameras, as a format for interchange of graphical assets in desk top publishing, for industrial process visualization, display signage, and many other applications which require scalable static or interactive graphical capability.

    Additional information:
    Magic number(s):
    File extension(s):
    svg

    Note that the extension 'svgz' is used as an alias for 'svg.gz' [RFC1952], i.e. octet streams of type image/svg+xml, subsequently compressed with gzip.

    Macintosh file type code(s):
    "svg " (all lowercase, with a space character as the fourth letter).

    Note that the Macintosh file type code 'svgz' (all lowercase) is used as an alias for GZIP [RFC1952] compressed "svg ", i.e. octet streams of type image/svg+xml, subsequently compressed with gzip.

    Macintosh Universal Type Identifier code:
    org.w3c.svg conforms to public.image and to public.xml
    Windows Clipboard Name:
    "SVG Image"
    Fragment Identifiers
    For documents labeled as application/svg+xml, the fragment identifier notation is either Shorthand Pointers (formerly called barenames), the SVG-specific SVG Views syntax or a Media Fragment Identifier; all described in the fragment identifiers section of the SVG specification.
    Person & email address to contact for further information:

    Chris Lilley, Doug Schepers (member-svg-media-type@w3.org).

    Intended usage:

    COMMON

    Restrictions on usage:

    None

    Author:

    The SVG specification is a work product of the World Wide Web Consortium's SVG Working Group.

    Change controller:

    The W3C has change control over this specification.

    SVG 2 – 28 July 2016 TopContentsPreviousNextElementsAttributesProperties

    SVG 2 – 28 July 2016 TopContentsPreviousElementsAttributesProperties

    Appendix L: Changes from SVG 1.1

    This appendix is informative, not normative.

    This appendix summarizes the changes that have been made since the SVG 1.1 Second Edition Recommendation. Changes made since the last SVG 2 Working Draft are highlighted.

    L.1. Editorial changes

    A number of stylistic changes have been made to the specification to make it more readable. These include the following:

    L.2. Substantial changes

    In additional to the editorial changes listed above, the following substantial additions, changes and removals have been made.

    L.2.1. Across the whole document

    L.2.2. Concepts

    L.2.3. Rendering Model chapter

    L.2.4. Basic Data Types and Interfaces chapter

    L.2.5. Document Structure chapter

    L.2.6. Styling chapter

    L.2.7. Geometry Properties chapter

    L.2.8. Coordinate Systems, Transformations and Units chapter

    L.2.9. Paths chapter

    L.2.10. Basic Shapes chapter

    L.2.11. Text chapter

    L.2.12. Embedded Content chapter

    L.2.13. Painting chapter

    L.2.14. Color chapter

    L.2.15. Paint Servers chapter

    L.2.16. Clipping, Masking and Compositing chapter

    L.2.17. Filter Effects chapter

    L.2.18. Interactivity chapter

    L.2.19. Linking chapter

    L.2.20. Scripting chapter

    L.2.21. Animation chapter

    L.2.22. Fonts chapter

    L.2.23. Extensibility chapter

    L.2.24. Document Type Definition appendix

    L.2.25. SVG Document Object Model (DOM) appendix

    L.2.26. Java Language Binding appendix

    L.2.27. ECMAScript Language Binding appendix

    L.2.28. References appendix

    L.2.29. IDL Index appendix

    L.2.30. Feature Strings

    SVG 2 – 28 July 2016 TopContentsPreviousElementsAttributesProperties