canvas

The canvas element provides a drawing surface for rendering graphics, charts, games, and dynamic visual content via JavaScript.

Description

The <canvas> element is a container for scriptable graphics. It provides a bitmap drawing surface that you can manipulate with JavaScript using either the 2D rendering context or WebGL for 3D graphics.

Vanilla Breeze styles canvas elements to be block-level and responsive by default, with variants for borders, loading states, and interactive cursors.

When to Use

  • Charts and graphs - Data visualization (often via libraries like Chart.js)
  • Games - 2D and 3D game rendering
  • Image manipulation - Filters, cropping, compositing
  • Animations - Complex animations beyond CSS capabilities
  • Drawing applications - User-interactive drawing tools
  • Signatures - Capture user signatures

When to Use Other Elements

  • Use <svg> for scalable, accessible vector graphics
  • Use <img> for static images
  • Use CSS animations for simple, declarative animations
  • Use <video> for pre-recorded animated content

Variants

Default

Basic canvas without styling.

<canvas width="300" height="150"></canvas>

.bordered

Adds a subtle border to define the canvas boundary.

<canvas class="bordered" width="300" height="150"></canvas>

.loading

Striped pattern indicates loading or placeholder state before content is rendered.

<canvas class="bordered loading" width="300" height="150"></canvas>

.interactive

Crosshair cursor for interactive canvases where users can click or draw.

<canvas class="interactive" width="300" height="150"></canvas>

.drawing

Crosshair cursor with touch-action: none for drawing applications that handle touch events manually.

Click and drag to draw

<canvas class="drawing" width="300" height="150"></canvas>

.full

Full container width.

.fixed

Full width with fixed height (400px).

Responsive Canvas

Use the .canvas-responsive wrapper to maintain aspect ratio while filling available width.

<div class="canvas-responsive"> <canvas></canvas> </div>

The wrapper maintains a 16:9 aspect ratio by default. The canvas is positioned absolutely to fill the container.

Custom Aspect Ratios

<!-- Square canvas --> <div class="canvas-responsive" style="aspect-ratio: 1;"> <canvas></canvas> </div> <!-- 4:3 canvas --> <div class="canvas-responsive" style="aspect-ratio: 4 / 3;"> <canvas></canvas> </div>

Canvas Sizing

Canvas has two size concepts: the element size (CSS) and the drawing buffer size (attributes).

<!-- Drawing buffer is 600x400 pixels --> <!-- Display size is 300x200 CSS pixels (for retina) --> <canvas width="600" height="400" style="inline-size: 300px; block-size: 200px;"> </canvas>

High DPI / Retina Support

// Scale canvas for retina displays const canvas = document.querySelector('canvas'); const ctx = canvas.getContext('2d'); const dpr = window.devicePixelRatio || 1; // Set display size canvas.style.width = '300px'; canvas.style.height = '200px'; // Set actual size in memory (scaled for DPI) canvas.width = 300 * dpr; canvas.height = 200 * dpr; // Scale context to match ctx.scale(dpr, dpr);

Live Examples

Basic Drawing

const canvas = document.getElementById('example-basic'); const ctx = canvas.getContext('2d'); // Fill rectangle ctx.fillStyle = '#4a90d9'; ctx.fillRect(20, 20, 150, 100); // Stroke rectangle ctx.strokeStyle = '#333'; ctx.lineWidth = 2; ctx.strokeRect(200, 20, 150, 100); // Draw text ctx.fillStyle = '#333'; ctx.font = '16px system-ui'; ctx.fillText('Canvas Demo', 20, 160);

Chart Placeholder

Monthly sales data - Q4 2025

Accessibility

Canvas content is not accessible to screen readers by default. You must provide alternatives.

Fallback Content

Place fallback content inside the canvas element for browsers that don't support canvas or for screen readers.

<canvas width="400" height="300"> <!-- Fallback for screen readers and non-canvas browsers --> <p>Bar chart showing quarterly sales:</p> <ul> <li>Q1: $45,000</li> <li>Q2: $52,000</li> <li>Q3: $48,000</li> <li>Q4: $61,000</li> </ul> </canvas>

ARIA Labels

<canvas role="img" aria-label="Line chart showing website traffic increasing 25% over six months" width="400" height="300"> </canvas>

Data Tables

For complex data visualizations, provide an accessible data table nearby.

<figure> <canvas id="sales-chart" width="600" height="400"></canvas> <figcaption> Annual sales by region. <a href="#sales-table">View data table</a> </figcaption> </figure> <table id="sales-table"> <!-- Accessible data table with same information --> </table>

Best Practices

  • Always provide text alternatives for informative canvas content
  • Use role="img" and aria-label for simple graphics
  • Provide data tables for charts and graphs
  • Ensure interactive canvases are keyboard accessible
  • Respect prefers-reduced-motion for animated content

Related Elements

  • <svg> - Scalable vector graphics, often better for accessibility
  • <img> - Static images
  • <figure> - Wrap canvas with captions

CSS Reference

Styles defined in /src/native-elements/canvas/styles.css

Selector Properties
canvas display: block; max-inline-size: 100%;
canvas.full inline-size: 100%; block-size: auto;
canvas.fixed inline-size: 100%; block-size: 400px;
canvas.interactive cursor: crosshair;
canvas.drawing cursor: crosshair; touch-action: none;
canvas.bordered border; border-radius;
canvas.loading background with diagonal stripes;
.canvas-responsive position: relative; aspect-ratio: 16 / 9;