How to Use the canvas Element

The HTML canvas element creates a rectangular area where JavaScript can draw. Use it for graphics that a program creates or changes, such as charts, game screens, and image processing.

The answer first

Minimal example

<canvas id="chart" width="320" height="180">
  Chart data: January 12, February 18, March 14.
</canvas>
<p>The chart values are January 12, February 18, and March 14.</p>

<script>
  const canvas = document.querySelector("#chart");
  const context = canvas?.getContext("2d");

  if (context) {
    context.fillStyle = "#4c78c2";
    context.fillRect(24, 24, 80, 60);
  }
</script>

getContext("2d") returns the tools for drawing 2D shapes and text. The example draws only when a context is available.

What width and height control

The width and height attributes set the size of the drawing stored in the canvas. If omitted, the defaults are 300 pixels wide and 150 pixels high.

<canvas width="320" height="180"></canvas>

<style>
  canvas { width: 640px; height: 360px; }
</style>

This example enlarges a 320×180 drawing to 640×360 on the page. The HTML attributes set the drawing's dimensions, while CSS sets its displayed size. A different aspect ratio can make the drawing look stretched.

Setting canvas.width or canvas.height in JavaScript clears the drawing and resets the drawing state. That reset also happens if you assign the same number again, so do not keep setting dimensions when you only intend to adjust the display size.

Choose a drawing context

getContext("2d") is for 2D drawing. Other contexts, including WebGL, are available, but a canvas cannot switch to a different context type after one type has been initialized. Choose the type before you use it.

• Charts and simple shapes: 2d
• 3D graphics: a WebGL context
• If a context cannot be acquired: getContext() can return null

For a first project, decide whether you need to display an existing image or draw and change graphics with JavaScript.

Provide descriptions and ways to interact

Text written as a child of canvas is fallback content for conditions such as when scripts are unavailable. When a drawing is displayed, that text is not always layered visibly over the drawing. Provide important content, such as a diagram explanation or chart values, in HTML outside the canvas too.

If people can operate a control drawn inside the canvas, provide a keyboard-operable way to use it. The specification describes a correspondence between interactive regions and focusable fallback areas. For complex apps, ordinary HTML buttons and form controls may also be appropriate.

When drawing images from another site

You may be able to draw an image from another site into a canvas without being allowed to read its pixels or save the canvas as an image. If the image server does not grant permission through CORS, the browser can block pixel readback or export.

This security feature prevents one site's page from freely reading image data from another site. Being able to display an image and being able to read its image data are different things.

Common mistakes

• Changing only the CSS width and assuming the canvas drawing area has also changed.
• Expecting a drawing and context settings to survive a change to the width or height attribute.
• Putting important information only in drawn pixels without also explaining it as text.
• Assuming that an image from another site is readable just because it could be drawn.
• Building JavaScript drawing for a single static image that could be shown with a simple img.

Check it in Atlas

For bitmap and CSS display dimensions, context modes, resize resets, fallback descendants, origin-clean, and the limits of current implementation evidence, see canvas in Yugien Atlas. See img for alternative text and picture for selecting image candidates by display conditions.