createRadialGradient (creates a path styling object)

suggest change
var gradient = createRadialGradient( 
      centerX1, centerY1, radius1,     // this is the "display' circle
      centerX2, centerY2, radius2      // this is the "light casting" circle
gradient.addColorStop(gradientPercentPosition, CssColor)
gradient.addColorStop(gradientPercentPosition, CssColor)
[optionally add more color stops to add to the variety of the gradient]

Creates a reusable radial gradient (object). The gradient object is an object that you can use (and reuse!) to make your path strokes and fills become gradient colored.


The Canvas radial gradient is extremely different from traditional radial gradients.

The “official” (almost undecipherable!) definition of Canvas’s radial gradient is at the bottom of this posting. Don’t look at it if you have a weak disposition!!

In (almost understandable) terms:

Creating a gradient object is a 2-step process:

  1. Create the gradient object itself. During creation you define a line on the canvas where the gradient will start and end. The gradient object is created with var gradient = context.radialLinearGradient.
  2. Then add 2 (or more) colors that make up the gradient. This is done by adding multiple color stops to the gradient object with gradient.addColorStop.


Side Note: The gradient object is not internal to the Canvas element nor it’s Context. It is a separate and reusable JavaScript object that you can assign to any Path you desire. You can even use this object to color a Path on a different Canvas element(!)

Color stops are (percentage) waypoints along the gradient line. At each color stop waypoint, the gradient is fully (==opaquely) colored with it’s assigned color. Interim points along the gradient line between color stops are colored as gradients of the this and the previous color.

Important hint about Canvas gradients!

When you create a gradient object, the entire radial gradient is “invisibly” cast upon the canvas.

When you stroke() or fill() a path, the invisible gradient is revealed, but only revealed over that path being stroked or filled.

  1. If you create a green-to-red radial gradient like this:
    // create a radialGradient
    var x1=150;
    var y1=150;
    var x2=280;
    var y2=150;
    var r1=100;
    var r2=120;
    var gradient=ctx.createRadialGradient(x1,y1,r1,x2,y2,r2);
  2. Then Canvas will “invisibly” see your gradient creation like this:
  3. But until you stroke() or fill() with the gradient, you will see none of the gradient on the Canvas.
  4. Finally, if you stroke or fill a path using the gradient, the “invisible” gradient becomes visible on the Canvas … but only where the path is drawn.
<!doctype html>
    body{ background-color:white; padding:10px; }
    #canvas{border:1px solid blue; }

    // canvas related vars
    var canvas=document.getElementById("canvas");
    var ctx=canvas.getContext("2d");
    // create a radial gradient
    var x1=150;
    var y1=175;
    var x2=350;
    var y2=175;
    var r1=100;
    var r2=40;
    var gradient=ctx.createRadialGradient(x1,y1,r1,x2,y2,r2);

    // fill a path with the gradient

}); // end window.onload
    <canvas id="canvas" width=300 height=325></canvas>

The scary official details

Who decides what `createRadialGradient does?

The W3C issues the official recommended specifications that browsers use to build the Html5 Canvas element.

The W3C specification for createRadialGradient cryptically reads like this:

What does createRadialGradient create

createRadialGradient … effectively creates a cone, touched by the two circles defined in the creation of the gradient, with the part of the cone before the start circle (0.0) using the color of the first offset, the part of the cone after the end circle (1.0) using the color of the last offset, and areas outside the cone untouched by the gradient (transparent black).

How does it work internally

The createRadialGradient(x0, y0, r0, x1, y1, r1) method takes six arguments, the first three representing the start circle with origin (x0, y0) and radius r0, and the last three representing the end circle with origin (x1, y1) and radius r1. The values are in coordinate space units. If either of r0 or r1 are negative, an IndexSizeError exception must be thrown. Otherwise, the method must return a radial CanvasGradient initialized with the two specified circles.

Radial gradients must be rendered by following these steps:

  1. If x0 = x1 and y0 = y1 and r0 = r1, then the radial gradient must paint nothing. Abort these steps.
  2. Let x(ω) = (x1-x0)ω + x0; Let y(ω) = (y1-y0)ω + y0; Let r(ω) = (r1-r0)ω + r0 Let the color at ω be the color at that position on the gradient (with the colors coming from the interpolation and extrapolation described above).
  3. For all values of ω where r(ω) > 0, starting with the value of ω nearest to positive infinity and ending with the value of ω nearest to negative infinity, draw the circumference of the circle with radius r(ω) at position (x(ω), y(ω)), with the color at ω, but only painting on the parts of the canvas that have not yet been painted on by earlier circles in this step for this rendering of the gradient.

Feedback about page:

Optional: your email if you want me to get back to you:

Table Of Contents