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.
height
The height to give the new ImageData object.
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 are zero.

Examples

Using the createImageData method

This is just a simple code snippet which uses the createImageData method. For more information, see Pixel manipulation with canvas and the ImageData object.

HTML

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

JavaScript

var canvas = document.getElementById('canvas');
var ctx = canvas.getContext('2d');
ctx.rect(10, 10, 100, 100);
ctx.fill();
console.log(ctx.createImageData(100, 100)); 
// ImageData { width: 100, height: 100, data: Uint8ClampedArray[40000] }

Specifications

Specification Status Comment
WHATWG HTML Living Standard
The definition of 'CanvasRenderingContext2D.createImageData' in that specification.
Living Standard  

Browser compatibility

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari
Basic support (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)
Feature Android Chrome for Android Edge Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support (Yes) (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)

Compatibility notes

  • Starting with (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2):
    • createImageData() now correctly return 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 handle 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: nmve, erikadoyle, fscholz
 Last updated by: nmve,