W3docs
en
Log in

SVG linearGradient

Learn the SVG linearGradient element and its stop children: offset, stop-color, x1/x2/y1/y2, gradientUnits and spreadMethod, with runnable examples.

A linear gradient is a fluid transition from one color to another along a straight line. In SVG you build one with two elements working together: a <linearGradient> that defines the direction and coordinate system of the line, and one or more <stop> children that place colors along it. You then point a shape's fill (or stroke) at the gradient by its id, using fill="url(#myGradient)".

This page covers the <linearGradient> element, its <stop> children, the x1/x2/y1/y2 coordinates that aim the gradient, and the gradientUnits and spreadMethod attributes that control how it is mapped and tiled.

Description of SVG gradients

A gradient is a smooth color blend that can be reused as a paint for any number of shapes. SVG has two main kinds of gradients:

  • linear — colors blend along a straight line (this page).
  • radial — colors blend outward from a center point. See SVG radialGradient.

The <linearGradient> element

The <linearGradient> element defines a linear gradient that fills (or strokes) graphical elements. It is a definition, not a visible shape, so it lives inside a <defs> block, is given an id, and is referenced from a shape with fill="url(#id)".

The direction of the gradient is set by the start point (x1, y1) and the end point (x2, y2). The gradient line runs from the start point to the end point; colors are interpolated along it.

Linear gradients can be horizontal, vertical, or angular:

  • Horizontal — y1 and y2 are equal, while x1 and x2 differ.
  • Vertical — x1 and x2 are equal, while y1 and y2 differ.
  • Angular (diagonal) — both the x pair and the y pair differ.
Info

If you omit the coordinates, the SVG defaults are x1="0%", y1="0%", x2="100%", y2="0%" — a left-to-right horizontal gradient.

Danger

Don't confuse an SVG linear gradient with the CSS linear-gradient function. CSS gradients paint HTML elements via background-image, while SVG gradients paint SVG shapes via fill or stroke.

The <stop> element

Each <stop> places a single color at a position along the gradient line. You need at least two stops to see a transition. Stops can be styled with presentation attributes (stop-color, stop-opacity) or with the equivalent CSS inside a style attribute, as in the examples below.

AttributeDescription
offsetWhere the stop sits along the gradient line, as a number 0–1 or a percentage 0%–100%. 0% is the start point, 100% is the end point.
stop-colorThe color of the stop. Accepts any CSS color (named, #hex, rgb(), hsl()). Defaults to black.
stop-opacityThe opacity of the stop's color, from 0 (transparent) to 1 (opaque). Defaults to 1.

Example of the <linearGradient> element to create an ellipse with a horizontal linear gradient:

<!DOCTYPE html>
<html>
  <body>
    <svg height="200" width="300">
      <defs>
        <linearGradient id="ellipse" x1="0%" y1="0%" x2="100%" y2="0%">
          <stop offset="0%" style="stop-color:rgb(28, 135, 201);stop-opacity:1" />
          <stop offset="100%" style="stop-color:rgb(128, 0, 128);stop-opacity:1" />
        </linearGradient>
      </defs>
      <ellipse cx="150" cy="90" rx="105" ry="65" fill="url(#ellipse)" />
    </svg>
  </body>
</html>
Try it Yourself »

Example of the <linearGradient> element to create an ellipse with a vertical linear gradient:

<!DOCTYPE html>
<html>
  <body>
    <svg height="300" width="400">
      <defs>
        <linearGradient id="ellipse" x1="0%" y1="0%" x2="0%" y2="100%">
          <stop offset="0%" style="stop-color:rgb(28, 135, 201);stop-opacity:1" />
          <stop offset="100%" style="stop-color:rgb(128, 0, 128);stop-opacity:1" />
        </linearGradient>
      </defs>
      <ellipse cx="250" cy="100" rx="110" ry="70" fill="url(#ellipse)" />
    </svg>
  </body>
</html>
Try it Yourself »

Example of an angular (diagonal) linear gradient:

By default gradientUnits is objectBoundingBox, so the coordinates are fractions of the shape's bounding box. Using x1="0" y1="0" x2="1" y2="1" runs the gradient line from the top-left corner to the bottom-right corner, producing a diagonal blend.

<!DOCTYPE html>
<html>
  <body>
    <svg height="200" width="300">
      <defs>
        <linearGradient id="diagonal" x1="0" y1="0" x2="1" y2="1">
          <stop offset="0%" style="stop-color:rgb(28, 135, 201);stop-opacity:1" />
          <stop offset="100%" style="stop-color:rgb(128, 0, 128);stop-opacity:1" />
        </linearGradient>
      </defs>
      <rect x="20" y="20" width="260" height="160" fill="url(#diagonal)" />
    </svg>
  </body>
</html>

The gradientUnits attribute

gradientUnits decides how x1, y1, x2, and y2 are interpreted:

  • objectBoundingBox (default) — coordinates are relative to the shape being painted, where 0 (or 0%) is one edge and 1 (or 100%) is the opposite edge. The gradient automatically stretches to fit each shape.
  • userSpaceOnUse — coordinates are absolute positions in the SVG's user coordinate system (the same units as the shape's own x/y).

