previous next contents properties index

# 13 Gradients and Patterns

### Contents

## 13.1 Introduction

With SVG, you can fill (i.e., paint the interior) or stroke (i.e., paint the outline) of shapes and text using one of the following:

- color
- gradients (linear or radial)
- patterns (vector or image, possibly tiled)

SVG uses the general notion of a paint server. Gradients and patterns are just specific types of paint servers. For example, first you define a linear gradient by including a 'linearGradient' element with an ID and then reference that ID in a 'fill' or 'stroke' property:

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000303 Stylable//EN"
      "http://www.w3.org/TR/2000/03/WD-SVG-20000303/DTD/svg-20000303-stylable.dtd">
    <svg width="4in" height="3in">
      <desc>Linear gradient example
      </desc>
      <g>
        <defs>
          <linearGradient id="MyGradient">
            <stop offset="0%" style="stop-color:#F60"/>
            <stop offset="70%" style="stop-color:#FF6"/>
          </linearGradient>
        </defs>
        <rect style="fill: url(#MyGradient)" width="20" height="15.8"/>
      </g>
    </svg>

Download this example

## 13.2 Gradients

### 13.2.1 Introduction

Gradients consist of continuously smooth color transitions along a vector from one color to another, possibly followed by additional transitions along the same vector to other colors. SVG provides for two types of gradients, linear gradients and radial gradients.

Once defined, gradients are then referenced using 'fill' or 'stroke' or properties on a given graphics element to indicate that the given element shall be filled or stroked with the referenced gradient.

### 13.2.2 Linear gradients

Linear gradients are defined by a 'linearGradient' element.

    <!ENTITY % linearGradientExt "" >
    <!ELEMENT linearGradient (stop|animate|set|animateTransform
                       %linearGradientExt;)* >
    <!ATTLIST linearGradient
      %stdAttrs;
      gradientUnits (userSpace | userSpaceOnUse | objectBoundingBox) 'userSpace'
      gradientTransform %TransformList; #IMPLIED
      x1 %Coordinate; #IMPLIED
      y1 %Coordinate; #IMPLIED
      x2 %Coordinate; #IMPLIED
      y2 %Coordinate; #IMPLIED
      spreadMethod (pad | reflect | repeat) "pad"
      %xlinkRefAttrs;
      xlink:href %URI; #IMPLIED
      externalResourcesRequired %Boolean; #IMPLIED >

Attribute definitions:

gradientUnits = "userSpace | userSpaceOnUse | objectBoundingBox"
  Defines the coordinate system for attributes x1, y1, x2, y2.
  If gradientUnits="userSpace" (the default), x1, y1, x2, y2 represent values in the current user coordinate system in place at the time when the 'linearGradient' element is defined.
  If gradientUnits="userSpaceOnUse", x1, y1, x2, y2 represent values in the current user coordinate system in place at the time when the 'linearGradient' element is referenced (i.e., the user coordinate system for the element referencing the 'linearGradient' element via a 'fill' or 'stroke' property).
  If gradientUnits="objectBoundingBox", then x1, y1, x2, y2 represent values in an abstract coordinate system where (0,0) is the (minx,miny) in user space of the bounding box of the object getting filled with the gradient, and (1,1) is the (maxx,maxy) corner of the bounding box. (Note: the bounding box represents the maximum extent of the shape of the object in X and Y with respect to the user coordinate system of the object exclusive of stroke-width.)
  Animatable: yes.
gradientTransform = "<transform-list>"
  Contains the definitions of an optional additional transformation from the gradient coordinate system onto the target coordinate system (i.e., userSpace or objectBoundingBox). This allows for things such as skewing the gradient.
  Animatable: yes.
