Ripl

Ripl (pronounced "ripple") is a library that provides a unified API for 2D graphics rendering (Canvas & SVG) in the browser, with a focus on high performance and interactive data visualization. It also includes an experimental 3D rendering package.

Working with the canvas API can be notoriously difficult as it is designed to be very low-level. Alternatively, working with SVG is rather straightforward but not without its flaws. Because these paradigms differ widely in their implementations developers often have to choose one or the other at the outset of a project. Ripl alleviates the issue by exposing a unified API and mimicking the DOM/CSSOM in as many ways as possible to make it simple for developers to interact with. Switching between Canvas and SVG is as simple as changing one line of code.

[!IMPORTANT] Ripl is currently in beta.

Features

• Unified rendering API across Canvas, SVG, and experimental 3D contexts
• Grouping and property inheritance — CSS-like cascading of visual properties through the element tree
• Scene and renderer management — hoisted scenegraph with O(n) rendering and an automatic requestAnimationFrame loop
• DOM-like event system — event bubbling, delegation, stop propagation, and disposable subscriptions
• CSS-like element querying — getElementById, getElementsByType, getElementsByClass, query, queryAll with selector syntax
• Bounding box detection via getBoundingBox on all shape elements
• Context exporting — snapshot any context to an image (ImageData), an object URL, or a string (PNG data URL / SVG markup / terminal text)
• Transforms — translate, scale, rotation, and transform-origin on every element
• Clipping — path-based clipping via Shape2D
• Gradient support — CSS gradient parsing and serialisation (linear, radial, conic)
• Automatic interpolation for numbers, colors (RGB, hex, HSL), dates, gradients, paths, strings, and rotation values
• High performance animation — cancellable Task-based transitions with CSS-like keyframe support and custom interpolators
• 11 scale types — continuous, discrete, band, diverging, logarithmic, power, quantile, quantize, threshold, time (inspired by D3)
• 23 pre-built chart types via @ripl/charts
• Built-in shape primitives — arc, circle, rect, line, polyline, polygon, ellipse, text, path, image
• 3D primitives (experimental) — cube, sphere, cylinder, cone, plane, torus
• Easing library — linear, quad, cubic, quart, quint (in/out/inOut variants)
• Color utilities — parsing, serialisation, and color scales
• Math & geometry — degree/radian conversion, point operations, border radius normalisation, polygon extrapolation
• Renderer debug overlay — FPS counter, element count, bounding box visualisation
• Completely modular and tree-shakable — only ship the features you use
• Strictly typed in TypeScript
• Zero runtime dependencies

Packages

Package	Description
@ripl/web	Main entry point for browser usage — re-exports core + canvas context with browser platform bindings
@ripl/core	Core rendering — elements, scene, renderer, animation, scales, math, color, interpolation, gradients, tasks
@ripl/canvas	Canvas 2D rendering context
@ripl/svg	SVG rendering context
@ripl/charts	Pre-built chart components with axes, legends, tooltips, crosshairs, and grids
@ripl/3d	3D rendering context with camera, shading, and primitive shapes (experimental)
@ripl/webgpu	WebGPU-accelerated 3D rendering context with hardware depth testing and WGSL shaders
@ripl/terminal	Terminal rendering context — braille-character output with ANSI truecolor
@ripl/node	Node.js runtime bindings — configures the platform factory for headless environments
@ripl/dom	DOM utilities used internally by browser contexts
@ripl/utilities	Shared typed utility functions — type guards, collection helpers, DOM helpers

The project is structured as a Yarn 4 monorepo:

packages/
├── core/         # Core rendering library
├── canvas/       # Canvas 2D rendering context
├── svg/          # SVG context implementation
├── charts/       # Pre-built chart components
├── 3d/           # 3D rendering (experimental)
├── webgpu/       # WebGPU 3D rendering context
├── terminal/     # Terminal rendering context
├── node/         # Node.js runtime bindings
├── web/          # Main browser entry point
├── dom/          # DOM utilities
├── utilities/    # Shared typed utility functions
└── test-utils/   # Test utilities
app/              # Documentation site (VitePress) with live demos

Usage

The following is a tour of Ripl's features starting from the most basic and progressively building towards more advanced concepts.

Render a Basic Element

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

// Create a canvas context bound to a DOM element
const context = createContext('.mount-element');

// Create an element
const circle = createCircle({
    fill: 'rgb(30, 105, 120)',
    lineWidth: 4,
    cx: context.width / 2,
    cy: context.height / 2,
    radius: context.width / 3,
});

// Render the element to the context
circle.render(context);

Built-in 2D shape primitives: arc, circle, rect, line, polyline, polygon, ellipse, text, path, image.

Modify Element Properties