A common gotcha: with userSpaceOnUse, percentage and 0–1 coordinates no longer track the shape. You must give real coordinates (e.g. x1="20" y1="0" x2="280" y2="0") that overlap the shape, or the fill may appear flat (a single color) because the gradient line never crosses it.

The spreadMethod attribute

spreadMethod controls what happens outside the [x1,y1]–[x2,y2] segment when the gradient line is shorter than the shape. It only has a visible effect when the gradient doesn't already span the whole shape.

ValueBehavior
pad (default)The first and last stop colors extend ("pad out") to fill the remaining area.
reflectThe gradient mirrors back and forth, repeating in alternating directions.
repeatThe gradient tiles, jumping from the last stop back to the first and repeating.
<!DOCTYPE html>
<html>
  <body>
    <svg height="120" width="300">
      <defs>
        <linearGradient id="repeated" x1="0" y1="0" x2="0.2" y2="0"
                        spreadMethod="repeat">
          <stop offset="0%" stop-color="rgb(28, 135, 201)" />
          <stop offset="100%" stop-color="rgb(128, 0, 128)" />
        </linearGradient>
      </defs>
      <rect x="0" y="0" width="300" height="120" fill="url(#repeated)" />
    </svg>
  </body>
</html>

Change spreadMethod="repeat" to reflect or pad in the example above to compare the three behaviors: repeat produces hard color jumps, reflect produces a smooth ping-pong, and pad shows the gradient once and then a solid block of the last color.

Attributes

ValueDescription
gradientUnitsThis attribute specifies the coordinate system for attributes x1, x2, y1, y2. Values: userSpaceOnUse, objectBoundingBox.
gradientTransformThis attribute gives extra transformation to the gradient coordinate system.
hrefThis attribute specifies a reference to another <linearGradient> element.
spreadMethodThis attribute specifies how the gradient behaves if it starts or ends within the bounds of the shape that contains the gradient. Values: pad, repeat, reflect.
x1This attribute specifies the x coordinate of the beginning point of the vector gradient along which the linear gradient is being drawn.
x2This attribute specifies the x coordinate of the ending point of the vector gradient along which the linear gradient is being drawn.
y1This attribute specifies the y coordinate of the beginning point of the vector gradient along which the linear gradient is drawn.
y2This attribute specifies the y coordinate of the ending point of the vector gradient along which the linear gradient is drawn.

The SVG <linearGradient> element also supports the Global Attributes and Event Attributes.

For radial color blends that spread outward from a center point instead of along a line, see SVG radialGradient.

Practice

Practice
Which attribute places a single color at a position along an SVG linear gradient line?
Which attribute places a single color at a position along an SVG linear gradient line?
Practice
Select all that apply: what do the x1, y1, x2, and y2 attributes do on a linearGradient? (Select all that apply)
Select all that apply: what do the x1, y1, x2, and y2 attributes do on a linearGradient? (Select all that apply)
Was this page helpful?