x1 = "<coordinate>"
  x1, y1, x2, 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, y2 can be either numbers or percentages whose meaning is determined by the value of attribute gradientUnits, as follows:

  gradientUnits | Type of value | Meaning of value
  --- | --- | ---
  "userSpace" | a number | The value represents a coordinate in the current user coordinate system
  "userSpace" | a percentage | The value represents a percent distance along the X-axis of the current viewport (see Processing rules for CSS units and percentages)
  "objectBoundingBox" | a number | The value represents a fractional position within the bounding box of the given shape, where (0,0) is the (minx,miny) of the shape and (1,1) is the (maxx,maxy) of the shape. (See discussion of gradientUnits="objectBoundingBox".)
  "objectBoundingBox" | a percentage | The value represents a fractional position within the bounding box of the given shape, where (0%,0%) is the (minx,miny) of the shape and (100%,100%) is the (maxx,maxy) of the shape. (See discussion of gradientUnits="objectBoundingBox".)

  Default value is "0%".
  Animatable: yes.
y1 = "<coordinate>"
  See x1. Default value is "0%".
  Animatable: yes.
x2 = "<coordinate>"
  See x1. Default value is "100%".
  Animatable: yes.
y2 = "<coordinate>"
  See x1. Default value is "0%".
  Animatable: yes.
spreadMethod = "pad | reflect | repeat"
  Indicates what happens if the the gradient starts or ends inside the bounds of the target rectangle. Possible values are: pad, which says to use the terminal colors of the gradient to fill the remainder of the target region, reflect, which says to reflect the gradient pattern start-to-end, end-to-start, start-to-end, etc. continuously until the target rectangle is filled, and repeat, which says to repeat the gradient pattern start-to-end, start-to-end, start-to-end, etc. continuously until the target region is filled.
  Animatable: yes.
xlink:href = "<uri>"
  A URI reference to a different 'linearGradient' or 'radialGradient' element within the current SVG document fragment. Any 'linearGradient' attributes which are defined on the referenced element which are not defined on this element are inherited by this element. If this element has no defined gradient stops, and the referenced element does (possibly due to its own href attribute), then this element inherits the gradient stop from the referenced element. Inheritance can be indirect to an arbitrary level; thus, if the referenced element inherits attribute or gradient stops due to its own href attribute, then the current element can inherit those attributes or gradient stops.
  Animatable: yes.

Attributes defined elsewhere:
  %stdAttrs;, %xlinkRefAttrs;.

Percentages are allowed for x1, y1, x2, y2. For gradientUnits="userSpace", percentages represent values relative to the current viewport. For gradientUnits="objectBoundingBox", percentages represent values relative to the bounding box for the object.

### 13.2.3 Radial gradients

Radial gradients are defined by a 'radialGradient' element.

    <!ENTITY % radialGradientExt "" >
    <!ELEMENT radialGradient (stop|animate|set|animateTransform
                       %radialGradientExt;)* >
    <!ATTLIST radialGradient
      %stdAttrs;
      gradientUnits (userSpace | userSpaceOnUse | objectBoundingBox) 'userSpace'
      gradientTransform %TransformList; #IMPLIED
      cx %Coordinate; #IMPLIED
      cy %Coordinate; #IMPLIED
      r %Length; #IMPLIED
      fx %Coordinate; #IMPLIED
      fy %Coordinate; #IMPLIED
      %xlinkRefAttrs;
      xlink:href %URI; #IMPLIED
      externalResourcesRequired %Boolean; #IMPLIED >

Attribute definitions:

gradientUnits = "userSpace | userSpaceOnUse | objectBoundingBox"
  Defines the coordinate system for attributes cx, cy, r, fx, fy.
  If gradientUnits="userSpace" (the default), cx, cy, r, fx, fy represent values in the current user coordinate system in place at the time when the 'linearGradient' element is defined.
  If gradientUnits="userSpaceOnUse", cx, cy, r, fx, fy represent values in the current user coordinate system in place at the time when the 'radialGradient' element is referenced (i.e., the user coordinate system for the element referencing the 'radialGradient' element via a 'fill' or 'stroke' property).
  If gradientUnits="objectBoundingBox", then cx, cy, r, fx, fy represent values in an abstract coordinate system where (0,0) is the (minx,miny) in user space of the bounding box of the object getting filled with the gradient, and (1,1) is the (maxx,maxy) corner of the bounding box. (Note: the bounding box represents the maximum extent of the shape of the object in X and Y with respect to the user coordinate system of the object exclusive of stroke-width.)
  Animatable: yes.
