How SVG gradientTransform Modifies Gradient Orientation

The gradientTransform attribute in Scalable Vector Graphics (SVG) allows developers to alter the position, scale, skew, and rotation of both linear and radial gradients without modifying the original coordinate points or the shapes using the gradient. By applying an affine transformation matrix directly to the gradient’s coordinate system, this attribute provides fine-grained control over gradient orientation, enabling effects such as custom rotation angles, shearing, and focal shifting.

The Mechanism of gradientTransform

In standard SVG markup, gradient orientation is initially determined by coordinate attributes: x1, y1, x2, and y2 for <linearGradient>, or cx, cy, r, fx, and fy for <radialGradient>. While you can adjust these coordinates directly, calculating diagonal or skewed angles using raw coordinates can be mathematically complex.

The gradientTransform attribute resolves this by applying geometric transformation functions to the gradient space after the initial coordinates are evaluated.

Key Transformation Functions for Gradient Orientation

The gradientTransform attribute accepts the same list of transform definitions used by the standard SVG transform attribute:

1. Rotation (rotate)

The rotate() function is the most direct way to change the angle of a gradient. It rotates the gradient coordinate space around a specified origin point.

• Syntax: rotate(<angle> [<cx> <cy>])
• Orientation Effect: A linear gradient defined horizontally (x1="0%" y1="0%" x2="100%" y2="0%") can be turned into a 45-degree diagonal gradient simply by applying gradientTransform="rotate(45)".

<linearGradient id="angledGradient" x1="0%" y1="0%" x2="100%" y2="0%" gradientTransform="rotate(45)">
  <stop offset="0%" stop-color="#ff0000" />
  <stop offset="100%" stop-color="#0000ff" />
</linearGradient>

2. Skewing (skewX and skewY)

Skew functions distort the gradient along the horizontal or vertical axes, creating asymmetric or sheared color transitions.

• Syntax: skewX(<angle>) or skewY(<angle>)
• Orientation Effect: Slants the color transition bands relative to the geometry of the target element, which is useful for isometric designs and dynamic lighting effects.

3. Scaling (scale)

The scale() function expands or compresses the gradient space.

• Syntax: scale(<sx> [<sy>])
• Orientation Effect: Non-uniform scaling (e.g., scale(2, 0.5)) turns circular <radialGradient> fills into elliptical gradients and alters the apparent rate of color transitions across the surface.

4. Translation (translate)

The translate() function moves the origin of the gradient coordinate space.

• Syntax: translate(<tx> [<ty>])
• Orientation Effect: Shifts the focal point of a radial gradient or the starting threshold of a linear gradient across the canvas.

5. Matrix Transformations (matrix)

For complex orientations combining rotation, scale, and translation in a single mathematical expression, the matrix() function accepts six values defining a 2D affine transformation.

• Syntax: matrix(<a> <b> <c> <d> <e> <f>)

Interaction with gradientUnits

The behavior of gradientTransform is tied to the gradientUnits attribute:

• objectBoundingBox (Default): Coordinates are relative to the bounding box of the element using the gradient (from 0 to 1). Transformations apply relative to this normalized unit square.
• userSpaceOnUse: Coordinates reference the current user coordinate system (SVG canvas pixels). Transformations occur relative to the global SVG coordinate space.

Using gradientTransform simplifies SVG maintenance by separating the definition of gradient colors from their physical orientation on the canvas.