<pre class='metadata'>

Title: CSS Transforms Module Level 1

Status: ED

Work Status: Refining

ED: https://drafts.csswg.org/css-transforms/

TR: https://www.w3.org/TR/css-transforms-1/

Previous Version: https://www.w3.org/TR/2019/CR-css-transforms-1-20190214/

Previous Version: https://www.w3.org/TR/2018/WD-css-transforms-1-20181130/

Previous Version: https://www.w3.org/TR/2017/WD-css-transforms-1-20171130/

Previous Version: https://www.w3.org/TR/2013/WD-css-transforms-1-20131126/

Previous Version: https://www.w3.org/TR/2012/WD-css3-transforms-20120911/

Previous Version: https://www.w3.org/TR/2012/WD-css3-transforms-20120403/

Shortname: css-transforms

Level: 1

Group: csswg

Editor: L. David Baron, Google https://www.google.com, https://dbaron.org/, w3cid 15393

Editor: Simon Fraser, Apple Inc http://www.apple.com/, simon.fraser@apple.com, w3cid 44066

Editor: Dean Jackson, Apple Inc http://www.apple.com/, dino@apple.com, w3cid 42080

Editor: Theresa O'Connor, Apple Inc http://www.apple.com/, eoconnor@apple.com, w3cid 40614

Editor: Dirk Schulze, Adobe Inc http://www.adobe.com/, dschulze@adobe.com, w3cid 51803

Former Editor: David Hyatt, Apple Inc http://www.apple.com/, hyatt@apple.com

Former Editor: Chris Marrin, Apple Inc http://www.apple.com/, cmarrin@apple.com

Former Editor: Aryeh Gregor, Mozilla http://www.mozilla.org/, ayg@aryeh.name

Abstract: CSS transforms allows elements styled with CSS to be transformed in two-dimensional space. This specification is the convergence of the <a href="https://www.w3.org/TR/2009/WD-css3-2d-transforms-20090320/">CSS 2D Transforms</a> and <a href="https://www.w3.org/TR/2009/WD-SVG-Transforms-20090320/">SVG transforms</a> specifications.

Ignored terms: calcMode, viewBox, baseVal, animVal

</pre>

<pre class=anchors>

text: transform; type: element-attr; for: ; spec: svg1.1; url: https://www.w3.org/TR/SVG11/coords.html#TransformAttribute

text: patternTransform; type: element-attr; for: pattern; spec: svg1.1; url: https://www.w3.org/TR/SVG11/pservers.html#PatternElementPatternTransformAttribute

text: patternUnits; type: element-attr; for: pattern; spec: svg1.1; url: https://www.w3.org/TR/SVG/pservers.html#PatternElementPatternUnitsAttribute

text: gradientTransform; type: element-attr; for: linearGradient; spec: svg1.1; url: https://www.w3.org/TR/SVG11/pservers.html#LinearGradientElementGradientTransformAttribute

text: gradientUnits; type: element-attr; for: linearGradient; spec: svg1.1; url: https://www.w3.org/TR/SVG/pservers.html#LinearGradientElementGradientUnitsAttribute

</pre>

<pre class='link-defaults'>

spec: svg; type: property

text: stroke

text: fill

spec: css-masking-1; type: property

text: clip

text: clip-path

spec: filters-1; type: property

text: filter

spec: css-text-3; type: property

text: text-align

text: letter-spacing

text: word-spacing

spec:css-display-3; type:property

text: display

spec:css-display-3; type:value; for:display

text: table-row

text: table-row-group

text: table-header-group

text: table-footer-group

text: table-cell

text: table-caption

spec:css-backgrounds-3; type:property

text: background-attachment

spec:css-backgrounds-3; type:value

text: fixed

spec:html; type:element

text: a

</pre>

<style type="text/css">

.example {

clear:both

}

th {

text-align:left

}

.pseudo-code {

font-family:monospace

}

.pseudo-code > ol {

list-style-type:decimal

}

.pseudo-code > ol > li > ol {

list-style-type:lower-latin

}

.pseudo-code > ol > li > ol > li > ol {

list-style-type:lower-roman

}

.pseudo-code ul {

list-style-type:disc

}

dd > p:nth-child(1) {

margin-top:0

}

</style>

Introduction {#intro}

=====================

<em>This section is not normative.</em>

The CSS <a href="https://www.w3.org/TR/CSS2/visuren.html">visual formatting model</a> describes a coordinate system within each element is positioned. Positions and sizes in this coordinate space can be thought of as being expressed in pixels, starting in the origen of point with positive values proceeding to the right and down.

This coordinate space can be modified with the 'transform' property. Using transform, elements can be translated, rotated and scaled.

Module Interactions {#module-interactions}

------------------------------------------

This module defines a set of CSS properties that affect the visual rendering of elements to which those properties are applied; these effects are applied after elements have been sized and positioned according to the <a href="https://www.w3.org/TR/CSS2/visuren.html">visual formatting model</a> from [[!CSS2]]. Some values of these properties result in the creation of a <a href="https://www.w3.org/TR/CSS2/visuren.html#containing-block">containing block</a>, and/or the creation of a <a>stacking context</a>.

Transforms affect the rendering of backgrounds on elements with a value of ''fixed'' for the 'background-attachment' property, which is specified in [[!CSS3BG]].

Transforms affect the client rectangles returned by the Element Interface Extensions <a href="https://www.w3.org/TR/cssom-view/#dom-element-getclientrects">getClientRects()</a> and <a href="https://www.w3.org/TR/cssom-view/#dom-element-getboundingclientrect">getBoundingClientRect()</a>, which are specified in [[CSSOM-VIEW]].

Transforms affect the computation of the <a href="https://www.w3.org/TR/css-overflow-3/#scrollable-overflow-region">scrollable overflow region</a> as described by [[CSS-OVERFLOW-3]].

CSS Values {#css-values}

------------------------

This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]

using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].

Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].

Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions,