gradientTransform = "<transform-list>"
  Contains the definitions of an optional additional transformation from the gradient coordinate system onto the target coordinate system (i.e., userSpace or objectBoundingBox). This allows for things such as skewing the gradient.
  Animatable: yes.
cx = "<coordinate>"
  cx, cy, r define the largest/outermost circle for the radial gradient. The gradient will be drawn such that the 100% gradient stop is mapped to the perimeter of this largest/outermost circle. Default value is "50%".
  Animatable: yes.
cy = "<coordinate>"
  See cx. Default value is "50%".
  Animatable: yes.
r = "<length>"
  See cx. Default value is "50%".
  Animatable: yes.
fx = "<coordinate>"
  fx, fy define the focal point for the radial gradient. The gradient will be drawn such that the 0% gradient stop is mapped to (fx, fy). The default value is 50%.
  Animatable: yes.
fy = "<coordinate>"
  See fx. Default value is "50%".
  Animatable: yes.
xlink:href = "<uri>"
  A URI reference to a different 'linearGradient' or 'radialGradient' element within the current SVG document fragment. Any 'radialGradient' attributes which are defined on the referenced element which are not defined on this element are inherited by this element. If this element has no defined gradient stops, and the referenced element does (possibly due to its own href attribute), then this element inherits the gradient stop from the referenced element. Inheritance can be indirect to an arbitrary level; thus, if the referenced element inherits attribute or gradient stops due to its own href attribute, then the current element can inherit those attributes or gradient stops.
  Animatable: yes.

Attributes defined elsewhere:
  %stdAttrs;, %xlinkRefAttrs;.

Percentages are allowed for cx, cy, r, fx, fy. For gradientUnits="userSpace", percentages represent values relative to the current viewport. For gradientUnits="objectBoundingBox", percentages represent values relative to the bounding box for the object.

### 13.2.4 Gradient stops

The ramp of colors to use on a gradient is defined by the 'stop' elements that are child elements to either the 'linearGradient' element or the 'radialGradient' element. Here is an example of the definition of a linear gradient that consists of a smooth transition from white-to-red-to-black:

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000303 Stylable//EN"
      "http://www.w3.org/TR/2000/03/WD-SVG-20000303/DTD/svg-20000303-stylable.dtd">
    <svg width="4in" height="3in">
      <desc>Radial gradient example with three gradient stops
      </desc>
      <g>
        <defs>
          <radialGradient id="MyGradient">
             <stop offset="0%" style="stop-color:white"/>
             <stop offset="50%" style="stop-color:red"/>
             <stop offset="100%" style="stop-color:black"/>
          </radialGradient>
        </defs>
        <circle style="fill: url(#MyGradient)" cx="2in" cy="1.5in" r="1.25in"/>
      </g>
    </svg>

Download this example

    <!ENTITY % stopExt "" >
    <!ELEMENT stop (animate|set|animateColor
                       %stopExt;)* >
    <!ATTLIST stop
      %stdAttrs;
      class %ClassList; #IMPLIED
      offset %Length; #REQUIRED
      %StylableSVG-StyleAttribute;
      %ExchangeSVG-GradientAttrs; >

Attribute definitions:

offset = "length"
  The offset attribute is either a <number> (usually ranging from 0 to 1) or a percentage (correspondingly usually ranging from 0% to 100%) which indicates where the gradient stop is placed. For linear gradients, the offset attribute represents a location along the gradient vector. For radial gradients, it represents a percentage distance from (fx,fy) to the edge of the outermost/largest circle.
  Animatable: yes.

