CanvasRenderingContext2D.drawImage()

The CanvasRenderingContext2D.drawImage() method of the Canvas 2D API provides different ways to draw an image onto the canvas.

Syntax

void ctx.drawImage(image, dx, dy);
void ctx.drawImage(image, dx, dy, dWidth, dHeight);
void ctx.drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight);

drawImage

Parameters

image
An element to draw into the context. The specification permits any canvas image source (CanvasImageSource), such as an HTMLImageElement, an HTMLVideoElement, an HTMLCanvasElement or an ImageBitmap.
dx
The X coordinate in the destination canvas at which to place the top-left corner of the source image.
dy
The Y coordinate in the destination canvas at which to place the top-left corner of the source image.
dWidth
The width to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in width when drawn.
dHeight
The height to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in height when drawn.
sx
The X coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
sy
The Y coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
sWidth
The width of the sub-rectangle of the source image to draw into the destination context. If not specified, the entire rectangle from the coordinates specified by sx and sy to the bottom-right corner of the image is used.
sHeight
The height of the sub-rectangle of the source image to draw into the destination context.

Exceptions thrown

INDEX_SIZE_ERR
If the canvas or source rectangle width or height is zero.
INVALID_STATE_ERR
The image has no image data.
TYPE_MISMATCH_ERR
The specified source element isn't supported.

Examples

Using the drawImage method

This is just a simple code snippet which uses the drawImage method.

HTML

<canvas id="canvas"></canvas>
<div style="display:none;">
  <img id="source" src="https://mdn.mozillademos.org/files/5397/rhino.jpg"
       width="300" height="227">
</div>

JavaScript

var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");
var image = document.getElementById("source");

ctx.drawImage(image, 33, 71, 104, 124, 21, 20, 87, 104);

Edit the code below and see your changes update live in the canvas:

Playable code
<canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas>
<div style="display:none;">
  <img id="source" src="https://mdn.mozillademos.org/files/5397/rhino.jpg" width="300" height="227">
</div>
<div class="playable-buttons">
  <input id="edit" type="button" value="Edit" />
  <input id="reset" type="button" value="Reset" />
</div>
<textarea id="code" class="playable-code">
ctx.drawImage(image, 33, 71, 104, 124, 21, 20, 87, 104);</textarea>
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");
var image = document.getElementById('source');
var textarea = document.getElementById("code");
var reset = document.getElementById("reset");
var edit = document.getElementById("edit");
var code = textarea.value;

function drawCanvas() {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  eval(textarea.value);
}

reset.addEventListener("click", function() {
  textarea.value = code;
  drawCanvas();
});

edit.addEventListener("click", function() {
  textarea.focus();
})

textarea.addEventListener("input", drawCanvas);
window.addEventListener("load", drawCanvas);

Specifications

Specification Status Comment
WHATWG HTML Living Standard
The definition of 'CanvasRenderingContext2D.drawImage' in that specification.
Living Standard  

Browser compatibility

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari
Basic support (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)
ImageBitmap as source image ? ? 42 (42) ? ? ?
Feature Android Chrome for Android Edge Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support (Yes) (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)
ImageBitmap as source image ? ? ? 42.0 (42) ? ? ?

Compatibility notes

  • Support for flipping the image by using negative values for sw and sh was added in Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2).
  • Starting with (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2) drawImage() handles negative arguments in accordance with the specification, by flipping the rectangle around the appropriate axis.
  • Specifying a null or undefined image when calling or drawImage() correctly throws a TYPE_MISMATCH_ERR exception starting with (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2).
  • Prior to Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4), Firefox threw an exception if any of the coordinate values was non-finite or zero. As per the specification, this no longer happens.
  • Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6) now correctly supports CORS for drawing images across domains without tainting the canvas.
  • Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8) now allows SVG-as-an-image to be drawn into a canvas without tainting the canvas.

Notes

See also

Document Tags and Contributors

 Contributors to this page: erikadoyle, QihangSun, wdgreg, fscholz, Kaku, figure002, lukasolson
 Last updated by: erikadoyle,