The createImageBitmap()
method creates a bitmap from a given source, optionally cropped to contain only a portion of that source. The method exists on the global scope in both windows and workers. It accepts a variety of different image sources, and returns a Promise
which resolves to an ImageBitmap
.
Syntax
const imageBitmapPromise = createImageBitmap(image[, options]); const imageBitmapPromise = createImageBitmap(image, sx, sy, sw, sh[, options]);
Parameters
image
- An image source, which can be an
<img>
, SVG<image>
,<video>
,<canvas>
,HTMLImageElement
,SVGImageElement
,HTMLVideoElement
,HTMLCanvasElement
,Blob
,ImageData
,ImageBitmap
, orOffscreenCanvas
object. sx
- The x coordinate of the reference point of the rectangle from which the
ImageBitmap
will be extracted. sy
- The y coordinate of the reference point of the rectangle from which the
ImageBitmap
will be extracted. sw
- The width of the rectangle from which the
ImageBitmap
will be extracted. This value can be negative. sh
- The height of the rectangle from which the
ImageBitmap
will be extracted. This value can be negative. options
Optional- An object that sets options for the image's extraction. The available options are:
imageOrientation
: Specifies whether the image should be presented as is or flipped vertically. Eithernone
(default) orflipY
.premultiplyAlpha
: Specifies whether the bitmap's color channels should be premultiplied by the alpha channel. One ofnone
,premultiply
, ordefault
(default).colorSpaceConversion
: Specifies whether the image should be decoded using color space conversion. Eithernone
ordefault
(default). The valuedefault
indicates that implementation-specific behavior is used.resizeWidth
: A long integer that indicates the output width.resizeHeight
: A long integer that indicates the output height.resizeQuality
: Specifies the algorithm to be used for resizing the input to match the output dimensions. One ofpixelated
,low
(default),medium
, orhigh
.
Return value
A Promise
which resolves to an ImageBitmap
object containing bitmap data from the given rectangle.
Example
Creating sprites from a sprite sheet
This example loads a sprite sheet, extracts individual sprites, and then renders each sprite to the canvas. A sprite sheet is an image containing multiple smaller images, each of which you want to be able to render separately.
var canvas = document.getElementById('myCanvas'), ctx = canvas.getContext('2d'), image = new Image(); // Wait for the sprite sheet to load image.onload = function() { Promise.all([ // Cut out two sprites from the sprite sheet createImageBitmap(image, 0, 0, 32, 32), createImageBitmap(image, 32, 0, 32, 32) ]).then(function(sprites) { // Draw each sprite onto the canvas ctx.drawImage(sprites[0], 0, 0); ctx.drawImage(sprites[1], 32, 32); }); } // Load the sprite sheet from an image file image.src = 'sprites.png';
Specifications
Specification | Status | Comment |
---|---|---|
HTML Living Standard The definition of 'createImageBitmap' in that specification. |
Living Standard |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
createImageBitmap | Chrome Full support 50 | Edge Full support 79 | Firefox
Full support
52
| IE No support No | Opera Full support Yes | Safari No support No | WebView Android Full support 50 | Chrome Android Full support 50 | Firefox Android Full support Yes | Opera Android Full support Yes | Safari iOS ? | Samsung Internet Android Full support 5.0 |
options parameter | Chrome Full support 52 | Edge Full support 79 | Firefox No support No | IE No support No | Opera Full support 39 | Safari No support No | WebView Android Full support 52 | Chrome Android Full support 52 | Firefox Android No support No | Opera Android Full support 41 | Safari iOS ? | Samsung Internet Android Full support 6.0 |
resizeWidth , resizeHeight , and resizeQuality | Chrome Full support 54 | Edge Full support 79 | Firefox No support No | IE No support No | Opera Full support Yes | Safari No support No | WebView Android Full support 54 | Chrome Android Full support 54 | Firefox Android No support No | Opera Android Full support Yes | Safari iOS ? | Samsung Internet Android Full support 6.0 |
SVGImageElement as source image | Chrome Full support 59 | Edge Full support 79 | Firefox Full support 65 | IE No support No | Opera Full support Yes | Safari No support No | WebView Android Full support 59 | Chrome Android Full support 59 | Firefox Android Full support 65 | Opera Android Full support Yes | Safari iOS ? | Samsung Internet Android Full support 7.0 |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- See implementation notes.
- See implementation notes.