Attributes defined elsewhere:
  %stdAttrs;, %StylableSVG-StyleAttribute;.

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.

'stop-color'

  Value: | currentColor | <color> [icc-color(<name>,<icccolorvalue>+)] | inherit
  Initial: | black
  Applies to: | 'stop' elements
  Inherited: | no
  Percentages: | N/A
  Media: | visual
  Animatable: | yes

The 'stop-opacity' property defines the opacity of a given gradient stop.

'stop-opacity'

  Value: | <alphavalue> | inherit
  Initial: | 1
  Applies to: | 'stop' elements
  Inherited: | no
  Percentages: | N/A
  Media: | visual
  Animatable: | yes

Some notes on gradients:

- Gradient offset values less than 0 (or less than 0%) are rounded up to 0%. Gradient offset values greater than 1 (or greater than 100%) are rounded down to 100%.
- There needs to be at least two stops defined to have a gradient effect. If no stops are defined, then painting shall occur as if 'none' were specified as the paint style. If one stop is defined, then paint with the solid color fill using the color defined for that gradient stop.
- Each gradient offset value is required to be equal to or greater than the previous gradient stop's offset value. If a given gradient stop's offset value is not equal to or greater than all previous offset values, then the offset value is adjusted to be equal to the largest of all previous offset values.
- If two gradient stops have the same offset value, then the latter gradient stop controls the color value at the overlap point.

## 13.3 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:.

    <!ENTITY % patternExt "" >
    <!ELEMENT pattern (%descTitleDefs;,
                        (path|text|rect|circle|ellipse|line|polyline|polygon|
                         use|image|svg|g|switch|a
                         %ceExt;%patternExt;)*) >
    <!ATTLIST pattern
      %stdAttrs;
      %langSpaceAttrs;
      class %ClassList; #IMPLIED
      %testAttrs;
      externalResourcesRequired %Boolean; #IMPLIED
      patternUnits (userSpace | userSpaceOnUse | objectBoundingBox) 'userSpace'
      patternTransform %TransformList; #IMPLIED
      x %Coordinate; #IMPLIED
      y %Coordinate; #IMPLIED
      width %Length; #REQUIRED
      height %Length; #REQUIRED
      viewBox %ViewBoxSpec; #IMPLIED
      preserveAspectRatio %PreserveAspectRatioSpec; 'xMidYMid meet'
      %xlinkRefAttrs;
      xlink:href %URI; #IMPLIED
      %StylableSVG-StyleAttribute;
      %ExchangeSVG-ContainerAttrs;
      %ExchangeSVG-FillStrokeAttrs;
      %ExchangeSVG-GradientAttrs;
      %ExchangeSVG-GraphicsAttrs;
      %ExchangeSVG-MarkerAttrs;
      %ExchangeSVG-TextContainerAttrs;
      %ExchangeSVG-TextElementAttrs;
      %ExchangeSVG-ViewportAttrs; >

Attribute definitions:

patternUnits = "userSpace | userSpaceOnUse | objectBoundingBox"
  Defines the coordinate system for attributes x, y, width, height and the contents of the 'pattern'.
  If patternUnits="userSpace" (the default), x, y, width, height and the contents of the 'pattern' represent values in the current user coordinate system in place at the time when the 'mask' element is defined.
  If patternUnits="userSpaceOnUse", x, y, width, height and the contents of the 'pattern' represent values in 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).
  If patternUnits="objectBoundingBox", x, y, width, height and the contents of the 'pattern' represent values in the abstract coordinate system where (0,0) is the (minx,miny) in user space of the tight bounding box of the object referencing the mask, and (1,1) is the (maxx,maxy) corner of the bounding box. (Note: the bounding box represents the maximum extent of the shape of the object in X and Y with respect to the user coordinate system of the object exclusive of stroke-width.)
  Animatable: yes.
