CanvasRenderingContext2D.createImageData()

The CanvasRenderingContext2D.createImageData() method of the Canvas 2D API creates a new, blank ImageData object with the specified dimensions. All of the pixels in the new object are transparent black.

Syntax

ImageData ctx.createImageData(width, height);
ImageData ctx.createImageData(imagedata);

Parameters

width
The width to give the new ImageData object. A negative value flips the rectangle around the vertical axis.
height
The height to give the new ImageData object. A negative value flips the rectangle around the horizontal axis.
imagedata
An existing ImageData object from which to copy the width and height. The image itself is not copied.

Return value

A new ImageData object with the specified width and height. The new object is filled with transparent black pixels.

Errors thrown

IndexSizeError
Thrown if either of the width or height arguments is zero.

Examples

Creating a blank ImageData object

This snippet creates a blank ImageData object using the createImageData() method.

HTML

<canvas id="canvas"></canvas>

JavaScript

The generated object is 100 pixels wide and 50 pixels tall, making 5,000 pixels in all. Each pixel within an ImageData object consists of four array values, so the object's data property has  a length of 4 × 5,000, or 20,000.

const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');

const imageData = ctx.createImageData(100, 50);
console.log(imageData);
// ImageData { width: 100, height: 50, data: Uint8ClampedArray[20000] }

Filling a blank ImageData object

This example creates and fills a new ImageData object with purple pixels.

HTML

<canvas id="canvas"></canvas>

JavaScript

Since each pixel consists of four values, the for loop iterates by multiples of four. The array values associated with each pixel are R (red), G (green), B (blue), and A (alpha), in that order.

const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');
const imageData = ctx.createImageData(100, 100);

// Iterate through every pixel
for (let i = 0; i < imageData.data.length; i += 4) {
  // Modify pixel data
  imageData.data[i + 0] = 190;  // R value
  imageData.data[i + 1] = 0;    // G value
  imageData.data[i + 2] = 210;  // B value
  imageData.data[i + 3] = 255;  // A value
}

// Draw image data to the canvas
ctx.putImageData(imageData, 20, 20);

Result

More examples

For more examples using createImageData() and the ImageData object, see Pixel manipulation with canvas and ImageData.data.

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'CanvasRenderingContext2D.createImageData' 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 YesEdge Full support 12Firefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes

Legend

Full support  
Full support

Gecko-specific notes

  • Starting with (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2):
    • createImageData() now correctly returns at least one pixel's worth of image data if a rectangle smaller than one pixel is specified.
    • Specifying non-finite values when calling createImageData() now properly throws a NOT_SUPPORTED_ERR exception.
    • createImageData() now handles negative arguments in accordance with the specification, by flipping the rectangle around the appropriate axis.

See also

Document Tags and Contributors

Contributors to this page: mfluehr, danzen, fscholz, jpmedley, nmve, erikadoyle
Last updated by: mfluehr,