<script src="https://unpkg.com/pencil.js"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/pencil.js"></script>

<script>
    const scene = new Pencil.Scene();
</script>

Usage

Once you have installed the library using NPM, you can start to import it.

You can either import everything under a namespace or only the package you're going to use. Pick the way that fit your style.

// Just the part you need (recommended)
import { Scene } from "pencil.js";

const scene = new Scene();

/***/

// A single module
import Scene from "pencil.js/scene";

/***/

// The whole package under a namespace
import Pencil from "pencil.js";

const scene = new Pencil.Scene();

Pencil.js is fully tree-shakable, any modern bundler (Vite, webpack …) will only keep what you use. TypeScript declarations are included.

Documentation

The official documentation , built from the docs folder.

What Pencil.js do best

Abstraction

Drawing in a canvas is not trivial. First of all, the goal is to ease the use of canvas in a browser; allowing anyone to use it with its comprehensible syntax and extensible options.

OOP

OOP is great, OOP is almighty, OOP saves lives ! Others library exists, but none with a beautiful OOP syntax. It makes code look natural, and with TypeScript, your editor knows every option.

Modularity

Splitting the whole code into modules make everything cleaner. It also allows you to grab only what you need or replace what you don't like.

Documentation

A complete documentation goes a long way to help developers. All functions are assured to have a description and typed arguments and returns, the API reference is generated from the source.

Performance

Pencil.js is able to draw thousands of shapes pretty smoothly without tanking your memory. Even more if you use the Particles generator.

Size

With , Pencil.js is fairly lightweight. Furthermore, it's fully tree-shakable: a scene with a circle weighs about 7 kB gzipped.

Examples

import { Scene, Rectangle } from "pencil.js";

const scene = new Scene(); // create a new scene

const position = [100, 200];
const width = 80;
const height = 50;
const options = {
    fill: "red",
};
const rectangle = new Rectangle(position, width, height, options); // Create a new red rectangle
scene.add(rectangle); // Add the rectangle to the scene

scene.render(); // Render the scene once

Take a look at more advanced examples.

Modules

Every class lives in its own module, importable on its own (import Circle from "pencil.js/circle").

• EventEmitter
  • Container
    • OffScreenCanvas
      • Scene
    • Component
      • .draggable()
      • .rotatable()
      • Particles
      • Path
      • Heart
      • Line
        • Spline
      • Polygon
        • RegularPolygon
          • Star
          • Triangle
      • Rectangle
        • .resizable()
        • Square
        • Image
          • Sprite
        • Text
      • Arc
        • Pie
        • Ellipse
          • Circle
      • Widget
        • ProgressBar
        • ProgressPie
        • Input
          • Button
          • Checkbox
          • Knob
          • Select
          • Slider
• Position
• Vector
• Math
• Navigation
• Color
• LinearGradient
• RadialGradient
• ConicGradient
• Pattern
• BaseEvent
  • MouseEvent
  • KeyboardEvent
  • NetworkEvent

Non-core modules

Non-core modules refer to packages made by us and not part of Pencil.js library. We find them useful, so maybe you will too...

• spritesheet (CLI) Pack a set of images into a single spritesheet along its json description file.
• vue-pencil.js Build reactive 2D graphics scene in your Vue project.
• gif Turn any Pencil.js scene into an animated GIF.
• text-direction Gives the rendering text direction (left to right or right to left) of a node.
• canvas-gif-encoder Create a GIF stream frame by frame from a canvas rendering context.

Who is using Pencil.js ?

Take a tour of all the awesome project using Pencil.js.

Enterprises

We are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

Contributions

You want to help us improve ? Great, here's how to get started:

npm install
npm run dev        # Playground with hot reload (playground/playground.ts)
npm test           # Unit and visual tests (Vitest with a real canvas renderer)
npm run test:visual:update  # Regenerate visual references (check test/visual/references before committing)
npm run lint       # ESLint
npm run typecheck  # TypeScript
npm run build      # Build modules, CDN bundles and type declarations
npm run size       # Bundles and tree-shaking report
npm run docs:dev   # Documentation website (VitePress + TypeDoc)
npm run bench      # Compare performances with published versions
npm run bench:headless -- 16000  # Measure rendering time in a headless Chromium

Contributors

All contributions are valued, you can add yourself to this list (or request to be) whatever your contribution is.

License

MIT