patternTransform = "<transform-list>"
  Contains the definitions of an optional additional transformation from the pattern coordinate system onto the target coordinate system (i.e., userSpace or objectBoundingBox). This allows for things such as skewing the pattern tiles.
  Animatable: yes.
x = "<coordinate>"
  x, y, width, height indicate how the pattern tiles are placed and spaced and represent coordinates and values in the coordinate space specified by patternUnits. Default value is "0%".
  Animatable: yes.
y = "<coordinate>"
  See x. Default value is "0%".
  Animatable: yes.
width = "<length>"
  See x. Default value is "100%".
  Animatable: yes.
height = "<length>"
  See x. Default value is "100%".
  Animatable: yes.
xlink:href = "<uri>"
  A URI reference to a different 'pattern' element within the current SVG document fragment. Any attributes which are defined on the referenced element which are not defined on this element are inherited by this element. If this element has children, and the referenced element does (possibly due to its own href attribute), then this element inherits the children from the referenced element. Inheritance can be indirect to an arbitrary level; thus, if the referenced element inherits attributes or children due to its own href attribute, then the current element can inherit those attributes or gradient stops.
  Animatable: yes.

Attributes defined elsewhere:
  %stdAttrs;, %langSpaceAttrs;, viewBox, preserveAspectRatio, %xlinkRefAttrs;, %StylableSVG-StyleAttribute;.

An example:

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000303 Stylable//EN"
      "http://www.w3.org/TR/2000/03/WD-SVG-20000303/DTD/svg-20000303-stylable.dtd">
    <svg width="4in" height="3in" >
      <defs>
        <pattern id="TrianglePattern"
                 patternUnits="userSpace"
                 x="0" y="0" width="25" height="25"
                 patternTransform="skewX(45)"
                 viewBox="0 0 10 10" >
          <path d="M 0 0 L 10 0 L 5 10 z" />
        </pattern>
      </defs>
      <!-- Fill this ellipse with the above pattern -->
      <ellipse style="fill: url(#TrianglePattern)" rx="40" ry="27" />
    </svg>

Download this example

## 13.4 DOM interfaces

The following interfaces are defined below: SVGGradientElement, SVGLinearGradientElement, SVGRadialGradientElement, SVGStopElement, SVGPatternElement.

### Interface SVGGradientElement

The SVGGradientElement interface is a base interface used by SVGLinearGradientElement and SVGRadialGradientElement.

IDL Definition

      interface SVGGradientElement : SVGElement, SVGURIReference, SVGUnitTypes {
                 attribute unsigned short   gradientUnits;
                 attribute SVGTransformList gradientTransform;
      };

Attributes
  unsigned short gradientUnits
    Corresponds to attribute gradientUnits on the given element. Takes on one of the constants defined in SVGUnitTypes.
  SVGTransformList gradientTransform
    Corresponds to attribute gradientTransform on the given element.

### Interface SVGLinearGradientElement

The SVGLinearGradientElement interface corresponds to the 'linearGradient' element.

IDL Definition

      interface SVGLinearGradientElement : SVGGradientElement {
        // Spread Method Types
        constant unsigned short SVG_SPREADMETHOD_UNKNOWN = 0;
        constant unsigned short SVG_SPREADMETHOD_PAD     = 1;
        constant unsigned short SVG_SPREADMETHOD_REFLECT = 2;
        constant unsigned short SVG_SPREADMETHOD_REPEAT  = 3;

                 attribute SVGLength       x1;
                 attribute SVGLength       y1;
                 attribute SVGLength       x2;
                 attribute SVGLength       y2;
                 attribute unsigned short  spreadMethod;
      };

Definition group Spread Method Types
  Defined constants

    SVG_SPREADMETHOD_UNKNOWN |  | The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type.
    SVG_SPREADMETHOD_PAD |  | Corresponds to value pad.
    SVG_SPREADMETHOD_REFLECT |  | Corresponds to value reflect.
    SVG_SPREADMETHOD_REPEAT |  | Corresponds to value repeat.

