steveruizok /perfect-freehand
Draw perfect pressure-sensitive freehand lines.
★ 5,813⑂ 219👁 19⑃ 43● 45▤ 1
+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 getStrokeOutlinePointsTop issues
#88[Bug] Artefacts if strokeOptions.size is small3 comments · 2025-03-28#112[Bug] Improper handling of consecutive sharp corners1 comments · 2026-03-09#94[documentation] Clean up SVG path data example functions1 comments · 2025-11-08#93[documentation] Use tuple `[number, number]` for points instead of `number[]`1 comments · 2025-11-08#83[Bug] Skipping Input Points1 comments · 2024-07-15#70[documentation] How to use Flattening?1 comments · 2023-06-19
Discussions
#92Real World Demonstration — Freeform Chemistry Notes0 comments · 2025-08-03#91Customization Options to support Multiple Brushes1 comments · 2025-06-06#89Converting Canvas Drawing to SVG shrinks0 comments · 2025-04-26#82How to run Feather Icons through getStroke?0 comments · 2024-04-16#80How to include this in a native HTML/CSS/JS project1 comments · 2024-03-19#73How to use the SVG-file0 comments · 2023-11-22#71why auto remove previous line, when draw new line?1 comments · 2023-07-11#66Most performant settings?0 comments · 2023-02-05
Latest release
v1.2.3 v1.2.3 2026-02-01What'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.