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:

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:

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