vSignature Documentation

Introduction

vSignature is a premium, lightweight vanilla JavaScript library built to capture, render, and export high-fidelity hand-drawn signatures on HTML5 canvas elements. It contains vector physics to calculate brush thickness variations dynamically relative to drawing velocity, simulating realistic drawing instruments (e.g. fountain pens, quills, brushes).

The library is fully responsive, dependency-free, and designed to work cleanly inside any framework environment (Laravel, React, Vue, Angular, Node, etc.).

Installation

Install the library into your project dependency manager using npm:

npm install v-signature

Importing Options

Import the ES Module class directly inside your script bundles:

import vSignature from 'v-signature';

Or load using standard CommonJS modular requires:

const vSignature = require('v-signature');

Quick Start

Create a hidden HTML input field where the base64 signature images will be automatically stored during capture:

<input type="hidden" id="signature-data" class="signature">

Initialize the signature capture pad using Javascript:

document.addEventListener('DOMContentLoaded', () => {
    // initialize by passing target input id
    const signature = new vSignature('signature-data');
});

Core Parameters

You can customize the appearance, dimensions, and drawing behaviors by passing configuration parameters in the initialization options:

const signature = new vSignature('signature-data', {
    options: {
        width: '100%',
        height: '350px',
        backgroundColor: '#ffffff',
        border: '1px dashed #cccccc',
        borderRadius: '8px',
        disabled: false
    }
});

Options Properties Table

Pen Brush Presets

vSignature supports 5 built-in drawing presets, as well as a fully custom configuration option to define your own dynamic physics:

Custom Physics Config

const signature = new vSignature('signature-data', {
    options: {
        style: 'custom',
        minWidth: 0.8,              // min thickness at high speeds
        maxWidth: 4.5,              // max thickness at slow speeds
        velocitySensitivity: 0.65   // intensity of velocity transitions
    }
});

Custom Pen Cursor Example

You can customize the mouse cursor shape by providing a custom image URL (such as an ornate green feather quill pen):

const signature = new vSignature('signature-data', {
    options: {
        pen: 'https://png.pngtree.com/png-clipart/20250419/original/pngtree-ornate-green-feather-quill-pen-with-gold-detailing-isolated-png-image_20738981.png'
    }
});

Watermarks & Guidelines

Draw background aids and copyright watermarks directly onto the signature pad at the vector level:

const signature = new vSignature('signature-data', {
    options: {
        // watermark settings
        watermark: 'OFFICIAL USE ONLY',
        watermarkColor: 'rgba(0, 0, 0, 0.05)',
        watermarkFont: '24px sans-serif',
        watermarkAngle: -45,

        // guideline settings
        guideLine: 'Dotted Guideline Title',
        guideLineColor: 'rgba(0, 0, 0, 0.15)',
        guideLineExport: false // do not burn guideline into image exports
    }
});

Public Methods

Interact with the signature pad instance using standard programmatic API methods:

Callbacks & Events

Bind to changes using the built-in programmatic event listeners:

// bind to change events
signature.on('change', (base64Data) => {
    if (base64Data) {
        console.log('signature captured: ', base64Data);
    } else {
        console.log('signature cleared');
    }
});

License

Released under the standard MIT License. See the LICENSE file for details.