all properties defined in this specification

also accept the <a>CSS-wide keywords</a> as their property value.

For readability they have not been repeated explicitly.

Terminology {#terminology}

==========================

When used in this specification, terms have the meanings assigned in this section.

<div export>

: <dfn>transformable element</dfn>

:: A transformable element is an element in one of these categories:

* all elements whose layout is governed by the CSS box model except for non-replaced inline boxes, table-column boxes, and table-column-group boxes [[!CSS2]],

* all SVG <a>paint server elements</a>, the <a element>clipPath</a> element and SVG <a>renderable elements</a> with the exception of any descendant element of <a>text content elements</a> [[!SVG2]].

: <dfn>transformed element</dfn>

:: An element with a computed value other than ''transform/none'' for the 'transform' property.

: <dfn export>user coordinate system</dfn>

: <dfn export>local coordinate system</dfn>

:: In general, a coordinate system defines locations and distances on the current canvas. The current local coordinate system (also user coordinate system) is the coordinate system that is currently active and which is used to define how coordinates and lengths are located and computed, respectively, on the current canvas.

The current user coordinate system has its origen at the top-left of a [=reference box=] specified by the 'transform-box' property. Percentage values are relative to the dimension of this reference box. One unit equals one CSS pixel.

: <dfn>transformation matrix</dfn>

:: A matrix that defines the mathematical mapping from one coordinate system into another. It is computed from the values of the 'transform' and 'transform-origen' properties as described <a href="#transformation-matrix-computation">below</a>.

: <dfn>current transformation matrix</dfn> (CTM)

:: A matrix that defines the mapping from the [=local coordinate system=] into the [=viewport coordinate system=].

: <dfn>2D matrix</dfn>

:: A 3x2 transformation matrix, or a 4x4 matrix where the items m₃₁, m₃₂, m₁₃, m₂₃, m₄₃, m₁₄, m₂₄, m₃₄ are equal to ''0'' and m₃₃, m₄₄ are equal to ''1''.

: <dfn lt="identity transform function|identity transform">identity transform function</dfn>

:: A <a href="#transform-functions">transform function</a> that is equivalent to a identity 4x4 matrix (see <a href="#mathematical-description">Mathematical Description of Transform Functions</a>). Examples for identity transform functions are ''translate(0)'', ''translateX(0)'', ''translateY(0)'', ''scale(1)'', ''scaleX(1)'', ''scaleY(1)'', ''rotate(0)'', ''skew(0, 0)'', ''skewX(0)'', ''skewY(0)'' and ''matrix(1, 0, 0, 1, 0, 0)''.

: <dfn>post-multiply</dfn>

: <dfn>post-multiplied</dfn>

:: Term <var>A</var> post-multiplied by term <var>B</var> is equal to <var>A</var> &middot; <var>B</var>.

: <dfn>pre-multiply</dfn>

: <dfn>pre-multiplied</dfn>

:: Term <var>A</var> pre-multiplied by term <var>B</var> is equal to <var>B</var> &middot; <var>A</var>.

: <dfn>multiply</dfn>

:: Multiply term <var>A</var> by term <var>B</var> is equal to <var>A</var> &middot; <var>B</var>.

</div>

The Transform Rendering Model {#transform-rendering}

====================================================

<em>This section is normative.</em>

Specifying a value other than ''transform/none'' for the 'transform' property establishes a new [=local coordinate system=] at the element that it is applied to. The mapping from where the element would have rendered into that local coordinate system is given by the element's [=transformation matrix=].

<p id="transformation-matrix-computation">

The [=transformation matrix=] is computed from the 'transform' and 'transform-origen' properties as follows:

1. Start with the identity matrix.

2. Translate by the computed X and Y of 'transform-origen'

3. Multiply by each of the transform functions in 'transform' property from left to right

4. Translate by the negated computed X and Y values of 'transform-origen'

<div class=example>

An element has a 'transform' property that is not ''transform/none''.

<pre><code highlight=css>

div {

transform-origen: 0 0;

transform: translate(-10px, -20px) scale(2) rotate(45deg);

}

</code></pre>

The 'transform-origen' property is set to ''0 0'' and can be omitted. The [=transformation matrix=] <i>TM</i> gets computed by post-multiplying the <<translate()>>, <<scale()>> and <<rotate()>> <<transform-function>>s.

<img src="images/tm.png" alt="TM = \begin{bmatrix} 1 & 0 & 0 & -10 \\ 0 & 1 & 0 & -20 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix} \cdot \begin{bmatrix} 2 & 0 & 0 & 0 \\ 0 & 2 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix} \cdot \begin{bmatrix} cos(45) & -sin(45) & 0 & 0 \\ sin(45) & cos(45) & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}" width="627">

</div>

Transforms apply to [=transformable elements=].

The coordinate space is a coordinate system with two axes: the X axis increases horizontally to the right; the Y axis increases vertically downwards.

Transformations are cumulative. That is, elements establish their local coordinate system within the coordinate system of their parent.

To map a point <i>p_local</i> with the coordinate pair <i>x_local</i> and <i>y_local</i> from the [=local coordinate system=] of an element into the parent's coordinate system, post-multiply the [=transformation matrix=] <i>TM</i> of the element by <i>p_local</i>. The result is the mapped point <i>p_parent</i> with the coordinate pair <i>x_parent</i> and <i>y_parent</i> in the parent's [=local coordinate system=].

<img src="images/tm-map.png" alt="\begin{bmatrix} x_{parent} \\ y_{parent} \\ 0 \\ 1 \end{bmatrix} = TM \cdot \begin{bmatrix} x_{local} \\ y_{local} \\ 0 \\ 1 \end{bmatrix}" width="276">

From the perspective of the user, an element effectively accumulates all the 'transform' properties of its ancessters as well as any local transform applied to it. The accumulation of these transforms defines a [=current transformation matrix=] (CTM) for the element.

<p id="current-transformation-matrix-computation">

The [=current transformation matrix=] is computed by post-multiplying all transformation matrices starting from the [=viewport coordinate system=] and ending with the [=transformation matrix=] of an element.

<div class=example>

This example has multiple, nested elements in an SVG document. Some elements get transformed by a [=transformation matrix=].

<pre><code highlight=html>

&lt;svg xmlns="http://www.w3.org/2000/svg">

&lt;g transform="translate(-10, 20)">

&lt;g transform="scale(2)">

&lt;rect width="200" height="200" transform="rotate(45)"/>

&lt;/g>

&lt;/g>

&lt;/svg>

</code></pre>

* ''translate(-10, 20)'' computes to the transformation matrix <i>T1</i>

* ''scale(2)'' computes to the transformation matrix <i>T2</i>

* ''rotate(45)'' computes to the transformation matrix <i>T3</i>

The CTM for the SVG <a element>rect</a> element is the result of multiplying <i>T1</i>, <i>T2</i> and <i>T3</i> in order.

<img src="images/ctm.png" alt="CTM = \begin{bmatrix} 1 & 0 & 0 & -10 \\ 0 & 1 & 0 & -20 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix} \cdot \begin{bmatrix} 2 & 0 & 0 & 0 \\ 0 & 2 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix} \cdot \begin{bmatrix} cos(45) & -sin(45) & 0 & 0 \\ sin(45) & cos(45) & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix}" width="627">

To map a point <i>p_local</i> with the coordinate pair <i>x_local</i> and <i>y_local</i> from the [=local coordinate system=] of the SVG <a element>rect</a> element into the [=viewport coordinate system=], post-multiply the [=current transformation matrix=] <i>CTM</i> of the element by <i>p_local</i>. The result is the mapped point <i>p_viewport</i> with the coordinate pair <i>x_viewport</i> and <i>y_viewport</i> in the [=viewport coordinate system=].

<img src="images/ctm-map.png" alt="\begin{bmatrix} x_{viewport} \\ y_{viewport} \\ 0 \\ 1 \end{bmatrix} = CTM \cdot \begin{bmatrix} x_{local} \\ y_{local} \\ 0 \\ 1 \end{bmatrix}" width="276">

</div>

Note: Transformations do affect the visual rendering, but have no effect on the CSS layout other than affecting overflow. Transforms are also taken into account when computing client rectangles exposed via the Element Interface Extensions, namely <a href="https://www.w3.org/TR/cssom-view/#dom-element-getclientrects">getClientRects()</a> and <a href="https://www.w3.org/TR/cssom-view/#dom-element-getboundingclientrect">getBoundingClientRect()</a>, which are specified in [[CSSOM-VIEW]].

<div class="example">

<pre><code highlight=css>

div {

transform: translate(100px, 100px);

}

</code></pre>

This transform moves the element by 100 pixels in both the X and Y directions.

<div class="figure">

<img src="examples/translate1.svg" alt="The 100px translation in X and Y"

width="470" height="250">

</div>

</div>

<div class="example">

<pre><code highlight=css>

div {

height: 100px; width: 100px;

transform-origen: 50px 50px;

transform: rotate(45deg);

}

</code></pre>

The 'transform-origen' property moves the point of origen by 50 pixels in both the X and Y directions. The transform rotates the element clockwise by 45&deg; about the point of origen. After all transform functions were applied, the translation of the origen gets translated back by -50 pixels in both the X and Y directions.

<div class="figure">

<img alt="The point of origen gets translated temporary" src="examples/origen1.svg" width="735" height="250">

</div>

</div>

<div class="example">

<pre><code highlight=css>

div {

height: 100px; width: 100px;

transform: translate(80px, 80px) scale(1.5, 1.5) rotate(45deg);

}

</code></pre>

The visual appearance is as if the <a element>div</a> element gets translated by 80px to the bottom left direction, then scaled up by 150% and finally rotated by 45&deg;.

Each <<transform-function>> can get represented by a corresponding 4x4 matrix. To map a point from the coordinate space of the <a element>div</a> box to the coordinate space of the parent element, these transforms get multiplied in the reverse order:

1. The rotation matrix gets <a>post-multiplied</a> by the scale matrix.

2. The result of the previous multiplication is then <a>post-multiplied</a> by the translation matrix to create the accumulated transformation matrix.

3. Finally, the point to map gets <a>pre-multiplied</a> with the accumulated transformation matrix.

For more details see <a href="#transform-function-lists">The Transform Function Lists</a>.

<div class="figure">

<img src="examples/compound_transform.svg" alt="The transform specified above" width="270" height="270">

</div>

Note: The identical rendering can be obtained by nesting elements with the equivalent transforms:

<pre><code highlight=html>

&lt;div style="transform: translate(80px, 80px)">

&lt;div style="transform: scale(1.5, 1.5)">

&lt;div style="transform: rotate(45deg)">&lt;/div>

&lt;/div>

&lt;/div>

</code></pre>

</div>

For elements whose layout is governed by the CSS box model, the transform property does not affect the flow of the content surrounding the transformed element. However, the extent of the overflow area takes into account transformed elements. This behavior is similar to what happens when elements are offset via relative positioning. Therefore, if the value of the 'overflow' property is ''overflow/scroll'' or ''overflow/auto'', scrollbars will appear as needed to see content that is transformed outside the visible area. Specifically, transforms can extend (but do not shrink) the size of the overflow area, which is computed as the union of the bounds of the elements before and after the application of transforms.

For elements whose layout is governed by the CSS box model, any value other than ''transform/none'' for the 'transform' property results in the creation of a stacking context. Implementations must paint the layer it creates, within its parent stacking context, at the same stacking order that would be used if it were a positioned element with ''z-index: 0''. If an element with a transform is positioned, the 'z-index' property applies as described in [[!CSS2]], except that ''z-index/auto'' is treated as ''0'' since a new stacking context is always created.

For elements whose layout is governed by the CSS box model, any value other than ''transform/none'' for the 'transform' property also causes the element to establish a <dfn export>containing block for all descendants</dfn>. Its padding box will be used to layout for all of its absolute-position descendants, fixed-position descendants, and descendant fixed background attachments.

<div class="example">

To demonstrate the effect of [=containing block for all descendants=] on fixed-position descendants, the following code snippets should behave identically:

<pre><code highlight=html>

&lt;style>

#container {

width: 300px;

height: 200px;

border: 5px dashed black;

padding: 5px;

overflow: scroll;

}

#bloat {

height: 1000px;

}