Attributes
  SVGLength x1
    Corresponds to attribute x1 on the given 'linearGradient' element.
  SVGLength y1
    Corresponds to attribute y1 on the given 'linearGradient' element.
  SVGLength x2
    Corresponds to attribute x2 on the given 'linearGradient' element.
  SVGLength y2
    Corresponds to attribute y2 on the given 'linearGradient' element.
  unsigned short spreadMethod
    Corresponds to attribute spreadMethod on the given element. One of the Spread Method Types.

### Interface SVGRadialGradientElement

The SVGRadialGradientElement interface corresponds to the 'radialGradient' element.

IDL Definition

      interface SVGRadialGradientElement : SVGGradientElement {
                 attribute SVGLength cx;
                 attribute SVGLength cy;
                 attribute SVGLength r;
                 attribute SVGLength fx;
                 attribute SVGLength fy;
      };

Attributes
  SVGLength cx
    Corresponds to attribute cx on the given 'radialGradient' element.
  SVGLength cy
    Corresponds to attribute cy on the given 'radialGradient' element.
  SVGLength r
    Corresponds to attribute r on the given 'radialGradient' element.
  SVGLength fx
    Corresponds to attribute fx on the given 'radialGradient' element.
  SVGLength fy
    Corresponds to attribute fy on the given 'radialGradient' element.

### Interface SVGStopElement

The SVGStopElement interface corresponds to the 'stop' element.

IDL Definition

      interface SVGStopElement : SVGElement {
                 attribute DOMString className;
                 attribute float offset;

      #ifdef STYLABLESVG
                 // The following pre-defined attribute collections are only
                 // available in the DOM for Stylable SVG.
                 STYLABLESVGStyleAttribute;
      #endif STYLABLESVG
          };

Attributes
  DOMString className
    Corresponds to attribute class on the given element.
  float offset
    Corresponds to attribute offset on the given 'stop' element.

### Interface SVGPatternElement

The SVGPatternElement interface corresponds to the 'pattern' element.

IDL Definition

      interface SVGPatternElement : SVGElement, SVGLangSpace, SVGFitToViewBox, SVGURIReference, SVGUnitTypes {
                 attribute DOMString className;
                 attribute unsigned short   patternUnits;
                 attribute SVGTransformList patternTransform;
                 attribute SVGLength        x;
                 attribute SVGLength        y;
                 attribute SVGLength        width;
                 attribute SVGLength        height;

      #ifdef STYLABLESVG
                 // The following pre-defined attribute collections are only
                 // available in the DOM for Stylable SVG.
                 STYLABLESVGStyleAttribute;
      #endif STYLABLESVG

      #ifdef EXCHANGESVG
                 // The following pre-defined attribute collections are only
                 // available in the DOM for Exchange SVG.
                 EXCHANGESVGContainerAttrs;
                 EXCHANGESVGFillStrokeAttrs;
                 EXCHANGESVGGradientAttrs;
                 EXCHANGESVGGraphicsAttrs;
                 EXCHANGESVGMarkerAttrs;
                 EXCHANGESVGTextContainerAttrs;
                 EXCHANGESVGTextElementAttrs;
                 EXCHANGESVGViewportAttrs;
      #endif EXCHANGESVG
          };

Attributes
  DOMString className
    Corresponds to attribute class on the given element.
  unsigned short patternUnits
    Corresponds to attribute gradientUnits on the given 'pattern' element. Takes on one of the constants defined in SVGUnitTypes.
  SVGTransformList patternTransform
    Corresponds to attribute patternTransform on the given 'pattern' element.
  SVGLength x
    Corresponds to attribute x on the given 'pattern' element.
  SVGLength y
    Corresponds to attribute y on the given 'pattern' element.
  SVGLength width
    Corresponds to attribute width on the given 'pattern' element.
  SVGLength height
    Corresponds to attribute height on the given 'pattern' element.

previous next contents properties index