Drawing with canvas

Canvas is pixels, not page elements

A <canvas> is a rectangle on the page that you draw on with JavaScript. The rectangle is a grid of tiny colored dots called pixels. You can paint rectangles, lines, text, pictures, and color fades into it. You can also change single pixels.

Canvas is a good fit for things that redraw often:

• games
• paint and drawing apps
• visual effects and music visualizers
• busy charts with many points

The most important idea is this: a drawing call only changes pixels. When you call ctx.fillRect(20, 20, 80, 40), the browser colors a block of pixels. It does not keep a rectangle object that you can find later and move.

To move the rectangle, you keep its position in your own JavaScript data. Then you clear the canvas and draw everything again at the new position. This style is called immediate mode: each call paints right away and is then forgotten.

This lesson only covers the 2D context. WebGL and WebGPU are separate tools for fast graphics drawn by the graphics card, such as 3D scenes. They draw on the same <canvas> element, but you write very different code for them.

You work with two objects:

• The canvas element. It is the rectangle on the page.
• The 2D context, usually saved in a variable called ctx. It is like a painter's toolbox. It has the drawing commands, and it remembers your settings.

The settings include the fill color (fillStyle), the outline color (strokeStyle), and the line thickness (lineWidth). The context also remembers moves and zooms (called transforms), a clipping area that limits where paint can land, and the current path. You'll meet paths in the next section.

1const canvas = document.querySelector("canvas");2const ctx = canvas.getContext("2d");3 4ctx.fillStyle = "royalblue";5ctx.fillRect(10, 10, 80, 40);6ctx.clearRect(0, 0, canvas.width, canvas.height);

Line 1 finds the canvas element. Line 2 asks it for the 2D context. Line 4 sets the fill color to blue. Line 5 paints a blue rectangle: 10 pixels from the left, 10 from the top, 80 wide, and 40 tall. Line 6 wipes the whole canvas clear again.

A canvas has two sizes, and they are easy to mix up:

• The width and height attributes set the drawing buffer: how many pixels the canvas really has. If you leave them out, the buffer is 300×150.
• The CSS width and height only set how big the canvas looks on the page. CSS stretches the buffer to fit.

Many phones and laptops have sharp screens that pack 2 or 3 real screen dots into one CSS pixel. The browser tells you this number in devicePixelRatio. On those screens, a small stretched buffer looks blurry. The fix is to make the buffer bigger by that number, then scale the drawing back down to CSS pixels.

1function resizeCanvas(canvas, cssWidth, cssHeight, dpr) {2  canvas.style.width = cssWidth + "px";3  canvas.style.height = cssHeight + "px";4  canvas.width = Math.round(cssWidth * dpr);5  canvas.height = Math.round(cssHeight * dpr);6  const ctx = canvas.getContext("2d");7  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);8  return ctx;9}10 11// With a device pixel ratio of 2: a 600×300 buffer.

Lines 2 and 3 set the size the canvas looks on the page. Lines 4 and 5 make the buffer bigger by the device pixel ratio. Line 7 scales the drawing, so your code can keep using CSS-sized numbers.

So with a device pixel ratio of 2, a canvas that is 300×150 on the page should have a 600×300 buffer. Your drawing code can still use numbers like 300 and 150, because setTransform(2, 0, 0, 2, 0, 0) doubles every number you draw with.

1ctx.fillStyle = "tomato";2ctx.save();3ctx.fillStyle = "royalblue";4ctx.fillRect(10, 10, 30, 30);5ctx.restore();6ctx.fillRect(50, 10, 30, 30);

Line 1 sets the fill color to tomato red. Line 2, save(), puts all current settings aside. Line 3 changes the color to blue, and line 4 paints a blue square. Line 5, restore(), brings back the saved settings, so the color is tomato red again. Line 6 paints a red square.

save() keeps colors, line width, transforms, and the clipping area. restore() does not erase pixels you already painted. Put the pair around a short change, so the drawing after it doesn't get the changed setting by accident.

1ctx.beginPath();2ctx.moveTo(20, 30);3ctx.lineTo(120, 30);4ctx.stroke();5 6ctx.beginPath();7ctx.moveTo(20, 70);8ctx.lineTo(120, 70);9ctx.stroke();

