The CanvasRenderingContext2D.drawImage()
method of the Canvas 2D API provides different ways to draw an image onto the canvas.
The CanvasRenderingContext2D.drawImage()
method of the Canvas 2D API provides different ways to draw an image onto the canvas.
js
drawImage(image, dx, dy) drawImage(image, dx, dy, dWidth, dHeight) drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)
image
An element to draw into the context. The specification permits any canvas image source, specifically, an HTMLImageElement
, an SVGImageElement
, an HTMLVideoElement
, an HTMLCanvasElement
, an ImageBitmap
, an OffscreenCanvas
, or a VideoFrame
.
sx
Optional
The x-axis coordinate of the top left corner of the sub-rectangle of the source image
to draw into the destination context. Use the 3- or 5-argument syntax to omit this argument.
sy
Optional
The y-axis coordinate of the top left corner of the sub-rectangle of the source image
to draw into the destination context. Use the 3- or 5-argument syntax to omit this argument.
sWidth
Optional
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. Use the 3- or 5-argument syntax to omit this argument. A negative value will flip the image.
sHeight
Optional
The height of the sub-rectangle of the source image
to draw into the destination context. Use the 3- or 5-argument syntax to omit this argument. A negative value will flip the image.
dx
The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image
.
dy
The y-axis 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. Note that this argument is not included in the 3-argument syntax.
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. Note that this argument is not included in the 3-argument syntax.
None (undefined
).
InvalidStateError
DOMException
Thrown when the image has no image data or if the canvas or source rectangle width or height is zero.
TypeMismatchError
DOMException
Thrown when a null
or undefined
image is passed as parameter.
This example draws an image to the canvas using the drawImage()
method.
html
<canvas id="canvas"></canvas> <div style="display:none;"> <img id="source" src="rhino.jpg" width="300" height="227" /> </div>
The source image is taken from the coordinates (33, 71), with a width of 104 and a height of 124. It is drawn to the canvas at (21, 20), where it is given a width of 87 and a height of 104.
js
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); });
The drawImage()
method uses the source element's intrinsic size in CSS pixels when drawing.
For example, if you load an Image
and specify the optional size parameters in its constructor, you will have to use the naturalWidth
and naturalHeight
properties of the created instance to properly calculate things like crop and scale regions, rather than element.width
and element.height
. The same goes for videoWidth
and videoHeight
if the element is a <video>
element, and so on.
html
<canvas id="canvas"></canvas>
js
const canvas = document.getElementById("canvas"); const ctx = canvas.getContext("2d"); const image = new Image(60, 45); // Using optional size for image image.onload = drawImageActualSize; // Draw when image has loaded // Load an image of intrinsic size 300x227 in CSS pixels image.src = "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); }
Specification |
---|
HTML Standard # dom-context-2d-drawimage-dev |
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
ImageBitmap_source_image |
30 | 79 | 42 | No | 17 | 15 | ≤37 | 30 | 42 | 18 | 15 | 2.0 |
SVGImageElement_source_image |
59 | 12 | 56 | No | 46 | 17 | 59 | 59 | 56 | 43 | 17 | 7.0 |
drawImage |
1 | 12 | 1.5 | 9 | 9 | 2 | 4.4 | 18 | 4 | 10.1 | 1 | 1.0 |
drawImage()
only works correctly on an HTMLVideoElement
when its HTMLMediaElement.readyState
is greater than 1 (i.e., seek event fired after setting the currentTime
property). drawImage()
will always use the source element's intrinsic size in CSS pixels when drawing, cropping, and/or scaling.drawImage()
will ignore all EXIF metadata in images, including the Orientation. This behavior is especially troublesome on iOS devices. You should detect the Orientation yourself and use rotate()
to make it right. CanvasRenderingContext2D
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage