CanvasRenderingContext2D: createImageData() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨July 2015⁩.

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

createImageData(width, height)
createImageData(width, height, settings)
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.

settings Optional

An object with the following properties:

colorSpace

Specifies the color space of the image data. Can be set to "srgb" for the sRGB color space or "display-p3" for the display-p3 color space.

pixelFormat

Specifies the pixel format. Possible values:

"rgba-unorm8", for RGBA with 8 bit per component unsigned normalized format, using a Uint8ClampedArray.
"rgba-float16", for RGBA with 16 bits per component, using a Float16Array. Floating-point pixel values allow representing colors in arbitrarily wide gamuts and high dynamic range (HDR).

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.

Exceptions

IndexSizeError DOMException: 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>

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>

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);