Lines 1 to 4 draw one line. Lines 6 to 9 draw a second line lower down. Each part starts with beginPath(). It throws away the old path that the context remembers. It does not erase any pixels.

If you skip beginPath() on line 6, the old line stays in the path. Then the second stroke() paints the first line again too.

1ctx.font = "16px sans-serif";2const label = "Canvas";3const width = ctx.measureText(label).width;4ctx.fillText(label, 10, 30);5console.log(Math.round(width) > 0);

Line 1 picks the font. Line 3 measures how wide the word will be, without drawing it. Line 4 paints the word at x = 10. The letters sit on an invisible line at y = 30, called the baseline. Line 5 prints true, because the width is more than 0.

Knowing the width first lets you center a label, or cut it short, before you paint it.

1canvas.width = 300;2canvas.height = 150;3canvas.style.width = "600px";4canvas.style.height = "300px";5console.log(canvas.width + "x" + canvas.height);

Lines 1 and 2 set the real drawing buffer to 300×150. Lines 3 and 4 only make it look 600×300 on the page. So line 5 still prints 300x150. To get more pixels to draw on, change the attributes, not the CSS.

1const canvas = document.querySelector("canvas");2const ctx = canvas.getContext("2d");3ctx.fillStyle = "#5b8def";4ctx.strokeStyle = "#1f2937";5ctx.lineWidth = 4;6ctx.fillRect(24, 24, 96, 56);7ctx.strokeRect(148, 24, 96, 56);8ctx.beginPath();9ctx.arc(92, 142, 36, 0, Math.PI * 2);10ctx.fill();11ctx.beginPath();12ctx.moveTo(170, 164);13ctx.lineTo(214, 106);14ctx.lineTo(258, 164);15ctx.closePath();16ctx.stroke();17ctx.fillText("Canvas", 24, 210);

Try the sharp/blurry button. The shapes stay the same; only the buffer size changes. You saw the same idea in Sizes, scrolling & coordinates: the browser usually measures in CSS pixels, but the screen may have more real dots than that.

Some canvas commands paint right away, like fillRect(). Paths work differently. A path is a sketch that the context keeps in memory. Nothing shows until you paint it. You build it step by step:

• beginPath() starts a new, empty sketch.
• moveTo(x, y) lifts the pencil and puts it at a point.
• lineTo(x, y) adds a straight line. arc() adds a curve.
• fill() paints the inside, or stroke() paints the outline. Only now do pixels change.

1const ctx = canvas.getContext("2d");2ctx.beginPath();Run3ctx.moveTo(52, 124);4ctx.lineTo(138, 42);5ctx.arc(194, 124, 42, Math.PI, 0);6ctx.closePath();7ctx.fill();

arc() measures angles in radians, not degrees. A full circle is Math.PI * 2. Half a circle is Math.PI. If you think in degrees, change them to radians first with degrees * Math.PI / 180.

Canvas can draw pictures, frames from a video, color fades, and shapes made by code. Once pixels are on the canvas, getImageData() copies them into an ImageData object.

Its data property holds the pixels as one long list of numbers. Each pixel uses four numbers in a row: red, green, blue, and alpha. Alpha says how see-through the pixel is. Every number is from 0 to 255. The list type is Uint8ClampedArray: a list that can only hold whole numbers from 0 to 255.

For example, to invert a picture (swap each color for its opposite), you set each color number to 255 - value. Alpha stays the same.

1const image = ctx.getImageData(0, 0, canvas.width, canvas.height);2for (let i = 0; i < image.data.length; i += 4) {3  const red = image.data[i];4  const green = image.data[i + 1];5  const blue = image.data[i + 2];6  image.data[i] = 255 - red;7  image.data[i + 1] = 255 - green;8  image.data[i + 2] = 255 - blue;9}10ctx.putImageData(image, 0, 0);

The lab draws its own picture with code, so reading its pixels is allowed. Pictures from another website are different. An origin is the address of a website, like https://example.com. If you draw a picture from another origin without its permission, the canvas becomes tainted: marked as unsafe to read. After that, getImageData() throws a SecurityError.

This rule protects private pictures. For example, a page should not be able to read the pixels of a photo that only shows because the visitor is logged in to another site.

const image = new Image();
image.onload = () => {
  ctx.drawImage(image, 0, 0);
  console.log("drawn after load");
};
image.src = "avatar.png";

Line 1 makes an empty image. Line 6 sets src, the picture's address, which starts the download. The pixels are not ready yet at that moment. Lines 2 to 5 set up onload, which runs when the download finishes. Only then does line 3 draw the picture with drawImage().

A picture from another origin also needs that site's permission before you can read its pixels. The site gives permission with a special response header, part of a system called CORS.

const image = new Image();
image.crossOrigin = "anonymous";
image.onload = () => {
  ctx.drawImage(image, 0, 0);
  try {
    ctx.getImageData(0, 0, 1, 1);
  } catch (error) {
    console.log(error.name);
  }
};
image.src = "https://example.com/photo.png";

Line 2 asks for permission by setting crossOrigin. It must come before src on line 11. If the other site does not allow it, the picture won't load, so onload never runs. Without line 2, the picture would still draw, but the canvas would be tainted. Then line 6 would throw, and line 8 would print SecurityError.

A tainted canvas still shows on the page. Only reading its pixels from code is blocked. Your page cannot give itself permission; only the other site can.

A canvas animation is usually a loop. Each turn of the loop is one frame, and it does five things:

1. Measure how much time has passed.
2. Update your own data, like a ball's position.
3. Clear the old pixels.
4. Draw the new frame.
5. Ask for the next frame with requestAnimationFrame().

requestAnimationFrame(frame) asks the browser to call frame just before it next paints the screen. You saw timing in Timers and the Event loop. Canvas adds the clear-and-draw-again step.

1let x = 40;2let velocity = 180;3let lastTime = performance.now();4 5function frame(now) {6  const seconds = (now - lastTime) / 1000;7  lastTime = now;8  x = x + velocity * seconds;9  if (x > 260 || x < 40) velocity = -velocity;10  ctx.clearRect(0, 0, 300, 160);11  ctx.beginPath();12  ctx.arc(x, 80, 22, 0, Math.PI * 2);13  ctx.fill();14  requestAnimationFrame(frame);15}

The lab does not start moving on its own. Some people feel unwell when things move on screen, so their computer asks pages to use less motion. A page can check this with the prefers-reduced-motion setting.

The lab checks that setting after the page loads. It gives you a Step button to move one frame at a time. It also cancels its next frame when the lab leaves the page.

Normally, all your page code runs on one track, called the main thread. Clicks, typing, and scrolling are handled there too. A worker is a second track that runs code at the same time.

OffscreenCanvas lets a worker do the drawing. That helps when drawing is heavy enough to slow down clicks, typing, or scrolling. Most new browsers support it, but not all. So you first check that it exists. This check is called feature detection.

1if ("OffscreenCanvas" in window) {2  const offscreen = canvas.transferControlToOffscreen();3  const worker = new Worker(workerUrl);4  worker.postMessage({ canvas: offscreen }, [offscreen]);5} else {6  showMessage("This browser does not support OffscreenCanvas yet.");7}

Line 1 checks that the browser has OffscreenCanvas. Line 2 hands control of the canvas over to an OffscreenCanvas. Line 3 starts a worker. Line 4 sends the canvas to the worker. Line 6 shows a message when the browser has no support.

The demo only starts a worker when you click. It builds the worker's code from a Blob URL, a short-lived address for text made in the page. Reset stops the worker with terminate() and frees the Blob URL.

This cleanup matters, because a worker keeps running until you stop it. Also, once a canvas is handed to a worker, the main page can no longer draw on it.

Canvas is powerful, but it does not replace HTML. People need to click into things, select text, search the page, copy, and use screen readers (tools that read the page out loud). For that, normal page elements, the DOM, usually work best.

SVG sits in between. It draws shapes like canvas, but the browser keeps each shape as an element.

