steveruizok /perfect-freehand

Draw perfect pressure-sensitive freehand lines.

★ 5,813⑂ 219👁 19⑃ 43● 45▤ 1
HTMLMITCreated 2021-02-19perfectfreehand.com
Download: v1.2.3v1.2.3 ↓1.2.32026-02-01
+0
Daily
5,813
stars
219
forks
19
watchers
43
prs
45
issues
1
releases

README

!Screenshot

Draw perfect pressure-sensitive freehand lines.

🔗 Curious? Try out a demo.

💅 Designer? Check out the Figma Plugin.

🕊 This library is written in TypeScript but are community ports in:
- dart version
- odin
- python
- rust
- ...and probably more. Make a pull request!

💕 Love this library? Consider becoming a sponsor.

 Table of Contents

- Installation
- Usage
- Documentation
- Community
- Author

 Installation

bash
npm install perfect-freehand


or

bash
yarn add perfect-freehand


 Introduction

This package exports a function named getStroke that will generate the points for a polygon based on an array of points.

!Screenshot

To do this work, getStroke first creates a set of spline points (red) based on the input points (grey) and then creates outline points (blue). You can render the result any way you like, using whichever technology you prefer.



 Usage

To use this library, import the getStroke function and pass it an array of input points, such as those recorded from a user's mouse movement. The getStroke function will return a new array of outline points. These outline points will form a polygon (called a "stroke") that surrounds the input points.

js
import { getStroke } from 'perfect-freehand'

const inputPoints = [
  [0, 0],
  [10, 5],
  [20, 8],
  // ...
]

const outlinePoints = getStroke(inputPoints)


You then can render your stroke points using your technology of choice. See the Rendering section for examples in SVG and HTML Canvas.

You can customize the appearance of the stroke shape by passing getStroke a second parameter: an options object containing one or more options. See the Options section for a full list of available options.

js
const stroke = getStroke(myPoints, {
  size: 32,
  thinning: 0.7,
})


The appearance of a stroke is effected by the pressure associated with each input point. By default, the getStroke function will simulate pressure based on the distance between input points.

To use real pressure, such as that from a pen or stylus, provide the pressure as the third number for each input point, and set the simulatePressure option to false.

js
const inputPoints = [
  [0, 0, 0.5],
  [10, 5, 0.7],
  [20, 8, 0.8],
  // ...
]

const outlinePoints = getStroke(inputPoints, {
  simulatePressure: false,
})


In addition to providing points as an array of arrays, you may also provide your points as an array of objects as show in the example below. In both cases, the value for pressure is optional (it will default to .5).

js
const inputPoints = [
  { x: 0, y: 0, pressure: 0.5 },
  { x: 10, y: 5, pressure: 0.7 },
  { x: 20, y: 8, pressure: 0.8 },
  // ...
]

const outlinePoints = getStroke(inputPoints, {
  simulatePressure: false,
})


Note: Internally, the getStroke function will convert your object points to array points, which will have an effect on performance. If you're using this library ambitiously and want to format your points as objects, consider modifying this library's getStrokeOutlinePoints

Top issues

Discussions

Latest release

v1.2.3 v1.2.3 2026-02-01
What's Changed

Internal improvements and maintenance:

- Refactored getStrokeOutlinePoints for better readability (extracted helpers, renamed variables)
- Performance optimization in getStrokePoints hot loop
- Modernized build tooling (Rolldown, Vite, Vitest)
- Added benchmark support

No breaking changes or API modifications.

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON