self.createImageBitmap()

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

createImageBitmap(image[, options]).then(function(response) { ... });
createImageBitmap(image, sx, sy, sw, sh[, options]).then(function(response) { ... });

Parameters

image
An image source, which can be an <img>, SVG <image>, <video>, <canvas>, HTMLImageElement, SVGImageElement, HTMLVideoElement, HTMLCanvasElementBlob, ImageData, ImageBitmap, or OffscreenCanvas 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. Either none (default) or flipY.
  • premultiplyAlpha: Specifies whether the bitmap's color channels should be premultiplied by the alpha channel. One of none, premultiply, or default (default).
  • colorSpaceConversion: Specifies whether the image should be decoded using color space conversion. Either none or default (default). The value default 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 of pixelated, low (default), medium, or high.

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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Basic supportChrome Full support 50Edge No support NoFirefox Full support 42
Full support 42
Full support 52
Notes
Notes createImageBitmap() now defined on WindowOrWorkerGlobalScope mixin.
IE No support NoOpera Full support YesSafari No support NoWebView Android Full support 50Chrome Android Full support 50Edge Mobile ? Firefox Android ? Opera Android Full support YesSafari iOS ? Samsung Internet Android ?
options parameterChrome Full support 52Edge No support NoFirefox ? IE No support NoOpera Full support 39Safari No support NoWebView Android Full support 52Chrome Android Full support 52Edge Mobile ? Firefox Android ? Opera Android Full support 39Safari iOS ? Samsung Internet Android ?
resizeWidth, resizeHeight, and resizeQualityChrome Full support 54Edge No support NoFirefox ? IE No support NoOpera Full support YesSafari No support NoWebView Android Full support 54Chrome Android Full support 54Edge Mobile ? Firefox Android ? Opera Android Full support YesSafari iOS ? Samsung Internet Android ?
SVGImageElement as source imageChrome Full support 59Edge No support NoFirefox ? IE No support NoOpera Full support YesSafari No support NoWebView Android Full support 59Chrome Android Full support 59Edge Mobile ? Firefox Android ? Opera Android Full support YesSafari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
See implementation notes.
See implementation notes.

See also

Document Tags and Contributors

Last updated by: mfluehr,