SVG gradients: linear, radial, and reusable color

Create a linear gradient

A linear gradient interpolates colors along a vector from x1,y1 to x2,y2. Stops define colors and positions. Refer to the gradient with fill="url(#id)".

<defs>
  <linearGradient id="sky" x1="0%" y1="0%" x2="100%" y2="100%">
    <stop offset="0%" stop-color="#276ef1" />
    <stop offset="100%" stop-color="#0aaaa6" />
  </linearGradient>
</defs>
<rect width="240" height="140" rx="20" fill="url(#sky)" />

Offsets normally run from 0 to 1 or from 0% to 100%. Stops do not need equal spacing. Put two stops close together for a sharp transition, or repeat an offset to create a hard boundary.

Choose the right coordinate system

The default gradientUnits="objectBoundingBox" maps values to each painted element's bounding box. A gradient from 0% to 100% stretches across every object independently. This is convenient for reusable buttons and icons, but circles, thin paths, and differently proportioned shapes can make the same gradient look inconsistent.

Use gradientUnits="userSpaceOnUse" when coordinates should align with the SVG canvas. A single light-to-dark transition can then continue across several objects. With user-space units, use actual coordinates such as x1="0" and x2="240". The MDN gradientUnits reference explains how percentages resolve in both systems and why a radial gradient can become elliptical on a non-square object bounding box.

Build a radial gradient

A radial gradient uses a center cx,cy, radius r, and optional focal point fx,fy. Moving the focal point creates directional lighting while the outer circle stays fixed.

<radialGradient id="orb" cx="50%" cy="50%" r="50%"
                fx="35%" fy="30%">
  <stop offset="0%" stop-color="#ffffff" />
  <stop offset="45%" stop-color="#70a4ff" />
  <stop offset="100%" stop-color="#163b82" />
</radialGradient>

Keep the focal point inside the ending circle for predictable results. If a radial gradient appears oval, check the object's aspect ratio and gradient units. The default bounding-box mapping can stretch the gradient along with a rectangular object.

Control spread and direction

spreadMethod="pad" extends the first and last stop colors beyond the gradient range. repeat repeats the sequence in the same direction. reflect alternates direction to avoid a visible jump at each repeat.

gradientTransform rotates, scales, or moves the gradient without transforming the painted geometry. This is useful for rotating a highlight while leaving an icon untouched. Apply one transform at a time and inspect the result because the gradient's own units affect the transform.

Control color and transparency at each stop

Each stop can set stop-color and stop-opacity. Use stop opacity when the gradient itself should fade to transparency, and remember that the color channels under a transparent stop can still affect interpolation before compositing.

CSS can target stops by class, which is helpful for theming, but it also means a page stylesheet can override presentation attributes inside inline SVG. When a pasted gradient changes color unexpectedly, inspect the computed stop-color and stop-opacity values before rewriting the definition.

Reuse and extend definitions

Several elements can reference one gradient ID. A second gradient can reference a base definition with href="#baseGradient" and override selected attributes. This reduces repeated stop lists and keeps a color system consistent.

IDs must be unique within the document. When combining exported SVG fragments, duplicate IDs can cause one object's fill to unexpectedly use another object's gradient. Rename both the definition and every matching url(#id) reference. Keep IDs short but descriptive enough to debug.

Gradient debugging checklist

1. Confirm the referenced ID exists and is unique.
2. Check whether the paint belongs on fill or stroke.
3. Choose object-bounding-box or user-space units deliberately.
4. Keep stop offsets ordered and within the intended range.
5. Inspect stop opacity as well as stop color.
6. Test transforms after the base gradient works.
7. Provide a sensible solid-color fallback where older or constrained renderers matter.

Paste the complete SVG into SVG Vector Lab to inspect its definitions and rendered result together. After the paint is correct, use the SVG optimization guide to remove duplicate definitions without breaking references.