Documentation / @ripl/svg

@ripl/svg

The SVG rendering context for Ripl: draws the same elements into a live SVG DOM tree instead of a canvas bitmap.

Features

• One import to switch — replace createContext from @ripl/web with this package's, and the elements, scenes, animations and events are untouched.
• Reconciled DOM updates — each render pass diffs a virtual tree against the real SVG nodes and touches only what changed, rather than rebuilding the subtree.
• Inspectable output — the result is real markup you can style with CSS, inspect in devtools, export, or hand to a print pipeline.
• Native <defs> for paint — linear and radial gradients, pattern tiles, clip paths, shadow filters and text paths become <defs> entries, cached by id and swept when unused. Conic gradients, which SVG has no element for, fall back to a solid colour.
• Full element parity — paths, text, text-on-a-path, images, transforms, clipping and hit testing all behave as they do on Canvas.
• Snapshot export — SVG markup, an image/svg+xml object URL, or rasterized ImageData.

Installation

# npm
npm install @ripl/svg

# yarn
yarn add @ripl/svg

# pnpm
pnpm add @ripl/svg

Install it alongside @ripl/web, which supplies the elements, scene, renderer and browser platform bindings.

Quick start

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

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

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

createCircle({
    fill: '#3a86ff',
    stroke: '#1a56db',
    lineWidth: 2,
    cx: context.width / 3,
    cy: context.height / 2,
    radius: Math.min(context.width, context.height) / 4,
}).render(context);

createRect({
    fill: 'linear-gradient(45deg, #ff006e, #fb5607)',
    x: context.width / 2,
    y: context.height / 4,
    width: context.width / 3,
    height: context.height / 2,
}).render(context);

Key API

Export	What it does
createContext	Binds an SVGContext to a selector or element
SVGContext	The context itself, for typing and subclassing
SVGPath / SVGText / SVGImage	The SVG-backed path, text and image primitives
isSupportedSVGGradient	Whether a parsed gradient has a native SVG element

Related packages

• @ripl/web — the browser entry point supplying elements, scene and renderer
• @ripl/canvas — the same API, rasterizing to a canvas instead
• @ripl/core — the elements and scene graph this context draws
• @ripl/charts — every chart type renders through this context too

Documentation

Guides, live demos and the full API reference are at ripl.run/docs/core/contexts/svg.

License

MIT

Classes

Class	Description
SVGContext	SVG rendering context implementation, mapping the unified API to SVG DOM elements via virtual-DOM reconciliation.
SVGImage	SVG-specific image element wrapping a CanvasImageSource as an SVG <image> tag.
SVGPath	SVG-specific path implementation that builds an SVG d attribute string from drawing commands.
SVGText	SVG-specific text element mapping position and content to SVG <text> attributes.
SVGTextPath	SVG <textPath> element for rendering text along a path defined in <defs>.

Interfaces

Interface	Description
SVGContextElement	An SVG-specific context element carrying its rendering definition.
SVGContextElementDefinition	Definition for an SVG context element, describing its tag, inline styles, and attributes.

Functions

Function	Description
createContext	Creates an SVG rendering context (a concrete Context) attached to the given DOM target.