Canvas Context

The Canvas context is the default rendering backend in Ripl. It renders elements to an HTML <canvas> element using the Canvas 2D API, handling DPR (device pixel ratio) scaling automatically so your content looks crisp on Retina displays. It also parses CSS gradient strings directly in fill and stroke properties, converting them to native CanvasGradient objects behind the scenes.

Demo

Usage

The canvas context is created by importing createContext from @ripl/core:

import {
    createContext,
} from '@ripl/web';

const context = createContext('.my-container');

You can also pass an HTMLElement directly:

const container = document.getElementById('my-container');
const context = createContext(container);

DPR Scaling

The canvas context automatically scales the canvas to match the device pixel ratio (DPR). This ensures crisp rendering on high-DPI displays (e.g. Retina screens). The scaling is transparent — you work in CSS pixel coordinates and Ripl handles the rest.

// These coordinates are in CSS pixels, not physical pixels
const circle = createCircle({
    cx: context.width / 2, // CSS pixel width
    cy: context.height / 2, // CSS pixel height
    radius: 50,
});

Gradient Support

The canvas context supports CSS gradient strings directly in fill and stroke. Ripl parses the CSS gradient syntax and converts it to native CanvasGradient objects:

const rect = createRect({
    x: 0,
    y: 0,
    width: 200,
    height: 100,
    fill: 'linear-gradient(90deg, #3a86ff, #ff006e)',
});

See Gradients for the full gradient syntax reference.

Canvas-Specific Methods

The canvas context provides all the standard Context methods, plus canvas-specific behaviors like rotate, scale, translate, setTransform, measureText, applyClip, and path-based hit testing (isPointInPath, isPointInStroke).

NOTE

For the full API, see the Canvas Context API Reference.

When to Use Canvas

Canvas is the best choice when:

• Performance is critical — Canvas is generally faster for rendering many elements per frame
• Pixel-level operations — Canvas supports getImageData/putImageData for pixel manipulation
• Complex animations — Canvas clears and redraws efficiently each frame

Canvas is less ideal when:

• You need DOM accessibility for rendered elements
• You need to inspect or style individual elements via browser DevTools
• You need CSS animations on individual rendered elements