To modify an element simply change any of its properties and re-render it.

circle.fill = '#FF0000';
circle.cx = context.width / 3;
circle.cy = context.height / 3;
circle.render(context);

Switch Contexts (Canvas / SVG)

To render the same element to SVG, replace the createContext import from @ripl/web with @ripl/svg:

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

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

const context = createContext('.mount-element');
const circle = createCircle({ /* same options */ });
circle.render(context);

Grouping and Inheritance

Render multiple elements in groups with inherited properties (like CSS) and event bubbling (like the DOM):

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

const context = createContext('.mount-element');

const circle = createCircle({
    cx: context.width / 2,
    cy: context.height / 2,
    radius: context.width / 3,
});

const rect = createRect({
    x: context.width / 2,
    y: context.height / 2,
    width: context.width / 5,
    height: context.height / 5,
});

// Both children inherit fill and lineWidth from the group
const group = createGroup({
    fill: 'rgb(30, 105, 120)',
    lineWidth: 4,
    children: [circle, rect],
});

group.render(context);

Querying Elements

Elements can be queried using common DOM methods or CSS-like selectors:

const circles = parentGroup.getElementsByType('circle');
const shapes = parentGroup.queryAll('.shape');
const first = parentGroup.query('#child-group > .shape');

Supported selector features:

circle                                   /* type */
#element-id                              /* id */
.element-class                           /* class */
circle[radius="5"]                       /* attribute */
.group-class circle                      /* descendant */
.group-class > circle                    /* direct child */
.group-class rect + circle.circle-class  /* adjacent sibling */

Scene and Renderer

A Scene is the top-level group bound to a rendering context. A Renderer drives the animation loop via requestAnimationFrame.

import {
    createCircle,
    createGroup,
    createRect,
    createRenderer,
    createScene,
} from '@ripl/web';

const circle = createCircle({
    fill: 'rgb(30, 105, 120)',
    cx: 100,
    cy: 100,
    radius: 40,
});

const rect = createRect({
    fill: 'rgb(30, 105, 120)',
    x: 200,
    y: 80,
    width: 60,
    height: 60,
});

// Scene takes a target (selector, element, or context) and options
const scene = createScene('.mount-element', {
    children: [circle, rect],
});

const renderer = createRenderer(scene, {
    autoStart: true,
    autoStop: true,
});

// Listen for events
circle.on('click', event => console.log(event));

Animation

The renderer provides transition-based animation. Transitions are cancellable Task instances (extending Promise with AbortController integration).

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

// Animate a single element
await renderer.transition(circle, {
    duration: 1000,
    ease: easeOutCubic,
    state: {
        fill: '#FF0000',
        cx: 200,
        cy: 200,
        radius: 60,
    },
});

// Animate multiple elements (or a whole group/scene)
await renderer.transition([circle, rect], {
    duration: 1000,
    ease: easeOutCubic,
    state: {
        fill: '#FF0000',
    },
});

Keyframes

// Implicit keyframe offsets
await renderer.transition(circle, {
    duration: 1000,
    ease: easeOutCubic,
    state: {
        fill: [
            '#FF0000', // offset ~0.33
            '#00FF00', // offset ~0.66
            '#0000FF', // offset 1
        ],
    },
});

// Explicit keyframe offsets
await renderer.transition(circle, {
    duration: 1000,
    ease: easeOutCubic,
    state: {
        fill: [
            { value: '#FF0000',
                offset: 0.25 },
            { value: '#0000FF',
                offset: 0.8 },
        ],
    },
});

// Custom interpolator function
await renderer.transition(circle, {
    duration: 1000,
    ease: easeOutCubic,
    state: {
        radius: t => t * 100, // 0 <= t <= 1
    },
});

Transforms

Every element supports CSS-like transforms:

const rect = createRect({
    x: 100,
    y: 100,
    width: 80,
    height: 80,
    rotation: '45deg', // or radians as a number
    transformOriginX: '50%', // or pixels as a number
    transformOriginY: '50%',
    translateX: 20,
    translateY: 10,
    transformScaleX: 1.5,
    transformScaleY: 1.5,
});

Transforms can also be animated via renderer.transition.

Exporting

Every context can capture a snapshot of what it has rendered and export it to an image, URL, or string via export():

const snapshot = context.export();

const str = snapshot.toString(); // PNG data URL (SVG → markup, Terminal → braille text)
const url = snapshot.toURL(); // openable Blob object URL
const image = await snapshot.toImage(); // low-level ImageData (environment-agnostic)

The exact outputs depend on the context: Canvas, 3D, and WebGPU export raster images; SVG exports vector markup (and can rasterize to an image); Terminal exports braille text (and a rasterized image). Charts forward export() to their underlying context: