This page is Ready to Use

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

addColorStop

Summary

Adds a new stop to a gradient. If offset is less than 0 or greater than 1 then an IndexSizeError exception must be thrown. If the color cannot be parsed as a CSS <color> value, then a SyntaxError exception must be thrown. Otherwise the gradient must have a new stop placed, at offset offset relative to the whole gradient, and with the color obtained by parsing color as a CSS <color> value.

Method of apis/canvas/CanvasGradientapis/canvas/CanvasGradient

Syntax

var object = CanvasGradient.addColorStop(offset, color);

Parameters

offset

Data-type
any

A floating point value between 0.0 and 1.0 that represents the position between the start and end points in a gradient.

color

Data-type
any

A CSS color string to display at the position that the offset parameter specifies.

Return Value

Returns an object of type DOM NodeDOM Node

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Examples

The following code example creates a gradient.

<!DOCTYPE html>
<html>
<head>
  <script type="text/javascript">
function draw()
{
  var canvas = document.getElementById("MyCanvas");
    if (canvas.getContext) {
      var ctx = canvas.getContext("2d");
      gradient = ctx.createLinearGradient(0, 0, canvas.width, 0);
  // Add the colors with fixed stops at 1/4 of the width.
      gradient.addColorStop("0","magenta");
      gradient.addColorStop(".25","blue");
      gradient.addColorStop(".50","green");
      gradient.addColorStop(".75","yellow");
      gradient.addColorStop("1.0","red");

      // Use the gradient.
      ctx.fillStyle = gradient;
      ctx.fillRect (0,0,300,250);
      ctx.fillRect(250,300,600,500);
    }
}
  </script>
</head>
<body>
  <canvas id="MyCanvas" width="600" height="500" border="1"> </canvas>
    <button onclick="draw()">Click me</button>
</body>
</html>

Notes

You can call the addColorStop method multiple times to change a gradient. If you never call this method for CanvasGradient, the gradient is not visible. You need to create at least one color stop to have a visible gradient.

Related specifications

W3C HTML Canvas 2D Specification
W3C Candidate Recommendation

Attributions