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.

<div align="center"> <table> <tr> <td align="center"><b>Spline Polyline</b><br><img src="./assets/polyline.png" width="300" alt="Spline Curve"/></td> <td align="center"><b>3D Sphere</b><br><img src="./assets/sphere.png" width="300" alt="Sphere Rendering"/></td> <td align="center"><b>Multi-Line Graph</b><br><img src="./assets/line-chart.png" width="300" alt="Line Chart Analysis"/></td> </tr> <tr></tr> <tr> <td align="center"><b>Bubble Scatter</b><br><img src="./assets/scatter-chart.png" width="300" alt="Scatter Plot"/></td> <td align="center"><b>Candlestick Chart</b><br><img src="./assets/stock-chart.png" width="300" alt="Stock Market Chart"/></td> <td align="center"><b>Jet Engine Model</b><br><img src="./assets/jet-engine.png" width="300" alt="3D Jet Engine"/></td> </tr> </table> </div>

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
• 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)
• 18 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
aw