!Teaser

p5.brush.js

p5.brush.js adds natural drawing tools to p5.js — pencils, charcoal, markers, watercolor fills, hatch patterns, and vector fields that bend strokes organically. It's built for generative art and high-resolution printing.

Visit the library website here! (more examples soon)

🖌️ Try the interactive Brush Maker →

Design custom brushes with live preview and generate ready-to-paste brush.add() code.

🌊 Try the interactive Flow Field Generator →

Design custom vector fields with live preview and generate ready-to-paste brush.addField() code.

▶️ Check the teaser live →

Live on the p5.js Web Editor, where you can read and edit code.

Two builds

p5.brush ships in two flavors:

| | p5 build | Standalone build | |---|---|---| | File | dist/p5.brush.js | dist/brush.js | | Requires | p5.js 2.x + WEBGL canvas | Nothing — WebGL2 browser only | | Canvas setup | createCanvas(w, h, WEBGL) | brush.createCanvas(w, h) | | Transforms | p5's push/pop, translate, rotate, scale | brush.push/pop, brush.translate, etc. | | Angle mode | Follows p5's angleMode() | brush.angleMode(brush.DEGREES \| brush.RADIANS) | | Seeding | randomSeed() / noiseSeed() | brush.seed() / brush.noiseSeed() | | Frame flush | Automatic | brush.render() at end of each frame | | Clear | p5's background() | brush.clear(color?) |

This README covers the p5 build. For the standalone build see docs/standalone.md.

Table of Contents

• Installation
• Quick Start
• Core Concepts in 1 Minute
• Features
• Reference
• Examples
• Contributing
• License
• Acknowledgements

Installation

Important note: p5.brush requires p5.js 2.x or higher.

Local Installation

To set up your project, add p5.min.js and p5.brush.js to your HTML file. You can download the latest version of the p5.brush.js library in the dist folder. Place the script tags in the following order:

<script src="path_to/p5.min.js"></script>
<script src="path_to/p5.brush.js"></script>

Use a hosted version of the p5.brush.js library

Alternatively, you can link to a p5.brush.js file hosted online. All versions are stored in a CDN (Content Delivery Network). You can find a history of these versions in the p5.js CDN. In this case you can change the link to:

<!-- Online version of p5.brush -->
<script src="https://cdn.jsdelivr.net/npm/p5.brush@latest"></script>

Install with NPM and other modular-based apps

Install the npm package. p5.brush requires p5.js as a peer dependency for the p5 build.

npm install p5.brush --save

The package exposes two subpaths — pick the one that matches your build:

// p5 build (default) — requires p5.js 2.x
import * as brush from 'p5.brush'
// Standalone build — no p5.js required
import * as brush from 'p5.brush/standalone'

If you are using p5 and p5.brush as modules, you will need to use instance mode. Read below.

Note for p5 instance mode

In instance mode, p5 functions are scoped to a variable instead of the global namespace — useful when mixing with other libraries or using p5 as an ES module.

Call brush.instance(p) inside your sketch function before setup and draw. After that, all brush.* calls work normally without any p. prefix.

const sketch = (p) => {
  // Tell p5.brush which p5 instance to use
  brush.instance(p);
p.setup = () => {
    // Canvas must be in WEBGL mode — brush initializes automatically
    p.createCanvas(700, 410, p.WEBGL);
  };
p.draw = () => {
    p.background(240);
    brush.set("HB", "#333", 1);
    brush.line(100, 100, 400, 300);
  };
};
new p5(sketch);

Quick Start

If you already know the basics of p5, this is the shortest path to drawing with p5.brush:

1. Create a WEBGL canvas.
2. Pick a brush with brush.set(name, color, weight).
3. Draw with a primitive like brush.line(), brush.rect(), or brush.circle().

function setup() {
  createCanvas(700, 410, WEBGL);
  background("#f6f1e8");
  brush.scaleBrushes(3);
brush.set("HB", "#2f2a26", 1.4);
  brush.line(-220, -80, 180, 40);
brush.fill("#d7c3a3", 120);
  brush.noStroke();
  brush.circle(120, 20, 70);
brush.set("rotring", "#1f4b99", 0.8);
  brush.noFill();
  brush.hatch(7, 35);
  brush.rect(-140, 40, 120, 90, "center");
}

If you are new to the library, a good first sequence is:

• brush.scaleBrushes(...) if you are using built-in brushes
• brush.set(...) to choose the stroke brush
• brush.fill(...) or brush.hatch(...) if you want interior texture
• brush.line(), brush.rect(), brush.circle(), or brush.polygon() to draw

Core Concepts in 1 Minute

• p5.brush follows p5's drawing model: first you set drawing state, then you draw shapes.
• brush.set(), brush.stroke(), brush.strokeWeight(), brush.fill(), brush.hatch(), and related functions configure how upcoming shapes should look.
• brush.line(), brush.rect(), brush.circle(), brush.arc(), brush.beginShape(), and brush.polygon() actually draw geometry.
• brush.noStroke(), brush.noFill(), brush.noHatch(), and brush.noWash() turn parts of that state back off.
• Vector fields are optional. If you never call brush.field(...), your shapes still draw normally.
• Most sketches only need a small subset of the API: choose a brush, maybe add fill or hatch, then draw primitives.

• Style: choose how marks look with brush.set(), brush.fill(), brush.hatch(), and related state functions
• Geometry: draw lines and shapes with brush.line(), brush.rect(), brush.circle(), brush.beginShape(), and more
• Advanced control: add vector fields, custom brushes, clipping, buffers, and classes when you need them

Features

p5.brush.js enhances the p5.js framework with a set of tools that allow for sophisticated drawing and rendering techniques.

• Custom Configuration: Customize your drawing strokes with the ability to select different buffers and leverage a custom random number generator to introduce variability in procedural designs.
• Vector Field Integration: Direct the motion of your brush strokes with vector fields, crafting fluid, dynamic visuals within your sketches.
• Dynamic Brush System: Select from an array of brushes, each offering distinct characteristics, to create a variety of effects and textures.
• Brush and Field Management: Manage and switch between brushes and vector fields with ease, adapting to the needs of your project seamlessly.
• Extensibility: Expand the library's capabilities by integrating your own custom brushes and vector fields, tailoring the toolset to your artistic vision.
• Custom Brush Tips: Load and use your own custom brush tip assets.
• Interactive Brush Tips: Utilize pressure-sensitive brush tips for interactive drawing, adding a level of responsiveness to your canvas work.
• Hatch Patterns: Implement hatching techniques with precision control over the patterns' density and orientation, enhancing your artwork with automated detailing.
• Intuitive Spline and Curve Generation: Generate smooth and accurate curves and splines effortlessly, simplifying the process of intricate path creation.
• Watercolor Fill System: Achieve the subtle nuances of watercolor with a digital fill system designed to blend and diffuse colors in a naturally fluid way.

Reference

p5.brush.js provides a comprehensive API for creating complex drawings and effects. Below are the categorized functions and classes available in the library.

Table of Functions

| Section | Functions | Section | Functions | |---|---|---|---| | Configuration | brush.load(), brush.scaleBrushes(), brush.instance() | Fill Operations | brush.fill(), brush.noFill(), brush.wash(), brush.noWash(), brush.fillBleed(), brush.fillTexture() | | Vector Fields | brush.field(), brush.noField(), brush.refreshField(), brush.listFields(), brush.addField(), brush.wiggle() | Hatch Operations | brush.hatch(), brush.noHatch(), brush.hatchStyle(), brush.mass(), brush.noMass() | | Brush Management | brush.box(), brush.add(), brush.clip(), brush.noClip() | Primitives | brush.line(), brush.flowLine(), brush.beginStroke(), brush.move(), brush.endStroke(), brush.spline(), brush.rect(), brush.circle(), brush.arc(), brush.beginShape(), brush.vertex(), brush.endShape(), brush.polygon() | | Stroke Operations | brush.set(), brush.pick(), brush.stroke(), brush.noStroke(), brush.strokeWeight() | Exposed Classes | brush.Polygon(), brush.Plot(), brush.Position() | | | | Utility Functions | upgrade notes, angle behavior |

_{back to table}

Configuration

This section covers functions for initializing the drawing system and configuring how the library behaves in your sketch. In particular, brush.scaleBrushes() is usually important when you use the built-in brushes.

Seeding: p5.brush automatically hooks into p5's randomSeed() and noiseSeed(). Calling either of those functions seeds both p5 and the library simultaneously — no separate brush.seed() call is needed.

• brush.load(buffer)

function setup() {
      createCanvas(400, 400, WEBGL);
      brush.load();
      brush.set("HB", "black", 1);
      brush.rect(40, 40, 150, 100);
// Switch to a buffer
      let buffer = createGraphics(200, 300, WEBGL);
      brush.load(buffer);
      brush.set("HB", "black", 1);
      brush.rect(40, 40, 150, 100);
      image(buffer, 20, 40);
// Switch back to main canvas
      brush.load();
    }

function setup() {
      createCanvas(400, 400, WEBGL);
      brush.load();

const layer = createFramebuffer({ width: 200, height: 200 });
layer.draw(() => {
        brush.load(layer);
        brush.set("HB", "black", 1);
        brush.circle(100, 100, 80);
      });
brush.load();
      image(layer, 20, 20);
    }

- Typical workflows:

// p5.Graphics
    const pg = createGraphics(300, 200, WEBGL);
    pg.background(250);
    brush.load(pg);
    brush.set("HB", "black", 1);
    brush.circle(150, 100, 70);
    brush.load();
    image(pg, 20, 20);

// p5.Framebuffer
    const fb = createFramebuffer({ width: 300, height: 200 });
    fb.draw(() => {
      background(250);
      brush.load(fb);
      brush.set("HB", "black", 1);
      brush.circle(150, 100, 70);
    });
    brush.load();
    image(fb, 20, 240);

• brush.scaleBrushes(scale)

// Usually needed when working with built-in brushes
    brush.scaleBrushes(3);

• brush.instance(p)

const sketch = (p) => {
        // Must be called before setup/draw
        brush.instance(p);
p.setup = () => {
          // Canvas must be WEBGL
          p.createCanvas(700, 410, p.WEBGL);
          brush.load();
        };
p.draw = () => {
          p.background(240);
          brush.set("HB", "#333", 1);
          brush.line(100, 100, 400, 300);
        };
      };
new p5(sketch);

_{back to table}

Vector Fields

Vector fields let you bend and redirect strokes so they follow a flow across the canvas. If you do not use them, p5.brush still works like a normal drawing library.

#### Basic vector-field functions

• brush.field(name)

// To activate the "waves" vector field
    brush.field("waves");
// To activate a custom vector field named "myCustomField"
    brush.field("myCustomField");

• brush.noField()

brush.noField();

• brush.wiggle(wiggle)

brush.wiggle(3);

• brush.refreshField(time)

// In the draw loop, refresh the vector field based on the frame count
    function draw() {
      brush.refreshField(frameCount / 10);
      // Additional drawing code
    }

• brush.listFields()

let fieldNames = brush.listFields();
    for (let name of fieldNames) {
      console.log(name);
    }

• brush.addField(name, generatorFunction, options)

brush.addField("diagonal", function(t, field) {
        for (let col = 0; col < field.length; col++) {
            for (let row = 0; row < field[0].length; row++) {
                field[col][row] = 45 + t * 10; // 45° angle, changes with time
            }
        }
        return field; // always return field at the end!
    });
brush.field("diagonal"); // activate it

_{back to table}

Brush Management

This section covers choosing brushes, adding your own brushes, and clipping where strokes are allowed to appear.

• brush.box()

// Retrieve a list of all available brush names
    let brushes = brush.box();
    console.log(brushes); // Logs the array of brush names

• brush.add(name, params) — Design your brush visually with the Brush Maker ↗

// Image brush — use a photo as the brush tip.
    // IMPORTANT: use "await" so the image loads before drawing,
    // and make sure your setup() function is declared "async"!
    async function setup() {
        createCanvas(800, 800, WEBGL);
        brush.load();
await brush.add("watercolor", {
            type: "image",
            weight: 10,
            scatter: 2,
            opacity: 30,
            spacing: 1.5,
            pressure: [1, 0.5],   // starts thick, ends thin
            image: { src: "./brush_tips/brush.jpg" },
            rotate: "random",
            markerTip: false,
        });
// Now you can draw with it!
        brush.set("watercolor", "blue", 1);
        brush.line(100, 100, 400, 100);
    }
// Advanced: explicitly use the built-in Gaussian pressure mode
    brush.add("soft-pencil", {
        type: "default",
        weight: 0.3,
        scatter: 0.6,
        sharpness: 0.3,
        grain: 10,
        opacity: 170,
        spacing: 0.1,
        pressure: {
            mode: "gaussian",
            curve: [0.15, 0.2],
            min_max: [1.1, 0.9],
        },
        rotate: "none",
    });

Custom tip brushes: The tip function receives _m, a p5.Graphics buffer. You draw inside it using normal p5 commands. The coordinate space is 100×100 units with the origin at the centre, so shapes are drawn around (0, 0) and edges fall around ±50 units. The library converts the result to a mask: dark fills become opaque, light or white becomes transparent — so you define the shape in dark tones, and the color from brush.set() or brush.stroke() is applied at render time. Any p5 drawing command works: rect, circle, ellipse, line, triangle, beginShape/vertex/endShape, push/pop, translate, rotate, scale, and so on.

brush.add("diamond", {
        type: "custom",
        weight: 5,
        scatter: 0.08,
        opacity: 23,
        spacing: 0.6,
        pressure: [0.5, 1.5, 0.5],   // thin → thick → thin
        tip: (_m) => {
            _m.rotate(45);            // degrees, follows p5 angleMode
            _m.rect(-1.5, -1.5, 3, 3);
        },
        rotate: "natural",
        markerTip: false,
    });

• brush.clip(clippingRegion)

// Set a clipping region
    brush.clip([10, 10, 250, 200]);
    // Draw a line - it will be clipped according to the region
    brush.line(100, 90, 300, 40);
// Remove the clipping region
    brush.noClip();
    // Draw another line - it will not be clipped
    brush.line(0, 0, 200, 300);

• brush.noClip()

// Disable the clipping region
    brush.noClip();

_{back to table}

Stroke Operations

These functions control stroke appearance: which brush is active, what color it uses, and how thick it should be.

• brush.set(brushName, color, weight)

// Set the "HB" brush with a specific blue color and weight factor 1
    brush.set("HB", "#002185", 1);

- brush.pick(brushName) - Description: Selects the current brush type based on the specified name. This function is used to change the brush type without altering its color or weight. - Parameters: - brushName (String): The name of the brush to set as current. - Usage:

// Set the current brush to "charcoal"
    brush.pick("charcoal");

• brush.stroke(r, g, b) or brush.stroke(color)

// Set the brush color using RGB values
    brush.stroke(105, 111, 34);
    // Or set the brush color using a HEX string
    brush.stroke("#002185");

• brush.noStroke()

// Disable stroke for the upcoming shapes
    brush.noStroke();

• brush.strokeWeight(weight)

// Set the brush stroke weight to 2.3 times the base size
    brush.strokeWeight(2.3);

_{back to table}

Fill Operations

These functions control how closed shapes are filled. You can use watercolor-style fills, flat wash fills, and adjust bleed or texture.

• brush.fill(a, b, c, d) or brush.fill(color, opacity)

// Set the fill color using RGB values and opacity
    brush.fill(244, 15, 24, 75);
    // Or set the fill color using a HEX string and opacity
    brush.fill("#002185", 110);

• brush.noFill()

// Disable fill for the upcoming shapes
    brush.noFill();

• brush.wash(color, opacity)

brush.wash("#f7e4a0", 255);
    brush.circle(width / 2, height / 2, 180);
    brush.noWash();

• brush.noWash()

brush.noWash();

• brush.fillBleed(strength, direction, angle)

brush.fillBleed(0.3, "out", 0); // left to right

• brush.fillTexture(textureStrength, borderIntensity, scatter?)

// Set the fill texture and border intensity
    brush.fillTexture(0.6, 0.4);
// Disable scatter layers for a cleaner gradient
    brush.fillTexture(0.6, 0.4, false);

_{back to table}

Hatch Operations

These functions control hatching and massing inside shapes, using repeated lines or layered marks to build tone and texture.

• brush.hatch(dist, angle, options)

// Set hatching with specific distance, angle, and options
    brush.hatch(5, 30, {rand: 0.1, continuous: true, gradient: 0.3});

• brush.noHatch()

// Disable hatching for upcoming shapes
    brush.noHatch();

• brush.hatchStyle(brushName, color, weight)

brush.hatchStyle("rotring", "green", 1.3);

• brush.mass(brushName, color, options)

brush.mass("pastel", "#4b6cb7", {
      precision: 0.55,
      strength: 0.9,
      gradient: 0.35,
      outline: true,
    });
    brush.circle(width / 2, height / 2, 180);

• brush.noMass()

brush.noMass();

• brush.hatchArray(polygons)

// Define an array of polygons (reference in the classes section)
    let myPolygons = []
    for (let i = 0; i < 10; i++) {
       // We're creating 10 random triangles here
    			let p = new brush.Polygon([
          [random(width), random(height)],
          [random(width), random(height)],
          [random(width), random(height)],  
       ])
       myPolygons.push(p)
    }
    // Create hatching across specified polygons
    brush.hatchArray(myPolygons);

• brush.massArray(polygons)

// Define two nested polygons — outer boundary and inner hole
    let outer = new brush.Polygon([[50,50],[350,50],[350,350],[50,350]]);
    let inner = new brush.Polygon([[100,100],[300,100],[300,300],[100,300]]);
    let myPolygons = [outer, inner];
// Apply mass to both as one combined gesture
    brush.mass("HB", "#002185", { strength: 1 });
    brush.massArray(myPolygons);

_{back to table}

Primitives

These are the functions that actually draw lines, paths, and shapes using the current stroke, fill, and hatch settings.

Lines, Strokes, Splines, and Plots

The following functions are only affected by stroke() operations, completely ignoring fill() and hatch().

• brush.line(x1, y1, x2, y2)

// Set the brush color and draw a line
    brush.stroke("red");
    brush.line(15, 10, 200, 10);

• brush.flowLine(x, y, length, dir)

// Set a vector field and draw a flow line
    brush.field("seabed");
    brush.flowLine(15, 10, 185, 0);

These three functions provide advanced control over the creation of strokes/paths, allowing for custom pressure and direction at different points along the path. Think of them as bodily movements performed with the hands. You can create two types of strokes: "curve" or "segments". For curved strokes, the curvature at any point is interpolated between the nearest control points.

These functions allow for the creation of strokes with varied pressures and directions, mimicking the organic nature of hand-drawn strokes. For an application of these principles, see: Enfantines II

• brush.beginStroke(type, x, y)

// Begin a new curve stroke
    brush.beginStroke("curve", 15, 30);

• brush.move(angle, length, pressure)

brush.move(30, 150, 0.6);
    brush.move(75, 40, 1.1);

• brush.endStroke(angle, pressure)

// Complete the stroke with a specific angle and pressure
    brush.endStroke(-45, 0.8);

• brush.spline(array_points, curvature)

let points = [[30, 70], [85, 20, 1.5], [130, 100], [180, 50]];
    brush.spline(points, 0.5);

brush.noStroke();
    brush.noHatch();
    brush.fill("#002185", 75);
    brush.rect(150, 100, 50, 35, "center");

brush.circle(100, 150, 75, true);

brush.arc(200, 200, 50, 0, Math.PI);