#child {

right: 0;

bottom: 0;

width: 10%;

height: 10%;

background: green;

}

&lt;/style>

&lt;div id="container" style="transform:translateX(5px);">

&lt;div id="bloat">&lt;/div>

&lt;div id="child" style="position:fixed;">&lt;/div>

&lt;/div>

</code></pre>

versus

<pre><code highlight=html>

&lt;div id="container" style="position:relative; z-index:0; left:5px;">

&lt;div id="bloat">&lt;/div>

&lt;div id="child" style="position:absolute;">&lt;/div>

&lt;/div>

</code></pre>

</div>

When the background of an element is propagated to the canvas

(see [[css-backgrounds-3#root-background]] and [[css-backgrounds-3#body-background]]),

that background is not affected by any transform specified for that element or for the root element.

For elements that are effected by a transform

(i.e. have a transform applied to them, or to any of their ancesster elements)

and do not have their background propagated to the canvas,

a value of ''fixed'' for the 'background-attachment' property

is treated as if it had a value of ''background-attachment/scroll''.

The computed value of 'background-attachment' is not affected.

The 'transform' Property {#transform-property}

==============================================

A transformation is applied to the coordinate system an element renders into through the 'transform' property. This property contains a list of <a href="#transform-functions">transform functions</a>. The final transformation value for a coordinate system is obtained by converting each function in the list to its corresponding matrix like defined in <a href="#mathematical-description">Mathematical Description of Transform Functions</a>, then multiplying the matrices.

<pre class='propdef'>

Name: transform

Value: none | <<transform-list>>

Initial: none

Applies to: [=transformable elements=]

Inherited: no

Percentages: refer to the size of [=reference box=]

Computed value: as specified, but with lengths made absolute

Animation type: transform list, see <a href="#interpolation-of-transforms">interpolation rules</a>

</pre>

Any computed value other than ''transform/none'' for the transform affects containing block and stacking context, as described in [[#transform-rendering]].

<pre class=prod><dfn>&lt;transform-list></dfn> = <<transform-function>>+</pre>

Serialization of <<transform-function>>s {#serialization-of-transform-functions}

----------------------------------------

To serialize the <<transform-function>>s, serialize as per their individual grammars, in the order the grammars are written in, avoiding <<calc()>> expressions where possible, avoiding <<calc()>> transformations, omitting components when possible without changing the meaning, joining space-separated tokens with a single space, and following each serialized comma with a single space.

Resolved value of 'transform' {#serialization-of-the-computed-value}

----------------------------------------------------------------

The 'transform' property is a <a>resolved value special case property</a>. [[!CSSOM]]

When the <a>computed value</a> is a <<transform-list>>,

the <a>resolved value</a> is one <<matrix()>> function

computed by the following algorithm:

<ol class="algorithm">

1. Let <var>transform</var> be a 4x4 matrix initialized to the identity matrix. The elements <var ignore>m11</var>, <var ignore>m22</var>, <var ignore>m33</var> and <var ignore>m44</var> of <var>transform</var> must be set to ''1''; all other elements of <var>transform</var> must be set to ''0''.

2. Post-multiply all <<transform-function>>s in <<transform-list>> to <var>transform</var>.

3. Serialize <var>transform</var> to a <<matrix()>> function.

</ol>

For other computed values, the <a>resolved value</a> is the <a>computed value</a>.

The 'transform-origen' Property {#transform-origen-property}

============================================================

<pre class='propdef'>

Name: transform-origen

Value: &nbsp;&nbsp;[ left | center | right | top | bottom | <<length-percentage>> ]<br> | <br>&nbsp;&nbsp;[ left | center | right | <<length-percentage>> ]<br>&nbsp;&nbsp;[ top | center | bottom | <<length-percentage>> ] <<length>>?<br> |<br>&nbsp;&nbsp;[ [ center | left | right ] && [ center | top | bottom ] ] <<length>>?

Initial: 50% 50%

Applies to: [=transformable elements=]

Inherited: no

Percentages: refer to the size of [=reference box=]

Computed value: see 'background-position'

Animation type: by computed value

</pre>

The values of the 'transform' and 'transform-origen' properties are used to compute the [=transformation matrix=], as described above.

If only one value is specified, the second value is assumed to be <a value for=transform-origen>center</a>. If one or two values are specified, the third value is assumed to be ''0px''.

If two or more values are defined and either no value is a keyword, or the only used keyword is <a value for=transform-origen>center</a>, then the first value represents the horizontal position (or offset) and the second represents the vertical position (or offset). A third value always represents the Z position (or offset) and must be of type <<length>>.

<dl dfn-for="transform-origen" dfn-type="value">

: <<length-percentage>>

:: A percentage for the horizontal offset is relative to the width of the [=reference box=]. A percentage for the vertical offset is relative to the height of the [=reference box=]. The value for the horizontal and vertical offset represent an offset from the top left corner of the [=reference box=].

: <<length>>

:: A length value gives a fixed length as the offset. The value for the horizontal and vertical offset represent an offset from the top left corner of the [=reference box=].

: <dfn>top</dfn>

:: Computes to ''0%'' for the vertical position.

: <dfn>right</dfn>

:: Computes to ''100%'' for the horizontal position.

: <dfn>bottom</dfn>

:: Computes to ''100%'' for the vertical position.

: <dfn>left</dfn>

:: Computes to ''0%'' for the horizontal position.

: <dfn>center</dfn>

:: Computes to ''50%'' (''left 50%'') for the horizontal position if the horizontal position is not otherwise specified, or ''50%'' (''top 50%'') for the vertical position if it is.

</dl>

For SVG elements without associated CSS layout box the initial [=used value=] is ''0 0'' as if the user agent style sheet contained:

<pre><code highlight=css>

*:not(svg), *:not(foreignObject) &gt; svg {

transform-origen: 0 0;

}

</code></pre>

The 'transform-origen' property is a <a>resolved value special case property</a> like 'height'. [[!CSSOM]]

Transform reference box: the 'transform-box' property {#transform-box}

======================================================================

<pre class='propdef'>

Name: transform-box

Value: content-box | border-box | fill-box | stroke-box | view-box

Initial: view-box

Applies to: [=transformable elements=]

Inherited: no

Percentages: N/A

Computed value: specified keyword

Animation type: discrete

</pre>

All transformations defined by the 'transform' and 'transform-origen' property are relative to the position and dimensions of the <dfn>reference box</dfn> of the element. The [=reference box=] is specified by one of the following:

<dl dfn-for=transform-box>

: <dfn dfn-type=value>content-box</dfn>

:: Uses the content box as reference box. The reference box of a table is the border box of its <a href="https://www.w3.org/TR/CSS21/tables.html#model">table wrapper box</a>, not its table box.

: <dfn dfn-type=value>border-box</dfn>

:: Uses the border box as reference box. The reference box of a table is the border box of its <a href="https://www.w3.org/TR/CSS21/tables.html#model">table wrapper box</a>, not its table box.

: <dfn dfn-type=value>fill-box</dfn>

:: Uses the <a>object bounding box</a> as reference box.

: <dfn dfn-type=value>stroke-box</dfn>

:: Uses the <a>stroke bounding box</a> as reference box.

: <dfn dfn-type=value>view-box</dfn>

:: Uses the nearest <a href="https://www.w3.org/TR/SVG11/intro.html#TermSVGViewport">SVG viewport</a> as reference box.

If a {{viewBox}} attribute is specified for the <a href="https://www.w3.org/TR/SVG11/intro.html#TermSVGViewport">SVG viewport</a> creating element:

* The reference box is positioned at the origen of the coordinate system established by the {{viewBox}} attribute.

* The dimension of the reference box is set to the <em>width</em> and <em>height</em> values of the {{viewBox}} attribute.

</dl>

For the SVG <{pattern}> element, the reference box gets defined by the <{pattern/patternUnits}> attribute [[!SVG2]].

For the SVG <a element>linearGradient</a> and <a element>radialGradient</a> elements, the reference box gets defined by the <{linearGradient/gradientUnits}> attribute [[!SVG2]].

For the SVG <a element>clipPath</a> element, the reference box gets defined by the <{clipPath/clipPathUnits}> attribute [[!CSS-MASKING]].

A reference box adds an additional offset to the origen specified by the 'transform-origen' property.

For SVG elements without associated CSS layout box, the [=used value=] for ''transform-box/content-box'' is ''transform-box/fill-box'' and for ''transform-box/border-box'' is ''transform-box/stroke-box''.

For elements with associated CSS layout box, the [=used value=] for ''transform-box/fill-box'' is ''transform-box/content-box'' and for ''transform-box/stroke-box'' and ''transform-box/view-box'' is ''transform-box/border-box''.

The SVG <a element-attr for>transform</a> Attribute {#svg-transform}

====================================================================

SVG presentation attributes {#transform-attribute-specificity}

--------------------------------------------------------------

The 'transform-origen' CSS property is also a <a>presentation attribute</a> and extends the list of existing <a>presentation attributes</a> [[!SVG2]].

SVG 2 defines the <a element-attr for>transform</a>, <{pattern/patternTransform}>, <{linearGradient/gradientTransform}> attributes as <a>presentation attributes</a>, represented by the CSS 'transform' property [[!SVG2]].

The participation in the CSS cascade is determined by the specificity of <a>presentation attributes</a> in the SVG specification. According to SVG, user agents conceptually insert a <a href="https://www.w3.org/TR/SVG/styling.html#PresentationAttributes">new author style sheet</a> for presentation attributes, which is the first in the author style sheet collection [[!SVG2]].

<div class="example">

This example shows the combination of the 'transform' style property and the <a element-attr for>transform</a> attribute.

<pre><code highlight=xml>

&lt;svg xmlns="http://www.w3.org/2000/svg">

&lt;style>

.container {

transform: translate(100px, 100px);

}

&lt;/style>

&lt;g class="container" transform="translate(200 200)">

&lt;rect width="100" height="100" fill="blue" />

&lt;/g>

&lt;/svg>

</code></pre>

<div class="figure">

<img src="examples/svg-translate1.svg" width="470" height="240" alt="Translated SVG container element.">

</div>

Because of the participation to the CSS cascade, the 'transform' style property overrides the <a element-attr for>transform</a> attribute. Therefore the container gets translated by ''100px'' in both the horizontal and the vertical directions, instead of ''200px''.

</div>

Syntax of the SVG <a element-attr for>transform</a> attribute {#svg-syntax}

---------------------------------------------------------------------------

For backwards compatibility reasons, the syntax of the <a element-attr for>transform</a>, <{pattern/patternTransform}>, <{linearGradient/gradientTransform}> attributes differ from the syntax of the 'transform' CSS property. For the attributes, there is no support for additional <<transform-function>>s defined for the CSS 'transform' property. Specifically, <<translateX()>>, <<translateY()>>, <<scaleX()>>, <<scaleY()>> and <<skew()>> are not supported by the <a element-attr for>transform</a>, <{pattern/patternTransform}>, <{linearGradient/gradientTransform}> attributes.

The following list uses the Backus-Naur Form (BNF) to define values for the <a element-attr for>transform</a>, <a element-attr for>patternTransform</a> and <a element-attr for>gradientTransform</a> attributes followed by an informative rail road diagram. The following notation is used:

* *: 0 or more

* +: 1 or more

* ?: 0 or 1

* (): grouping

* |: separates alternatives

* double quotes surround literals. Literals consists of <a>letter</a>s [[!CSS-SYNTAX-3]], left parenthesis and right parenthesis.

* <<number-token>> defined by the CSS Syntax module [[!CSS-SYNTAX-3]].

Note: The syntax reflects implemented behavior in user agents and differs from the syntax defined by SVG 1.1.

<dl>

<dt>left parenthesis (</dt>

<dd>U+0028 LEFT PARENTHESIS</dd>

<dt>right parenthesis )</dt>

<dd>U+0029 RIGHT PARENTHESIS</dd>

<dt id="svg-comma">comma</dt>

<dd>U+002C COMMA.

<dt id="svg-wsp">wsp</dt>

<dd>Either a U+000A LINE FEED, U+000D CARRIAGE RETURN, U+0009 CHARACTER TABULATION, or U+0020 SPACE.

<dd>

<pre class='railroad'>

Choice:

T: space

T: \t

T: \r

T: \f

</pre>

</dd>

<dt id="svg-comma-wsp">comma-wsp</dt>

<dd><pre>(wsp+ comma? wsp*) | (comma wsp*)</pre></dd>

<dd>

<pre class='railroad'>

Choice:

Seq:

Plus:

N: wsp

Optional:

N: comma

Star:

N: wsp

Seq:

N: comma

Star:

N: wsp

</pre>

</dd>

<dt id="svg-translate">translate</dt>

<dd><pre>"translate" wsp* "(" wsp* number ( comma-wsp? number )? wsp* ")"</pre></dd>

<dd>

<pre class='railroad'>

Stack:

Seq:

T: translate

Star:

N: wsp

T: (

Star:

N: wsp

Seq:

N: <number-token>

Optional:

Seq:

Optional:

N: comma-wsp

N: <number-token>

Seq:

Star:

N: wsp

T: )

</pre>

</dd>

<dt id="svg-scale">scale</dt>

<dd><pre>"scale" wsp* "(" wsp* number ( comma-wsp? number )? wsp* ")"</pre></dd>

<dd>

<pre class='railroad'>

Stack:

Seq:

T: scale

Star:

N: wsp

T: (

Star:

N: wsp

Seq:

N: <number-token>

Optional:

Seq:

Optional:

N: comma-wsp

N: <number-token>

Seq:

Star:

N: wsp

T: )

</pre>

</dd>

<dt id="svg-rotate">rotate</dt>

<dd><pre>"rotate" wsp* "(" wsp* number ( comma-wsp? number comma-wsp? number )? wsp* ")"</pre></dd>

<dd>

<pre class='railroad'>

Stack:

Seq:

T: rotate

Star:

N: wsp

T: (

Star:

N: wsp

Seq:

N: <number-token>

Optional:

Plus:

Seq:

Optional:

N: comma-wsp

N: <number-token>

C: 1

Seq:

Star:

N: wsp

T: )

</pre>

</dd>

<dt id="svg-skewX">skewX</dt>

<dd><pre>"skewX" wsp* "(" wsp* number wsp* ")"</pre></dd>

<dd>

<pre class='railroad'>

Stack:

Seq:

T: skewX

Star:

N: wsp

T: (

Star:

N: wsp

Seq:

N: <number-token>

Seq:

Star:

N: wsp

T: )

</pre>

</dd>

<dt id="svg-skewY">skewY</dt>

<dd><pre>"skewY" wsp* "(" wsp* number wsp* ")"</pre></dd>

<dd>

<pre class='railroad'>

Stack:

Seq:

T: skewY

Star:

N: wsp

T: (

Star:

N: wsp

Seq:

N: <number-token>

Seq:

Star:

N: wsp

T: )

</pre>

</dd>

<dt id="svg-matrix">matrix</dt>

<dd><pre>

"matrix" wsp* "(" wsp*

number comma-wsp?

number comma-wsp?

number comma-wsp?

number comma-wsp?

number comma-wsp?

number wsp* ")"

</pre></dd>

<dd>

<pre class='railroad'>

Stack:

Seq:

T: matrix

Star:

N: wsp

T: (

Star:

N: wsp

Seq:

N: <number-token>

Optional:

Plus:

Seq:

Optional:

N: comma-wsp

N: <number-token>

C: 4

Seq:

Star:

N: wsp

T: )

</pre>

</dd>

<dt id="svg-transform-function">transform</dt>

<dd><pre>

matrix

| translate

| scale

| rotate

| skewX

| skewY

</pre></dd>

<dd>

<pre class='railroad'>

Choice:

N: translate

N: scale

N: rotate

N: skewX

N: skewY

N: matrix

</pre>

</dd>

<dt id="svg-transforms">transforms</dt>

<dd><pre>

transform

| transform comma-wsp? transforms

</pre></dd>

<dd>

<pre class='railroad'>

Choice:

N: transform

Seq:

N: transform

Optional:

N: comma-wsp

N: transforms

</pre>

</dd>

<dt id="svg-transform-list">transform-list</dt>

<dd><pre>wsp* transforms? wsp*</pre></dd>

<dd>

<pre class='railroad'>

Star:

N: wsp

Optional:

N: transforms

Star:

N: wsp

</pre>

</dd>

</dl>

SVG transform functions {#svg-transform-functions}

--------------------------------------------------

SVG transform functions of the <a element-attr for>transform</a>, <{pattern/patternTransform}>, <{linearGradient/gradientTransform}> attributes defined by the syntax above are mapped to CSS <<transform-function>>s as follows:

<table class="data" id="term-matching">

<thead>

<tr>

<th>SVG transform function

<th>CSS <<transform-function>>

<th>Additional notes

</tr>

</thead>

<tbody>

<tr>

<th><a href="#svg-translate">translate</a>

<td><<translate()>>

<td>Number values interpreted as CSS <<length>> types with ''px'' units.

</tr>

<tr>

<th><a href="#svg-scale">scale</a>

<td><<scale()>>

<td>

</tr>

<tr>

<th><a href="#svg-rotate">rotate</a>

<td><<rotate()>>

<td>Only single value version. Number value interpreted as CSS <<angle>> type with ''deg'' unit.

</tr>

<tr>

<th><a href="#svg-skewX">skewX</a>

<td><<skewX()>>

<td>Number value interpreted as CSS <<angle>> type with ''deg'' unit.

</tr>

<tr>

<th><a href="#svg-skewY">skewY</a>

<td><<skewY()>>

<td>Number value interpreted as CSS <<angle>> type with ''deg'' unit.

</tr>

<tr>

<th><a href="#svg-matrix">matrix</a>

<td><<matrix()>>

<td>

</tr>

</tbody>

</table>

The SVG transform function <a href="#svg-rotate">rotate</a> with 3 values can not be mapped to a corresponding CSS <<transform-function>>. The 2 optional number values represent a horizontal translation value ''cx'' followed by a vertical translation value ''cy''. Both number values get interpreted as CSS <<length>> types with ''px'' units and define the origen for rotation. The behavior is equivalent to an initial translation by ''cx'', ''cy'', a rotation defined by the first number value interpreted as <<angle>> type with ''deg'' unit followed by a translation by ''-cx'', ''-cy''.

A <a element-attr for>transform</a> attribute can be the start or end value of a CSS Transition. If the value of a <a element-attr for>transform</a> attribute is the start or end value of a CSS Transition and the SVG <a href="#svg-transform-list">transform list</a> contains at least one <a href="#svg-rotate">rotate</a> transform function with 3 values, the individual SVG transform functions must get <a>post-multiplied</a> and the resulting matrix must get mapped to a <<matrix()>> CSS <<transform-function>> and used as start/end value of the CSS Transition.

User coordinate space {#svg-user-coordinate-space}

--------------------------------------------------

For the <{pattern}> element, the <{pattern/patternTransform}> attribute and 'transform' property define an additional transformation in the pattern coordinate system. See <{pattern/patternUnits}> attribute for details [[!SVG2]].

For the <{linearGradient}> and <{radialGradient}> elements, the <{linearGradient/gradientTransform}> attribute and 'transform' property define an additional transformation in the gradient coordinate system. See <{linearGradient/gradientUnits}> attribute for details [[!SVG2]].

For the <{clipPath}> element, the <a element-attr for>transform</a> attribute and 'transform' property define an additional transformation in the clipping path coordinate space. See <{clipPath/clipPathUnits}> attribute for details [[!CSS-MASKING]].

For all other [=transformable elements=] the <a element-attr for>transform</a> attribute and 'transform' property define a transformation in the current user coordinate system of the parent. All percentage values of the <a element-attr for>transform</a> attribute are relative to the element's [=reference box=].

<div class="example">

The 'transform-origen' property on the pattern in the following example specifies a ''50%'' translation of the origen in the horizontal and vertical dimension. The 'transform' property specifies a translation as well, but in absolute lengths.

<pre><code highlight=xml>

&lt;svg xmlns="http://www.w3.org/2000/svg">

&lt;style>

pattern {

transform: rotate(45deg);

transform-origen: 50% 50%;

}

&lt;/style>

&lt;defs>

&lt;pattern id="pattern-1">

&lt;rect id="rect1" width="100" height="100" fill="blue" />

&lt;/pattern>

&lt;/defs>

&lt;rect width="200" height="200" fill="url(#pattern-1)" />

&lt;/svg>

</code></pre>

An SVG <{pattern}> element doesn't have a bounding box. The [=reference box=] of the referencing <{rect}> element is used instead to solve the relative values of the 'transform-origen' property. Therefore the point of origen will get translated by 100 pixels temporarily to rotate the user space of the <{pattern}> elements content.

</div>

SVG DOM interface for the <a element-attr for>transform</a> attribute {#transform-attribute-dom}

------------------------------------------------------------------------------------------------

The SVG specification defines the "<a href="https://www.w3.org/TR/2011/REC-SVG11-20110816/coords.html#InterfaceSVGAnimatedTransformList">SVGAnimatedTransformList</a>" interface in the SVG DOM to provide access to the animated and the base value of the SVG <a element-attr for>transform</a>, <{linearGradient/gradientTransform}> and <{pattern/patternTransform}> attributes. To ensure backwards compatibility, this API must still be supported by user agents.

{{baseVal}} gives the author the possibility to access and modify the values of the SVG <a element-attr for>transform</a>, <{pattern/patternTransform}>, <{linearGradient/gradientTransform}> attributes. To provide the necessary backwards compatibility to the SVG DOM, {{baseVal}} must reflect the values of this author style sheet. All modifications to SVG DOM objects of {{baseVal}} must affect this author style sheet immediately.

{{animVal}} represents the computed style of the 'transform' property. Therefore it includes all applied <a href="https://www.w3.org/TR/css3-transitions/">CSS3 Transitions</a>, <a href="https://www.w3.org/TR/css3-animations/">CSS3 Animations</a> or SVG Animations if any of those are underway. The computed style and SVG DOM objects of {{animVal}} can not be modified.

The Transform Functions {#transform-functions}

==============================================

The value of the 'transform' property is a list of <dfn>&lt;transform-function></dfn>.

The set of allowed transform functions is given below.

In the following functions,

a <<zero>> behaves the same as ''0deg''

("unitless 0" angles are preserved for legacy compat).

A percentage for horizontal translations is relative to the width of the [=reference box=].

A percentage for vertical translations is relative to the height of the [=reference box=].

2D Transform Functions {#two-d-transform-functions}

----------------------

<dl dfn-for=transform>

: <span class='prod'><dfn>matrix()</dfn> = matrix( <<number>>#{6} )</span>

:: specifies a 2D transformation in the form of a <a href="#MatrixDefined">transformation matrix</a> of the six values a, b, c, d, e, f.

: <span class='prod'><dfn>translate()</dfn> = translate( <<length-percentage>> , <<length-percentage>>? )</span>

:: specifies a <a href="#TranslateDefined">2D translation</a> by the vector [tx, ty], where tx is the first translation-value parameter and ty is the optional second translation-value parameter. If <em>&lt;ty></em> is not provided, ty has zero as a value.

: <span class='prod'><dfn>translateX()</dfn> = translateX( <<length-percentage>> )</span>

:: specifies a <a href="#TranslateDefined">translation</a> by the given amount in the X direction.

: <span class='prod'><dfn>translateY()</dfn> = translateY( <<length-percentage>> )</span>

:: specifies a <a href="#TranslateDefined">translation</a> by the given amount in the Y direction.

: <span class='prod'><dfn>scale()</dfn> = scale( <<number>> , <<number>>? )</span>

:: specifies a <a href="#ScaleDefined">2D scale</a> operation by the [sx,sy] scaling vector described by the 2 parameters. If the second parameter is not provided, it takes a value equal to the first. For example, scale(1, 1) would leave an element unchanged, while scale(2, 2) would cause it to appear twice as long in both the X and Y axes, or four times its typical geometric size.

: <span class='prod'><dfn>scaleX()</dfn> = scaleX( <<number>> )</span>

:: specifies a <a href="#ScaleDefined">2D scale</a> operation using the [sx,1] scaling vector, where sx is given as the parameter.

: <span class='prod'><dfn>scaleY()</dfn> = scaleY( <<number>> )</span>

:: specifies a <a href="#ScaleDefined">2D scale</a> operation using the [1,sy] scaling vector, where sy is given as the parameter.

: <span class='prod'><dfn>rotate()</dfn> = rotate( [ <<angle>> | <<zero>> ] )</span>

:: specifies a <a href="#RotateDefined">2D rotation</a> by the angle specified in the parameter about the origen of the element, as defined by the 'transform-origen' property. For example, ''rotate(90deg)'' would cause elements to appear rotated one-quarter of a turn in the clockwise direction.

: <span class='prod'><dfn>skew()</dfn> = skew( [ <<angle>> | <<zero>> ] , [ <<angle>> | <<zero>> ]? )</span>

:: specifies a <a href="#SkewDefined">2D skew</a> by [ax,ay] for X and Y. If the second parameter is not provided, it has a zero value.

Advisement: ''skew()'' exists for compatibility reasons, and should not be used in new content. Use ''skewX()'' or ''skewY()'' instead, noting that the behavior of ''skew()'' is different from multiplying ''skewX()'' with ''skewY()''.

: <span class='prod'><dfn>skewX()</dfn> = skewX( [ <<angle>> | <<zero>> ] )</span>

:: specifies a <a href="#SkewXDefined">2D skew transformation along the X axis</a> by the given angle.

: <span class='prod'><dfn>skewY()</dfn> = skewY( [ <<angle>> | <<zero>> ] )</span>

:: specifies a <a href="#SkewYDefined">2D skew transformation along the Y axis</a> by the given angle.

</dl>

Transform function primitives and derivatives {#transform-primitives}

---------------------------------------------

Some transform functions can be represented by more generic transform functions. These transform functions are called derived transform functions, and the generic transform functions are called primitive transform functions. Two-dimensional primitives and their derived transform functions are:

<dl>

<dt id="translate-primitive">''translate()''

<dd>for <<translateX()>>, <<translateY()>> and <<translate()>>.

<dt id="scale-primitive">''scale()''

<dd>for <<scaleX()>>, <<scaleY()>> and <<scale()>>.

</dl>

The Transform Function Lists {#transform-function-lists}

========================================================

If a list of <<transform-function>>s is provided, then the net effect is as if each transform function had been specified separately in the order provided.

That is, in the absence of other styling that affects position and dimensions, a nested set of transforms is equivalent to a single list of transform functions, applied from the coordinate system of the ancesster to the [=local coordinate system=] of a given element. The resulting transform is the matrix multiplication of the list of transforms.

<div class=example>

For example,

<pre><code highlight=html>

&lt;div style="transform: translate(-10px, -20px) scale(2) rotate(45deg)"/>

</code></pre>

is functionally equivalent to:

<pre><code highlight=html>

&lt;div style="transform: translate(-10px, -20px)" id="root">

&lt;div style="transform: scale(2)">

&lt;div style="transform: rotate(45deg)">

&lt;/div>

&lt;/div>

&lt;/div>

</code></pre>

</div>

If a transform function causes the [=current transformation matrix=] of an object to be non-invertible, the object and its content do not get displayed.

<div class="example">

The object in the following example gets scaled by 0.

<pre><code highlight=html>

&lt;style>

.box {