<canvas width="300" height="150" aria-label="Sales by drink">
  <table>
    <caption>Sales by drink</caption>
    <tr><th>Tea</th><td>3</td></tr>
    <tr><th>Bread</th><td>5</td></tr>
  </table>
</canvas>

Line 1 gives the canvas a name with aria-label. Screen readers say that name. Lines 2 to 6 put a real table inside the canvas. People can read the table if the canvas can't be drawn.

For charts, it is best to also show the data in a real table next to the picture. Then the chart is not the only way to read the numbers.

The table compares the three tools. Read each row as one question, and each column as one tool's answer.

Where you'll use this in real projects

A real canvas feature keeps plain JavaScript data next to the pixels. For example:

• A diagram keeps an array of boxes and the lines between them.
• A game keeps each character's position and speed.
• A signature pad keeps the list of pen strokes.

The data is the real record of what is on screen. The canvas only shows a picture of it.

1const sales = [3, 5, 2];2const labels = ["Tea", "Bread", "Rice"];3const ctx = canvas.getContext("2d");4ctx.fillStyle = "royalblue";5sales.forEach((amount, index) => {6  const x = 20 + index * 70;7  const y = 140 - amount * 20;8  ctx.fillRect(x, y, 42, amount * 20);9  ctx.fillStyle = "black";10  ctx.fillText(labels[index], x, 158);11  ctx.fillStyle = "royalblue";12});

Line 1 holds three numbers. Line 5 loops over them. Each time, line 6 picks the bar's left edge, and line 7 picks its top edge. Line 8 paints the bar. Lines 9 and 10 write its name underneath in black.

Why does line 7 subtract? On a canvas, y grows downward: 0 is the top. To make a bar stand on a base line at y = 140, its top must be higher up, which means a smaller y.

1const circles = [2  { x: 40, y: 50, radius: 18, color: "tomato" },3  { x: 120, y: 80, radius: 28, color: "royalblue" },4];5 6function drawScene(ctx) {7  ctx.clearRect(0, 0, 300, 150);8  for (const circle of circles) {9    ctx.fillStyle = circle.color;10    ctx.beginPath();11    ctx.arc(circle.x, circle.y, circle.radius, 0, Math.PI * 2);12    ctx.fill();13  }14}

Line 1 keeps the two circles as plain objects. Line 7 clears the canvas. Line 8 loops over the circles, and line 11 draws each one. To move a circle, change its x in the array and call drawScene() again.

Finding which shape was clicked is called hit testing. It uses the same array. Canvas can't tell you which circle was clicked. You compare the click's position with your saved shapes instead:

• For a rectangle, check that the point is between its left and right edges, and between its top and bottom.
• For a circle, check that the point is no farther from the center than the radius.

Common misconceptions

• "Canvas shapes are page elements." They are only pixels. Keep your own data if you need to move, delete, label, or click on a shape.
• "The CSS size is the canvas size." The width and height attributes set the drawing buffer. CSS only stretches it.
• "lineTo() draws a line right away." Path commands only sketch. stroke() or fill() paints.
• "Pixel filters can read any picture." A picture from another site without permission taints the canvas. Then getImageData() throws a SecurityError.
• "Canvas animation never clears." Most loops clear and draw again every frame. A trail behind a moving thing only appears if you choose to skip the clear.
• "OffscreenCanvas makes everything fast." It can move drawing to a worker. You still pay for sending messages, copying data, a fallback, and cleanup.

Key takeaways

• Canvas drawing calls only change pixels. They don't make page elements you can move later.
• The 2D context holds the drawing commands, your settings, and the current path. save() and restore() put settings aside and bring them back.
• The width and height attributes set the drawing buffer. CSS only stretches it, so sharp screens need a bigger buffer.
• A path is a sketch until fill() or stroke() paints it. Angles are in radians.
• ImageData.data holds four numbers per pixel: red, green, blue, and alpha. You can't read the pixels of a tainted canvas.
• Animations clear and draw again inside requestAnimationFrame(). Check that OffscreenCanvas exists before you use it.

Canvas is pixel drawing with JavaScript: keep your own data about the shapes, and paint each frame from that data.

Up next: Files & Blobs.