Compass Transform
Provides mixins for CSS3 2D and 3D transforms. See W3C: CSS 2D transforms and See W3C: CSS 3D transforms.
Safari is the only browser that currently supports 3D transforms. Because of that it can be important to control whether a given 2D transform uses the full range of experimental browser prefixes, or only the 3D list. To make that easy, all 2D transforms include an browser-targeting toggle ($only3d) to switch between the two support lists. The toggle defaults to 'false' (2D), and also accepts 'true' (3D). Currently the lists are as follows: 2D: Mozilla, Webkit, Opera, Official 3D: Webkit, Official **(Only Safari Supports 3D perspective)**
This file can be imported using:
@import "compass/css3/transform"
Imports
- Browser Support – Provides configuration options for the Compass Browser Support Matrix.
Configurable Variables help
$transform-support-threshold
$graceful-usage-threshold
The the user threshold for transform support. Defaults to $graceful-usage-threshold
$default-origin-x
50%
The default x-origin for transforms
$default-origin-y
50%
The default y-origin for transforms
$default-origin-z
50%
The default z-origin for transforms
$default-scale-x
1.25
The default x-multiplier for scaling
$default-scale-y
$default-scale-x
The default y-multiplier for scaling
$default-scale-z
$default-scale-x
The default z-multiplier for scaling
$default-rotate
45deg
The default angle for rotations
$default-vector-x
1
The default x-vector for the axis of 3d rotations
$default-vector-y
1
The default y-vector for the axis of 3d rotations
$default-vector-z
1
The default z-vector for the axis of 3d rotations
$default-translate-x
1em
The default x-length for translations
$default-translate-y
$default-translate-x
The default y-length for translations
$default-translate-z
$default-translate-x
The default z-length for translations
$default-skew-x
5deg
The default x-angle for skewing
$default-skew-y
5deg
The default y-angle for skewing
Mixins
view sourceapply-origin($origin, $only3d)
=apply-origin($origin, $only3d) $capability: if($only3d or length($origin) > 2, transforms3d, transforms2d) +prefixed-properties($capability, $transform-support-threshold, (transform-origin: $origin))
@mixin apply-origin($origin, $only3d) {
$capability: if($only3d or length($origin) > 2, transforms3d, transforms2d);
@include prefixed-properties($capability, $transform-support-threshold, (transform-origin: $origin));
}
Transform-origin Transform-origin sent as a complete string
@include apply-origin( origin [, 3D-only ] )
where 'origin' is a space separated list containing 1-3 (x/y/z) coordinates in percentages, absolute (px, cm, in, em etc..) or relative (left, top, right, bottom, center) units
@param only3d Set this to true to only apply this mixin where browsers have 3D support.
transform-origin($origin-x, $origin-y, $origin-z, $only3d)
=transform-origin($origin-x: $default-origin-x, $origin-y: $default-origin-y, $origin-z: false, $only3d: if($origin-z, true, false))
$origin: unquote("")
@if $origin-x or $origin-y or $origin-z
@if $origin-x
$origin: $origin-x
@else
$origin: 50%
@if $origin-y
$origin: $origin $origin-y
@else
@if $origin-z
$origin: $origin 50%
@if $origin-z
$origin: $origin $origin-z
+apply-origin($origin, $only3d)
@mixin transform-origin($origin-x: $default-origin-x, $origin-y: $default-origin-y, $origin-z: false, $only3d: if($origin-z, true, false)) {
$origin: unquote("");
@if $origin-x or $origin-y or $origin-z {
@if $origin-x {
$origin: $origin-x;
}
@else {
$origin: 50%;
}
@if $origin-y {
$origin: $origin $origin-y;
}
@else {
@if $origin-z {
$origin: $origin 50%;
}
}
@if $origin-z {
$origin: $origin $origin-z;
}
@include apply-origin($origin, $only3d);
}
}
Transform-origin sent as individual arguments:
@include transform-origin( [ origin-x, origin-y, origin-z, 3D-only ] )
where the 3 'origin-' arguments represent x/y/z coordinates.
NOTE: setting z coordinates triggers 3D support list, leave false for 2D support
transform($transform, $only3d)
=transform($transform, $only3d: false) $capability: if($only3d, transforms3d, transforms2d) +prefixed-properties($capability, $transform-support-threshold, (transform: $transform))
@mixin transform($transform, $only3d: false) {
$capability: if($only3d, transforms3d, transforms2d);
@include prefixed-properties($capability, $transform-support-threshold, (transform: $transform));
}
Transform sent as a complete string:
@include transform( transforms [, 3D-only ] )
where 'transforms' is a space separated list of all the transforms to be applied.
transform2d($trans)
=transform2d($trans) +transform($trans, false)
@mixin transform2d($trans) {
@include transform($trans, false);
}
Shortcut to target all browsers with 2D transform support
transform3d($trans)
=transform3d($trans) +transform($trans, true)
@mixin transform3d($trans) {
@include transform($trans, true);
}
Shortcut to target only browsers with 3D transform support
perspective($p)
=perspective($p) +prefixed-properties(transforms3d, $transform-support-threshold, (perspective: $p))
@mixin perspective($p) {
@include prefixed-properties(transforms3d, $transform-support-threshold, (perspective: $p));
}
Set the perspective of 3D transforms on the children of an element:
@include perspective( perspective )
where 'perspective' is a unitless number representing the depth of the z-axis. The higher the perspective, the more exaggerated the foreshortening. values from 500 to 1000 are more-or-less "normal" - a good starting-point.
perspective-origin($origin)
=perspective-origin($origin: 50%) +prefixed-properties(transforms3d, $transform-support-threshold, (perspective-origin: $origin))
@mixin perspective-origin($origin: 50%) {
@include prefixed-properties(transforms3d, $transform-support-threshold, (perspective-origin: $origin));
}
Set the origin position for the perspective
@include perspective-origin(origin-x [origin-y])
where the two arguments represent x/y coordinates
transform-style($style)
=transform-style($style: preserve-3d) +prefixed-properties(transforms3d, $transform-support-threshold, (transform-style: $style))
@mixin transform-style($style: preserve-3d) {
@include prefixed-properties(transforms3d, $transform-support-threshold, (transform-style: $style));
}
Determine whether a 3D objects children also live in the given 3D space
@include transform-style( [ style ] )
where style can be either flat or preserve-3d.
Browsers default to flat, mixin defaults to preserve-3d.
backface-visibility($visibility)
=backface-visibility($visibility: hidden) +prefixed-properties(transforms3d, $transform-support-threshold, (backface-visibility: $visibility))
@mixin backface-visibility($visibility: hidden) {
@include prefixed-properties(transforms3d, $transform-support-threshold, (backface-visibility: $visibility));
}
Determine the visibility of an element when it's back is turned
@include backface-visibility( [ visibility ] )
where visibility can be either visible or hidden.
Browsers default to visible, mixin defaults to hidden
scale($scale-x, $scale-y, $perspective, $only3d)
=scale($scale-x: $default-scale-x, $scale-y: $scale-x, $perspective: false, $only3d: false)
$trans: scale($scale-x, $scale-y)
@if $perspective
$trans: perspective($perspective) $trans
+transform($trans, $only3d)
@mixin scale($scale-x: $default-scale-x, $scale-y: $scale-x, $perspective: false, $only3d: false) {
$trans: scale($scale-x, $scale-y);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform($trans, $only3d);
}
Scale an object along the x and y axis:
@include scale( [ scale-x, scale-y, perspective, 3D-only ] )
where the 'scale-' arguments are unitless multipliers of the x and y dimensions and perspective, which works the same as the stand-alone perspective property/mixin but applies to the individual element (multiplied with any parent perspective)
Note This mixin cannot be combined with other transform mixins.
scaleX($scale, $perspective, $only3d)
=scaleX($scale: $default-scale-x, $perspective: false, $only3d: false)
$trans: scaleX($scale)
@if $perspective
$trans: perspective($perspective) $trans
+transform($trans, $only3d)
@mixin scaleX($scale: $default-scale-x, $perspective: false, $only3d: false) {
$trans: scaleX($scale);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform($trans, $only3d);
}
Scale an object along the x axis @include scaleX( [ scale-x, perspective, 3D-only ] )
Note This mixin cannot be combined with other transform mixins.
scaleY($scale, $perspective, $only3d)
=scaleY($scale: $default-scale-y, $perspective: false, $only3d: false)
$trans: scaleY($scale)
@if $perspective
$trans: perspective($perspective) $trans
+transform($trans, $only3d)
@mixin scaleY($scale: $default-scale-y, $perspective: false, $only3d: false) {
$trans: scaleY($scale);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform($trans, $only3d);
}
Scale an object along the y axis @include scaleY( [ scale-y, perspective, 3D-only ] )
Note This mixin cannot be combined with other transform mixins.
scaleZ($scale, $perspective)
=scaleZ($scale: $default-scale-z, $perspective: false)
$trans: scaleZ($scale)
@if $perspective
$trans: perspective($perspective) $trans
+transform3d($trans)
@mixin scaleZ($scale: $default-scale-z, $perspective: false) {
$trans: scaleZ($scale);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform3d($trans);
}
Scale an object along the z axis @include scaleZ( [ scale-z, perspective ] )
Note This mixin cannot be combined with other transform mixins.
scale3d($scale-x, $scale-y, $scale-z, $perspective)
=scale3d($scale-x: $default-scale-x, $scale-y: $default-scale-y, $scale-z: $default-scale-z, $perspective: false)
$trans: scale3d($scale-x, $scale-y, $scale-z)
@if $perspective
$trans: perspective($perspective) $trans
+transform3d($trans)
@mixin scale3d($scale-x: $default-scale-x, $scale-y: $default-scale-y, $scale-z: $default-scale-z, $perspective: false) {
$trans: scale3d($scale-x, $scale-y, $scale-z);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform3d($trans);
}
Scale and object along all three axis @include scale3d( [ scale-x, scale-y, scale-z, perspective ] )
Note This mixin cannot be combined with other transform mixins.
rotate($rotate, $perspective, $only3d)
=rotate($rotate: $default-rotate, $perspective: false, $only3d: false)
$trans: rotate($rotate)
@if $perspective
$trans: perspective($perspective) $trans
+transform($trans, $only3d)
@mixin rotate($rotate: $default-rotate, $perspective: false, $only3d: false) {
$trans: rotate($rotate);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform($trans, $only3d);
}
Rotate an object around the z axis (2D) @include rotate( [ rotation, perspective, 3D-only ] ) where 'rotation' is an angle set in degrees (deg) or radian (rad) units
Note This mixin cannot be combined with other transform mixins.
rotateZ($rotate, $perspective, $only3d)
=rotateZ($rotate: $default-rotate, $perspective: false, $only3d: false) +rotate($rotate, $perspective, $only3d)
@mixin rotateZ($rotate: $default-rotate, $perspective: false, $only3d: false) {
@include rotate($rotate, $perspective, $only3d);
}
A longcut for 'rotate' in case you forget that 'z' is implied
Note This mixin cannot be combined with other transform mixins.
rotateX($rotate, $perspective)
=rotateX($rotate: $default-rotate, $perspective: false)
$trans: rotateX($rotate)
@if $perspective
$trans: perspective($perspective) $trans
+transform3d($trans)
@mixin rotateX($rotate: $default-rotate, $perspective: false) {
$trans: rotateX($rotate);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform3d($trans);
}
Rotate an object around the x axis (3D) @include rotateX( [ rotation, perspective ] )
Note This mixin cannot be combined with other transform mixins.
rotateY($rotate, $perspective)
=rotateY($rotate: $default-rotate, $perspective: false)
$trans: rotateY($rotate)
@if $perspective
$trans: perspective($perspective) $trans
+transform3d($trans)
@mixin rotateY($rotate: $default-rotate, $perspective: false) {
$trans: rotateY($rotate);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform3d($trans);
}
Rotate an object around the y axis (3D) @include rotate( [ rotation, perspective ] )
Note This mixin cannot be combined with other transform mixins.
rotate3d($vector-x, $vector-y, $vector-z, $rotate, $perspective)
=rotate3d($vector-x: $default-vector-x, $vector-y: $default-vector-y, $vector-z: $default-vector-z, $rotate: $default-rotate, $perspective: false)
$trans: rotate3d($vector-x, $vector-y, $vector-z, $rotate)
@if $perspective
$trans: perspective($perspective) $trans
+transform3d($trans)
@mixin rotate3d($vector-x: $default-vector-x, $vector-y: $default-vector-y, $vector-z: $default-vector-z, $rotate: $default-rotate, $perspective: false) {
$trans: rotate3d($vector-x, $vector-y, $vector-z, $rotate);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform3d($trans);
}
Rotate an object around an arbitrary axis (3D) @include rotate( [ vector-x, vector-y, vector-z, rotation, perspective ] ) where the 'vector-' arguments accept unitless numbers. These numbers are not important on their own, but in relation to one another creating an axis from your transform-origin, along the axis of Xx = Yy = Zz.
Note This mixin cannot be combined with other transform mixins.
translate($translate-x, $translate-y, $perspective, $only3d)
=translate($translate-x: $default-translate-x, $translate-y: $default-translate-y, $perspective: false, $only3d: false)
$trans: translate($translate-x, $translate-y)
@if $perspective
$trans: perspective($perspective) $trans
+transform($trans, $only3d)
@mixin translate($translate-x: $default-translate-x, $translate-y: $default-translate-y, $perspective: false, $only3d: false) {
$trans: translate($translate-x, $translate-y);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform($trans, $only3d);
}
Move an object along the x or y axis (2D) @include translate( [ translate-x, translate-y, perspective, 3D-only ] ) where the 'translate-' arguments accept any distance in percentages or absolute (px, cm, in, em etc..) units.
Note This mixin cannot be combined with other transform mixins.
translateX($trans-x, $perspective, $only3d)
=translateX($trans-x: $default-translate-x, $perspective: false, $only3d: false)
$trans: translateX($trans-x)
@if $perspective
$trans: perspective($perspective) $trans
+transform($trans, $only3d)
@mixin translateX($trans-x: $default-translate-x, $perspective: false, $only3d: false) {
$trans: translateX($trans-x);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform($trans, $only3d);
}
Move an object along the x axis (2D) @include translate( [ translate-x, perspective, 3D-only ] )
Note This mixin cannot be combined with other transform mixins.
translateY($trans-y, $perspective, $only3d)
=translateY($trans-y: $default-translate-y, $perspective: false, $only3d: false)
$trans: translateY($trans-y)
@if $perspective
$trans: perspective($perspective) $trans
+transform($trans, $only3d)
@mixin translateY($trans-y: $default-translate-y, $perspective: false, $only3d: false) {
$trans: translateY($trans-y);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform($trans, $only3d);
}
Move an object along the y axis (2D) @include translate( [ translate-y, perspective, 3D-only ] )
Note This mixin cannot be combined with other transform mixins.
translateZ($trans-z, $perspective)
=translateZ($trans-z: $default-translate-z, $perspective: false)
$trans: translateZ($trans-z)
@if $perspective
$trans: perspective($perspective) $trans
+transform3d($trans)
@mixin translateZ($trans-z: $default-translate-z, $perspective: false) {
$trans: translateZ($trans-z);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform3d($trans);
}
Move an object along the z axis (3D) @include translate( [ translate-z, perspective ] )
Note This mixin cannot be combined with other transform mixins.
translate3d($translate-x, $translate-y, $translate-z, $perspective)
=translate3d($translate-x: $default-translate-x, $translate-y: $default-translate-y, $translate-z: $default-translate-z, $perspective: false)
$trans: translate3d($translate-x, $translate-y, $translate-z)
@if $perspective
$trans: perspective($perspective) $trans
+transform3d($trans)
@mixin translate3d($translate-x: $default-translate-x, $translate-y: $default-translate-y, $translate-z: $default-translate-z, $perspective: false) {
$trans: translate3d($translate-x, $translate-y, $translate-z);
@if $perspective {
$trans: perspective($perspective) $trans;
}
@include transform3d($trans);
}
Move an object along the x, y and z axis (3D) @include translate( [ translate-x, translate-y, translate-z, perspective ] )
Note This mixin cannot be combined with other transform mixins.
skew($skew-x, $skew-y, $only3d)
=skew($skew-x: $default-skew-x, $skew-y: $default-skew-y, $only3d: false) $trans: skew($skew-x, $skew-y) +transform($trans, $only3d)
@mixin skew($skew-x: $default-skew-x, $skew-y: $default-skew-y, $only3d: false) {
$trans: skew($skew-x, $skew-y);
@include transform($trans, $only3d);
}
Skew an element:
@include skew( [ skew-x, skew-y, 3D-only ] )
where the 'skew-' arguments accept css angles in degrees (deg) or radian (rad) units.
Note This mixin cannot be combined with other transform mixins.
skewX($skew-x, $only3d)
=skewX($skew-x: $default-skew-x, $only3d: false) $trans: skewX($skew-x) +transform($trans, $only3d)
@mixin skewX($skew-x: $default-skew-x, $only3d: false) {
$trans: skewX($skew-x);
@include transform($trans, $only3d);
}
Skew an element along the x axiz
@include skew( [ skew-x, 3D-only ] )
Note This mixin cannot be combined with other transform mixins.
skewY($skew-y, $only3d)
=skewY($skew-y: $default-skew-y, $only3d: false) $trans: skewY($skew-y) +transform($trans, $only3d)
@mixin skewY($skew-y: $default-skew-y, $only3d: false) {
$trans: skewY($skew-y);
@include transform($trans, $only3d);
}
Skew an element along the y axis
@include skew( [ skew-y, 3D-only ] )
Note This mixin cannot be combined with other transform mixins.
create-transform($perspective, $scale-x, $scale-y, $scale-z, $rotate-x, $rotate-y, $rotate-z, $rotate3d, $trans-x, $trans-y, $trans-z, $skew-x, $skew-y, $origin-x, $origin-y, $origin-z, $only3d)
=create-transform($perspective: false, $scale-x: false, $scale-y: false, $scale-z: false, $rotate-x: false, $rotate-y: false, $rotate-z: false, $rotate3d: false, $trans-x: false, $trans-y: false, $trans-z: false, $skew-x: false, $skew-y: false, $origin-x: false, $origin-y: false, $origin-z: false, $only3d: false)
$trans: unquote("")
// perspective
@if $perspective
$trans: perspective($perspective)
// scale
@if $scale-x and $scale-y
@if $scale-z
$trans: $trans scale3d($scale-x, $scale-y, $scale-z)
@else
$trans: $trans scale($scale-x, $scale-y)
@else
@if $scale-x
$trans: $trans scaleX($scale-x)
@if $scale-y
$trans: $trans scaleY($scale-y)
@if $scale-z
$trans: $trans scaleZ($scale-z)
// rotate
@if $rotate-x
$trans: $trans rotateX($rotate-x)
@if $rotate-y
$trans: $trans rotateY($rotate-y)
@if $rotate-z
$trans: $trans rotateZ($rotate-z)
@if $rotate3d
$trans: $trans rotate3d($rotate3d)
// translate
@if $trans-x and $trans-y
@if $trans-z
$trans: $trans translate3d($trans-x, $trans-y, $trans-z)
@else
$trans: $trans translate($trans-x, $trans-y)
@else
@if $trans-x
$trans: $trans translateX($trans-x)
@if $trans-y
$trans: $trans translateY($trans-y)
@if $trans-z
$trans: $trans translateZ($trans-z)
// skew
@if $skew-x and $skew-y
$trans: $trans skew($skew-x, $skew-y)
@else
@if $skew-x
$trans: $trans skewX($skew-x)
@if $skew-y
$trans: $trans skewY($skew-y)
// apply it!
+transform($trans, $only3d)
+transform-origin($origin-x, $origin-y, $origin-z, $only3d)
@mixin create-transform($perspective: false, $scale-x: false, $scale-y: false, $scale-z: false, $rotate-x: false, $rotate-y: false, $rotate-z: false, $rotate3d: false, $trans-x: false, $trans-y: false, $trans-z: false, $skew-x: false, $skew-y: false, $origin-x: false, $origin-y: false, $origin-z: false, $only3d: false) {
$trans: unquote("");
// perspective
@if $perspective {
$trans: perspective($perspective);
}
// scale
@if $scale-x and $scale-y {
@if $scale-z {
$trans: $trans scale3d($scale-x, $scale-y, $scale-z);
}
@else {
$trans: $trans scale($scale-x, $scale-y);
}
}
@else {
@if $scale-x {
$trans: $trans scaleX($scale-x);
}
@if $scale-y {
$trans: $trans scaleY($scale-y);
}
@if $scale-z {
$trans: $trans scaleZ($scale-z);
}
}
// rotate
@if $rotate-x {
$trans: $trans rotateX($rotate-x);
}
@if $rotate-y {
$trans: $trans rotateY($rotate-y);
}
@if $rotate-z {
$trans: $trans rotateZ($rotate-z);
}
@if $rotate3d {
$trans: $trans rotate3d($rotate3d);
}
// translate
@if $trans-x and $trans-y {
@if $trans-z {
$trans: $trans translate3d($trans-x, $trans-y, $trans-z);
}
@else {
$trans: $trans translate($trans-x, $trans-y);
}
}
@else {
@if $trans-x {
$trans: $trans translateX($trans-x);
}
@if $trans-y {
$trans: $trans translateY($trans-y);
}
@if $trans-z {
$trans: $trans translateZ($trans-z);
}
}
// skew
@if $skew-x and $skew-y {
$trans: $trans skew($skew-x, $skew-y);
}
@else {
@if $skew-x {
$trans: $trans skewX($skew-x);
}
@if $skew-y {
$trans: $trans skewY($skew-y);
}
}
// apply it!
@include transform($trans, $only3d);
@include transform-origin($origin-x, $origin-y, $origin-z, $only3d);
}
Full transform mixins For settings any combination of transforms as arguments These are complex and not highly recommended for daily use. They are mainly here for backward-compatibility purposes.
- they include origin adjustments
- scale takes a multiplier (unitless), rotate and skew take degrees (deg)
Note This mixin cannot be combined with other transform mixins.
simple-transform($scale, $rotate, $trans-x, $trans-y, $skew-x, $skew-y, $origin-x, $origin-y)
=simple-transform($scale: false, $rotate: false, $trans-x: false, $trans-y: false, $skew-x: false, $skew-y: false, $origin-x: false, $origin-y: false) +create-transform(false, $scale, $scale, false, false, false, $rotate, false, $trans-x, $trans-y, false, $skew-x, $skew-y, $origin-x, $origin-y, false, false)
@mixin simple-transform($scale: false, $rotate: false, $trans-x: false, $trans-y: false, $skew-x: false, $skew-y: false, $origin-x: false, $origin-y: false) {
@include create-transform(false, $scale, $scale, false, false, false, $rotate, false, $trans-x, $trans-y, false, $skew-x, $skew-y, $origin-x, $origin-y, false, false);
}
A simplified set of options backwards-compatible with the previous version of the 'transform' mixin