TheCanvasRenderingContext2D.drawImage() method of theCanvas 2D API provides different ways to draw an image onto the canvas.

Syntax

drawImage(image, dx, dy)drawImage(image, dx, dy, dWidth, dHeight)drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)

Parameters

image

An element to draw into the context. The specification permits any canvas imagesource, specifically,anHTMLImageElement,anSVGImageElement,anHTMLVideoElement,anHTMLCanvasElement,anImageBitmap,anOffscreenCanvas,or aVideoFrame.

sxOptional

The x-axis coordinate of the top left corner of the sub-rectangle of the sourceimage to draw into the destination context. Use the 3- or 5-argument syntaxto omit this argument.

syOptional

The y-axis coordinate of the top left corner of the sub-rectangle of the sourceimage to draw into the destination context. Use the 3- or 5-argument syntaxto omit this argument.

sWidthOptional

The width of the sub-rectangle of the sourceimage to draw into thedestination context. If not specified, the entire rectangle from the coordinatesspecified bysx andsy to the bottom-right corner of theimage is used. Use the 3- or 5-argument syntax to omit this argument.Negative values grow the sub-rectangle in the opposite direction, but pixels are always processed in the original direction and the image is not flipped.

sHeightOptional

The height of the sub-rectangle of the sourceimage to draw into thedestination context. Use the 3- or 5-argument syntax to omit this argument.Negative values grow the sub-rectangle in the opposite direction, but pixels are always processed in the original direction and the image is not flipped.

dx

The x-axis coordinate in the destination canvas at which to place the top-leftcorner of the sourceimage.

dy

The y-axis coordinate in the destination canvas at which to place the top-leftcorner of the sourceimage.

dWidth

The width to draw theimage in the destination canvas. This allowsscaling of the drawn image. If not specified, the image is not scaled in width whendrawn. Note that this argument is not included in the 3-argument syntax.Negative values grow the sub-rectangle in the opposite direction, but pixels are always processed in the original direction and the image is not flipped.

dHeight

The height to draw theimage in the destination canvas. This allowsscaling of the drawn image. If not specified, the image is not scaled in height whendrawn. Note that this argument is not included in the 3-argument syntax.Negative values grow the sub-rectangle in the opposite direction, but pixels are always processed in the original direction and the image is not flipped.

Return value

None (undefined).

Exceptions

InvalidStateErrorDOMException

Thrown when the image has no image data or if the canvas or source rectangle width or height is zero.

TypeMismatchErrorDOMException

Thrown when anull orundefined image is passed as parameter.

Examples

Drawing an image to the canvas

This example draws an image to the canvas using thedrawImage() method.

HTML

<canvas></canvas><div>  <img       src="https://mdn.github.io/shared-assets/images/examples/rhino.jpg"    width="300"    height="227" /></div>

.hidden {  display: none;}

JavaScript

The source image is taken from the coordinates (33, 71), with a width of 104 and aheight of 124. It is drawn to the canvas at (21, 20), where it is given a width of 87and a height of 104.

const canvas = document.getElementById("canvas");const ctx = canvas.getContext("2d");const image = document.getElementById("source");image.addEventListener("load", (e) => {  ctx.drawImage(image, 33, 71, 104, 124, 21, 20, 87, 104);});

Result

Understanding source element size

ThedrawImage() method uses the source element'sintrinsic size in CSSpixels when drawing.

For example, if you load anImage and specify the optional size parametersin itsconstructor, you willhave to use thenaturalWidth andnaturalHeight properties ofthe created instance to properly calculate things like crop and scale regions, ratherthanelement.width andelement.height. The same goes forvideoWidth andvideoHeight if the element is a<video> element, and so on.

HTML

<canvas></canvas>

JavaScript

const canvas = document.getElementById("canvas");const ctx = canvas.getContext("2d");const image = new Image(60, 45); // Using optional size for imageimage.onload = drawImageActualSize; // Draw when image has loaded// Load an image of intrinsic size 300x227 in CSS pixelsimage.src = "https://mdn.github.io/shared-assets/images/examples/rhino.jpg";function drawImageActualSize() {  // Use the intrinsic size of image in CSS pixels for the canvas element  canvas.width = this.naturalWidth;  canvas.height = this.naturalHeight;  // Will draw the image as 300x227, ignoring the custom size of 60x45  // given in the constructor  ctx.drawImage(this, 0, 0);  // To use the custom size we'll have to specify the scale parameters  // using the element's width and height properties - lets draw one  // on top in the corner:  ctx.drawImage(this, 0, 0, this.width, this.height);}

Result

Specifications

Browser compatibility

Notes

• drawImage() only works correctly on anHTMLVideoElementwhen itsHTMLMediaElement.readyState is greater than 1 (i.e.,seek event fired after setting thecurrentTimeproperty).
• drawImage() will always use the source element'sintrinsic size inCSS pixels when drawing, cropping, and/or scaling.
• In some older browser versions,drawImage() will ignore all EXIFmetadata in images, including the Orientation. This behavior is especially troublesomeon iOS devices. You should detect the Orientation yourself and userotate() to make it right.

See also

• The interface defining this method:CanvasRenderingContext2D