Paper.js — The Swiss Army Knife of Vector Graphics Scripting

Introduction

Paper.js is a vector graphics scripting framework built on the HTML5 Canvas. It provides a comprehensive, well-designed API for creating and manipulating vector graphics, with particular strength in path operations like boolean combinations, simplification, and smoothing.

What Paper.js Does

• Creates and manipulates vector paths, shapes, compound paths, and raster images
• Performs boolean operations (unite, intersect, subtract, exclude) on paths
• Simplifies and smooths complex paths algorithmically
• Handles mouse and keyboard events with hit-testing against the scene graph
• Exports to SVG and imports SVG content as editable Paper.js items

Architecture Overview

Paper.js implements a full scene graph with a Project containing Layers, Groups, and Items. Each Item carries transformation matrices, styles, and child relationships. The rendering pipeline traverses the scene graph each frame, applying transformations hierarchically. A dedicated path geometry engine handles cubic bezier math, curve-fitting, and boolean clipping operations using a Greiner-Hormann variant.

Self-Hosting & Configuration

• Install via npm or include the paper-full.js script from CDN
• Initialize with paper.setup(canvas) to bind to an HTML5 canvas element
• Use PaperScript (optional) for operator overloading on points and sizes
• Configure view settings for frame rate, auto-update, and pixel ratio
• Runs in Node.js with node-canvas for headless SVG or raster export

Key Features

• Path boolean operations for constructive geometry (union, difference, intersection)
• Curve and path simplification reduces point counts while preserving shape
• Symbols and symbol instances for efficient repeated pattern rendering
• Raster items with pixel manipulation for image processing within the scene graph
• Comprehensive event model with onFrame, onMouseDown, onMouseDrag handlers

Comparison with Similar Tools

• Fabric.js — focused on interactive object manipulation; less path math and booleans
• Rough.js — sketch aesthetic only; no path operations or scene graph
• Snap.svg — SVG manipulation library; Paper.js renders to Canvas with SVG import/export
• Two.js — minimal 2D API across renderers; Paper.js has richer geometry tools
• p5.js — creative coding focused on immediate mode; Paper.js offers retained scene graph

FAQ

Q: Can Paper.js export to SVG? A: Yes. Call project.exportSVG() to get a full SVG representation of the current scene.

Q: Does it work with React? A: Yes. Instantiate Paper.js on a canvas ref in useEffect and manage scope lifecycle manually.

Q: What is PaperScript? A: A thin scripting extension that enables operator overloading (e.g., point1 + point2) for cleaner math syntax. Plain JavaScript works without it.

Q: How does performance scale? A: Paper.js handles thousands of path items efficiently. For tens of thousands of simple shapes, consider switching to a WebGL renderer.

Sources

• https://github.com/paperjs/paper.js
• http://paperjs.org/reference/