✍️ Vue3 Signature

A smooth and elegant electronic signature component for Vue 3

Powered by signature_pad - The most popular HTML5 canvas based signature library

[![npm version](https://img.shields.io/npm/v/vue3-signature.svg?style=flat-square)](https://www.npmjs.com/package/vue3-signature) [![npm downloads](https://img.shields.io/npm/dm/vue3-signature.svg?style=flat-square)](https://www.npmjs.com/package/vue3-signature) [![license](https://img.shields.io/npm/l/vue3-signature.svg?style=flat-square)](https://github.com/WangShayne/vue3-signature/blob/master/LICENSE) [![vue3](https://img.shields.io/badge/vue-3.x-brightgreen.svg?style=flat-square)](https://vuejs.org/) [![signature_pad](https://img.shields.io/badge/signature__pad-5.1.1-orange.svg?style=flat-square)](https://github.com/szimek/signature_pad) [🎮 Try Online](#-try-online) • [✨ Features](#-features) • [🚀 Quick Start](#-quick-start) • [📖 Documentation](#-documentation) • [💡 Examples](#-examples)

English | 简体中文

--- ## 🎮 Try Online Experience Vue3 Signature without any installation: **👉 [Live Demo on GitHub Pages](https://wangshayne.github.io/vue3-signature/)** - Try all features in your browser! > The demo showcases all component features including drawing, saving, undo, watermarks, and more. ### 🚀 Deploy Your Own Demo Want to deploy your own demo? Check out our [Deployment Guide](./DEPLOY.md) for detailed instructions on deploying to GitHub Pages. ### 📁 New: Image Import Feature The live demo now supports **importing images**: - 📁 Upload local image files - 🔗 Load images from URLs - 🖼️ Try sample images with one click Perfect for editing existing signatures, adding annotations, or working with templates! ## ✨ Features ### 🎯 Core Technology Built on top of **[signature_pad](https://github.com/szimek/signature_pad)** by Szymon Nowak - the industry-standard HTML5 canvas based smooth signature drawing library with **13k+ GitHub stars** and proven reliability. ### ⚡ Key Features - 📱 **Touch & Mouse Support** - Works seamlessly on both mobile and desktop devices - 🎨 **Customizable** - Fully customizable pen color, background, and signature styles - 💾 **Multiple Export Formats** - Export signatures as PNG, JPEG, or SVG - 🔄 **Undo Support** - Easy undo functionality for better user experience - 🖼️ **Watermark Support** - Add custom watermarks to signatures - 🚫 **Disable Mode** - Toggle between editable and read-only states - 📐 **Responsive** - Automatically adapts to container size - 🎯 **TypeScript Support** - Full TypeScript type definitions included - ⚡ **Lightweight** - Small bundle size with no unnecessary dependencies - 🌍 **Cross-Platform** - Works on all modern browsers and mobile devices ![Demo](./1.gif) ## 🚀 Quick Start ### Installation ```bash # Using npm npm install vue3-signature # Using yarn yarn add vue3-signature # Using pnpm pnpm add vue3-signature ``` ### Basic Usage **Step 1:** Register the component globally ```javascript // main.js import { createApp } from "vue"; import Vue3Signature from "vue3-signature"; import App from "./App.vue"; createApp(App).use(Vue3Signature).mount("#app"); ``` **Step 2:** Use it in your component ```vue ``` ## 📖 Documentation ### Props | Property | Type | Default | Description | | --------------- | --------- | ----------------------------------------------------------------- | --------------------------------------------------------------------- | | `sigOption` | `Object` | `{penColor: "rgb(0, 0, 0)", backgroundColor: "rgb(255,255,255)"}` | Signature pad options including pen color and background color | | `w` | `String` | `"100%"` | Width of the signature pad (e.g., `"100%"`, `"500px"`) | | `h` | `String` | `"100%"` | Height of the signature pad (e.g., `"100%"`, `"300px"`) | | `clearOnResize` | `Boolean` | `false` | Whether to clear the canvas when window is resized | | `waterMark` | `Object` | `{}` | Watermark configuration (see [Watermark Options](#watermark-options)) | | `disabled` | `Boolean` | `false` | Disable/enable signature input | | `defaultUrl` | `String` | `""` | Default image URL to display on canvas | > 💡 `sigOption` accepts the full [`SignaturePad.Options`](https://github.com/szimek/signature_pad#options) interface. The component watches it deeply and recreates the pad with your new settings while preserving the current drawing whenever possible. ### Methods Access these methods via the component ref — every public method from `signature_pad` is available: | Method | Parameters | Return | Description | | --------------------------------- | -------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | | `save(format?, encoderOptions?)` | `format?: string`, `encoderOptions?: number \| ToSVGOptions` | `string` | Alias of `toDataURL()` for backwards compatibility. | | `toDataURL(format?, encoderOptions?)` | Same as `SignaturePad#toDataURL` | `string` | Export the drawing as PNG/JPEG/SVG (see MDN for encoder options). | | `toSVG(options?)` | `options?: ToSVGOptions` | `string` | Export the SVG string with optional background/data URL layers. | | `clear()` | - | `void` | Clear the canvas using the current background color. | | `redraw()` | - | `void` | Re-render the stored strokes and any data URL that was imported. | | `isEmpty()` | - | `boolean` | Check whether anything has been drawn. | | `undo(steps = 1)` | `steps?: number` | `void` | Remove the last stroke(s) and re-render the remainder. | | `toData()` | - | `PointGroup[]` | Read the raw stroke data from `signature_pad`. | | `fromData(pointGroups, options?)` | `pointGroups: PointGroup[]`, `options?: FromDataOptions` | `void` | Draw from raw stroke data with optional clear control. | | `fromDataURL(url, options?)` | `url: string`, `options?: FromDataUrlOptions` | `Promise` | Import an image/data URL exactly like `signature_pad`. | | `addWaterMark(options)` | `options: WaterMarkOption` | `void` | Draw custom watermark text (utility helper provided by this component). | | `trim(options?)` | `options?: TrimOptions` | `TrimResult \| null` | Clone the canvas, crop out surrounding whitespace, and return the off-screen result without mutating the visible canvas. | | `toTrimmedDataURL(format?, encoderOptions?)` | `format?: string`, `encoderOptions?: number` | `string` | Convenience helper that returns only the cropped data URL (internally calls `trim`). | | `enable()` / `disable()` | - | `void` | Direct proxies for `signaturePad.on()` / `signaturePad.off()`. | | `addEventListener(...)` | Same signature as `EventTarget#addEventListener` | `void` | Listen to low-level stroke events directly on the wrapped `SignaturePad` instance. | | `removeEventListener(...)` | Same signature as `EventTarget#removeEventListener` | `void` | Remove listeners that were previously attached. | | `getInstance()` | - | `SignaturePad \| null` | Access the underlying `SignaturePad` instance if you need complete control over every API surface. | ### Events All native `signature_pad` events are forwarded so you can react to drawing lifecycle changes: | Event | Payload | Description | | -------------------- | ------------------- | ------------------------------------------------------------------------------------------- | | `ready` | `SignaturePad` | Emitted after the canvas has been initialised/resized and the instance is ready to use. | | `begin` / `end` | `void` | Compatibility shims for `signaturePad.onBegin` / `onEnd`. | | `beginStroke` | `SignatureEvent` | Fired before a stroke starts (cancelable via `event.preventDefault()` in `signature_pad`). | | `beforeUpdateStroke` | `SignatureEvent` | Fired before a stroke segment is rendered. | | `afterUpdateStroke` | `SignatureEvent` | Fired after a stroke segment is rendered. | | `endStroke` | `SignatureEvent` | Fired after a stroke ends. | ### Signature Options ```typescript import type { Options as SignaturePadOptions } from "signature_pad"; type SigOption = SignaturePadOptions & { // You can still pass anything supported by signature_pad: dotSize, min/maxWidth, throttle, minDistance, etc. }; // Commonly used fields // dotSize?: number; // minWidth?: number; // maxWidth?: number; // minDistance?: number; // throttle?: number; // velocityFilterWeight?: number; // penColor?: string; // backgroundColor?: string; // compositeOperation?: GlobalCompositeOperation; // canvasContextOptions?: CanvasRenderingContext2DSettings; ``` ### Watermark Options ```typescript interface WaterMarkOption { text?: string; // Watermark text (default: "") font?: string; // Font style (default: "20px sans-serif") style?: string; // Style type: "all" | "stroke" | "fill" (default: "fill") fillStyle?: string; // Fill color (default: "#333") strokeStyle?: string; // Stroke color (default: "#333") x?: number; // Fill text X position (default: 20) y?: number; // Fill text Y position (default: 20) sx?: number; // Stroke text X position (default: 40) sy?: number; // Stroke text Y position (default: 40) } ``` ### Trim Result & Options ```typescript interface TrimResult { canvas: HTMLCanvasElement; // The cropped off-screen canvas dataUrl: string; // Convenience data URL generated from the cropped canvas bounds: { x: number; y: number; width: number; height: number }; // Crop rectangle (device pixels) } interface TrimOptions { format?: string; // Any value accepted by canvas.toDataURL, e.g. "image/png", "image/jpeg" encoderOptions?: number; // Quality argument for JPEG/WebP backgroundColor?: string;// Override the color used to detect empty pixels (defaults to SignaturePad.backgroundColor) } ``` ## 💡 Examples ### Save as Different Formats ```vue ``` ### Custom Pen Colors and Styles ```vue ``` ### Add Watermark ```vue ``` ### Disabled Mode (Read-only) ```vue ``` ### Load from Data URL ```vue ``` ### Responsive Design ```vue ``` ## 🔧 Advanced Usage ### Complete Example with All Features ```vue ``` ## 🌐 Browser Support Vue3 Signature works on all modern browsers: - ✅ Chrome (latest) - ✅ Firefox (latest) - ✅ Safari (latest) - ✅ Edge (latest) - ✅ Opera (latest) - ✅ Mobile browsers (iOS Safari, Chrome Mobile) ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request ## 📝 Changelog See [Releases](https://github.com/WangShayne/vue3-signature/releases) for detailed changelog. ## 🙏 Credits & Dependencies ### Core Dependency This Vue 3 component is a wrapper around **[signature_pad](https://github.com/szimek/signature_pad)** - the most popular and reliable HTML5 canvas based signature library. **Why signature_pad?** - ⭐ **13,000+ GitHub Stars** - Trusted by thousands of developers worldwide - 🏆 **Industry Standard** - Used in countless production applications - 🎨 **Smooth Drawing** - Advanced Bézier curve interpolation for natural signatures - 📱 **Touch Optimized** - Perfect support for touchscreens and stylus input - 🔧 **Well Maintained** - Active development and regular updates - 📦 **Lightweight** - Minimal footprint with maximum functionality **Library Information:** - Author: [Szymon Nowak](https://github.com/szimek) - Repository: [github.com/szimek/signature_pad](https://github.com/szimek/signature_pad) - License: MIT - Current Version: 5.1.1 By using Vue3 Signature, you get all the power of signature_pad with the simplicity of Vue 3's Composition API. ## 📄 License [MIT License](https://opensource.org/licenses/MIT) Copyright (c) 2024 Shayne Wang --- ## 🔗 Related Projects - **[vue-signature](https://github.com/WangShayne/vue-signature)** - Vue 2.x version - **[signature_pad](https://github.com/szimek/signature_pad)** - The underlying signature library ---

Made with ❤️ by Shayne Wang
If this project helped you, please consider giving it a ⭐️

### Remove Blank Space Around the Signature ```vue ``` The implementation is based on the [popular workaround described here](https://github.com/szimek/signature_pad/issues/49#issuecomment-260976909): the component copies the current canvas, crops out the empty pixels, and returns the cropped data URL without mutating the visible canvas. Use it on `@end` to keep a continuously trimmed value if needed.