Skip to content
Tutorials Center
My learning

Topics

HTML Reference ยท SVG

SVG gradients and patterns

Reference for SVG paint servers: linearGradient, radialGradient, stop and pattern, with every attribute, gradientUnits, spreadMethod and focal points.

A fill or stroke in SVG can be more than a color. It can point to a paint server: a gradient or a pattern defined once (usually inside <defs>) and referenced by its ID with url(#id). SVG has three: <linearGradient>, <radialGradient> and <pattern>. Gradients get their colors from <stop> children.

HTML
<svg viewBox="0 0 200 60" width="300">
  <defs>
    <linearGradient id="sky">
      <stop offset="0" stop-color="#38bdf8"/>
      <stop offset="1" stop-color="#6366f1"/>
    </linearGradient>
  </defs>
  <rect width="200" height="60" rx="10" fill="url(#sky)"/>
</svg>

Try it

Linear gradients: direction and stops

Two stops at the same offset make a sharp line instead of a blend. Gradient coordinates here are fractions of each shape's bounding box, because gradientUnits defaults to objectBoundingBox.

Elements

Element Purpose
<linearGradient> Colors change along a straight line from (x1, y1) to (x2, y2).
<radialGradient> Colors spread out in circles from a focal point toward an outer circle.
<stop> One color in a gradient, at a position from 0 to 1 (or 0% to 100%).
<pattern> A tile of any SVG content repeated in both directions to fill a shape.

A shape uses them with fill="url(#id)" or stroke="url(#id)". You can add a fallback color after the reference, fill="url(#id) gray", which is used if the reference can't be resolved.

Attributes

Shared by both gradients

Attribute Values Default Description
gradientUnits objectBoundingBox, userSpaceOnUse objectBoundingBox objectBoundingBox: coordinates are fractions of each shape's box (0 to 1), so every shape gets the full gradient. userSpaceOnUse: coordinates are in the drawing's units, so one gradient spans several shapes.
gradientTransform A transform list (none) Rotates, scales or skews the gradient, for example rotate(45).
spreadMethod pad, reflect, repeat pad What happens outside the 0โ€“1 range: extend the end colors, mirror the gradient, or restart it.
href #id (none) Inherit stops and attributes from another gradient, then override what differs.

linearGradient

Attribute Default Description
x1, y1 0%, 0% Where offset 0 lies.
x2, y2 100%, 0% Where offset 1 lies. The default runs left to right.

radialGradient

Attribute Default Description
cx, cy 50% Center of the end circle (offset 1).
r 50% Radius of the end circle.
fx, fy Same as cx, cy The focal point, where offset 0 starts. Moving it off-center gives a highlight.
fr 0% Radius of the start circle (SVG 2).

stop

Attribute Values Description
offset 0โ€“1 or a percentage Position along the gradient. A stop with a smaller offset than the one before it is treated as equal to it.
stop-color Any CSS color The color at this position. Can also be set in CSS (stop-color: var(--brand)).
stop-opacity 0โ€“1 The color's opacity.

pattern

Attribute Values Default Description
x, y, width, height Length 0 The first tile's position and size. A zero size disables the pattern.
patternUnits objectBoundingBox, userSpaceOnUse objectBoundingBox The units of x, y, width and height.
patternContentUnits objectBoundingBox, userSpaceOnUse userSpaceOnUse The units of the content inside the tile. Ignored when the pattern has a viewBox.
viewBox, preserveAspectRatio (none) A coordinate system for the tile's content, scaled to the tile size.
patternTransform A transform list (none) Rotates or scales the whole tiling, for example diagonal stripes with rotate(45).
href #id (none) Inherit attributes and content from another pattern.

spreadMethod and units

pad, reflect and repeat

The second and third gradients use href="#pad" to copy the first one's coordinates and stops, and only change spreadMethod.

objectBoundingBox vs userSpaceOnUse

Radial gradients and patterns

A shiny sphere with a focal point

The left sphere's focal point (fx, fy) is up and to the left of the center, so the white highlight sits there and the colors bunch up toward the top-left edge. The right one uses href to reuse the stops with the focal point back in the center.

Patterns: dots, stripes and a checkerboard

The dots and stripes use patternUnits="userSpaceOnUse", so the tiles are 16 and 12 units no matter how big the shape is. The checkerboard keeps the default objectBoundingBox, so width="0.25" means "a quarter of the shape", and its viewBox scales the 2 ร— 2 tile content to fit.

Usage notes

  • Put paint servers in <defs>. They are never drawn by themselves, but <defs> makes the intent clear. They can live in any SVG on the page; the reference works across inline SVGs because IDs are page-wide.
  • Unique IDs. If the same inline SVG appears twice (or two icons both define id="grad"), every reference resolves to the first match in the document. Generate unique IDs in components.
  • Don't hide the defining SVG with display: none. Some browsers then stop painting gradients and patterns that live inside it. Use width="0" height="0" and position: absolute instead.
  • Strokes and lines. With the default objectBoundingBox, a gradient on a perfectly horizontal or vertical <line> doesn't render, because the line's box has zero height or width. Use gradientUnits="userSpaceOnUse" for those.
  • CSS can set colors. stop-color and stop-opacity are properties, so stops can use CSS variables and change with dark mode. The stop positions and gradient geometry can only be set as attributes.
  • Prefer CSS gradients for HTML boxes. For backgrounds of normal HTML elements, CSS linear-gradient() and radial-gradient() are simpler. SVG gradients are for SVG shapes, strokes and text.

Technical summary

Permitted content Gradients: <stop>, <animate>, <set>, <animateTransform> and descriptive elements. <stop>: <animate>, <set>. <pattern>: any SVG content (shapes, text, <use>, images)
Permitted parents Usually <defs>, but any SVG container element works; <stop> only inside a gradient
Tag omission End tags required (or self-closing, such as <stop โ€ฆ />)
Implicit ARIA role Not exposed (never rendered directly)
DOM interface SVGLinearGradientElement, SVGRadialGradientElement (both from SVGGradientElement), SVGStopElement, SVGPatternElement

Browser support

All four elements are supported in every browser. The SVG 2 additions (fr on radial gradients, plain href instead of xlink:href, and the fallback color after url()) work in all current browsers.