@signosoft/signpad-js

📍 Table of Contents

| Core Concepts & Overview | Getting Started & Usage | Advanced & Support | | :---------------------------------------- | :--------------------------------- | :--------------------------------- | | 📜 Description | 📦 Installation | 🤝 Feedback | | 🎬 Demo | 🔐 Licensing | 📄 License | | ⚙️ Tech stack | 🚀 Quick Start | | | | 📋 Properties | | | | 🧩 Methods | | | | 🎨 Styling | |

📜 Description

signosoft-signpad is a powerful and flexible web component built with LitElement, designed for seamless digital signature capture integration into modern web applications. It provides a unified interface for working with various signature devices like Wacom or Ugee, supporting both stylus and mouse-based signing.

This component works effortlessly with any modern stack:

It expertly handles the complexities of WebHID device connections, signature session lifecycles, and high-fidelity stroke rendering.

🎬 Demo

⚙️ Tech Stack / Built With

🔐 Get your license

To use the Signosoft Signpad component and its hardware drivers, a valid license key is required.

🛑 CRITICAL: Mandatory Initialization

Without a valid license key, the component WILL NOT INITIALIZE and all hardware communication features will be disabled.

1. How to obtain a license:

1. Go to www.signosoft.com
2. Sign in to your account.
3. Navigate to Settings > Get License.
4. Click Generate API Key (License Key).
5. Copy your key and add it to your configuration.

2. Implementation:

Add the key to the licenseKey field in your configuration object:

const config: SignpadConfig = {
  licenseKey: "YOUR-LICENSE-KEY-HERE", // Required
  // ... other options

  // For local development, ensure your license is valid for localhost.
};

📦 Installation

Install the library via npm:

npm install @signosoft/signpad-js

Or using your preferred manager:

yarn add @signosoft/signpad-js

pnpm add @signosoft/signpad-js

🌍 Environment Requirements

To ensure proper communication via the WebHID API:

• HTTPS: Required for all production environments (WebHID security policy).
• Supported Browsers: Chrome 89+, Edge 89+, Opera (Chromium-based).
• TypeScript: Built-in support; no extra @types needed.

🚀 Quick Start

First, install the core package:

npm install your-library-name

🧰 Framework Integration Guide

Angular Integration Guide

This guide describes how to integrate the @signosoft/signpad-js web component into an Angular application.

1. Installation

Install the core package using npm:

npm install @signosoft/signpad-js

2. Create the Bridge Directive

Since signosoft-signpad is a Web Component, Angular requires a Directive to properly sync configuration changes and provide typed access to the component instance.

Create signosoft-signpad.directive.ts:

import {
  Directive,
  ElementRef,
  Input,
  OnChanges,
  SimpleChanges,
} from "@angular/core";
import type { SignosoftSignpad, SignpadConfig } from "@signosoft/signpad-js";

@Directive({
  selector: "signosoft-signpad",
  standalone: true,
})
export class SignosoftSignpadDirective implements OnChanges {
  @Input() config?: SignpadConfig;

  constructor(private host: ElementRef<SignosoftSignpad>) {}

  // Access the native Web Component instance
  get signpadRef(): SignosoftSignpad {
    return this.host.nativeElement;
  }

  ngOnChanges(changes: SimpleChanges) {
    const el = this.host.nativeElement as any;
    for (const key of Object.keys(changes)) {
      el[key] = (this as any)[key];
    }
  }
}

3. Implementation in Component

Import the library, the directive, and add the CUSTOM_ELEMENTS_SCHEMA.

import { Component, ViewChild, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@signosoft/signpad-js"; // Import the Web Component registration
import {
  type SignosoftSignpad,
  type SignpadConfig,
} from "@signosoft/signpad-js";
import { SignosoftSignpadDirective } from "./directives/signosoft-signpad.directive";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [SignosoftSignpadDirective],
  templateUrl: "./app.component.html",
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Mandatory for custom HTML tags
})
export class AppComponent {
  @ViewChild(SignosoftSignpadDirective)
  signpadDirective!: SignosoftSignpadDirective;

  config: SignpadConfig = {
    licenseKey: "YOUR-LICENSE-KEY",
    // More info in "properties" section
  };

  // Helper to access methods easily (ok, clear, cancel, etc.)
  public get signpad(): SignosoftSignpad | undefined {
    return this.signpadDirective?.signpadRef;
  }
}

4. Component Template

Use the custom tag in your HTML and bind the configuration object.

<div>
  <div>
    <signosoft-signpad [config]="config"></signosoft-signpad>
  </div>
</div>

React - Quick start

This guide describes how to integrate the @signosoft/signpad-js web component into a React application (Functional Components with Hooks).

1. Installation

Install the core package using npm:

npm install @signosoft/signpad-js

2. Implementation

In React, we use the useRef hook to interact with the component's methods (like ok() or clear()) and pass the configuration directly via props.

import { useRef } from "react";
import "@signosoft/signpad-js"; // Registers the web component
import type { SignpadConfig } from "@signosoft/signpad-js";

function App() {
  // Use ref to access component methods (ok, clear, connect, etc. by signpadRef.current)
  const signpadRef = useRef<any>(null);

  const config: SignpadConfig = {
    licenseKey: "YOUR-LICENSE-KEY",
    // More info in "properties" section
  };

  return (
    <div>
      <h1>Signosoft Signpad React Example</h1>
      <signosoft-signpad ref={signpadRef} config={config} />
    </div>
  );
}

export default App;

Vue.js Integration Guide

This guide describes how to integrate the @signosoft/signpad-js web component into a Vue 3 application using the Composition API (<script setup>).

1. Installation

Install the core package using npm:

npm install @signosoft/signpad-js

2. Configure Vue to recognize Custom Elements

By default, Vue will try to resolve signosoft-signpad as a Vue component and will throw a warning. You need to tell Vue to ignore this tag.

If you are using Vite (vite.config.ts):

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // Treat all tags starting with 'signosoft-' as custom elements
          isCustomElement: (tag) => tag.startsWith("signosoft-"),
        },
      },
    }),
  ],
});

3. Implementation

In Vue 3, we use ref to hold the reference to the DOM element and pass the configuration via the :config attribute.

<script setup lang="ts">
import { ref } from "vue";
import "@signosoft/signpad-js"; // Registers the Web Component
import type { SignpadConfig, SignosoftSignpad, IPenData } from "@signosoft/signpad-js";

// Use ref to access component methods (ok, clear, connect, etc. by signpadRef.value)
const signpadRef = ref<SignosoftSignpad | null>(null);

const signpadConfig: SignpadConfig = {
  licenseKey: "YOUR-LICENSE-KEY",
  // More info in "properties" section
};

</script>

<template>
  <div>
    <signosoft-signpad
      ref="signpadRef"
      :config="signpadConfig"
    ></signosoft-signpad>
  </div>
</template>

🍦 Vanilla JS Integration Guide

This guide describes how to integrate the @signosoft/signpad-js web component into a plain JavaScript project without any frameworks.

1. Installation

Install the package via npm:

npm install @signosoft/signpad-js

Or, if you are not using a bundler, you can include the script directly in your HTML (ensure the path points to the compiled bundle in node_modules or a CDN).

2. JavaScript Implementation

In Vanilla JS, you interact with the component by selecting it from the DOM and assigning the configuration directly to its config property.

import "@signosoft/signpad-js";

/**
 * INTELLISENSE SUPPORT (Optional)
 * Helps VS Code provide autocomplete for methods and properties.
 * @type {import('@signosoft/signpad-js').SignosoftSignpad}
 */
const pad = document.querySelector("signosoft-signpad");

// 1. Initial Configuration
pad.config = {
  licenseKey: "YOUR-LICENSE-KEY",
};

3. HTML Structure

Add the custom element tag to your HTML and create the necessary control buttons.

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Signosoft Signpad - Vanilla JS</title>
  </head>
  <body>
    <h1>Signosoft Signpad</h1>
    <!-- The Web Component -->
    <signosoft-signpad id="my-signpad"></signosoft-signpad>
    <!-- Main logic script -->
    <script type="module" src="main.js"></script>
  </body>
</html>

4. Key Concepts

• Direct Property Assignment: Unlike some frameworks that use attributes, in Plain JS you should assign the configuration directly: element.config = { ... }.
• Module System: Ensure your <script> tag has type="module" to use the import statement.
• Methods: All methods like .connect(), .ok(), and .clear() are available directly on the DOM element object.
• DOM Events: The component dispatches standard DOM events (like sign-ok, sign-clear) which you can listen to using addEventListener.

📋 Properties

The component is primarily configured through a single config property. This object controls everything from licensing and hardware behavior to UI visibility and localization.

| Property | Type | Default | Description | | :------- | :-------------- | :---------- | :----------------------------------------------- | | config | SignpadConfig | undefined | The main configuration object for the component. |

🔑 Core Options

| Option | Type | Required | Description | | :------------------- | :------- | :------- | :-------------------------------------------------------------------- | | licenseKey | string | Yes | Your unique API key from signosoft.com. Mandatory for initialization. | | customCssVariables | object | No | Custom theme object generated via the getSignpadTheme utility. |

🔄 autoconnectOptions

Controls how the component handles hardware connections and session flow.

| Field | Type | Default | Description | | :------------------------------ | :-------- | :------ | :---------------------------------------------------------------------------------------------------- | | autoConnect | boolean | false | Attempts to connect to an authorized device on startup. Defaults to mouse mode if no device is found. | | autoConnectOnPlugIn | boolean | false | Automatically initiates connection when a compatible and authorized device is plugged into USB. | | autoRestartSigningAfterAction | boolean | false | Automatically calls startSigning() after a user completes an action (OK/Cancel). |

👁️ uiVisibilityOptions

Toggles the visibility of specific User Interface elements.

| Field | Type | Description | | :------------------------- | :-------- | :-------------------------------------------------------------- | | topBarVisible | boolean | Shows/hides the entire top navigation bar. | | topBarClearButtonVisible | boolean | Shows a "Clear" button in the top-left corner. | | bottomBarVisible | boolean | Shows/hides the entire bottom action bar. | | okButtonVisible | boolean | Shows the OK button in the bottom bar. | | clearButtonVisible | boolean | Shows the Clear button in the bottom bar. | | cancelButtonVisible | boolean | Shows the Cancel button in the bottom bar. | | canvasLineVisible | boolean | Shows the horizontal signature guide line on the canvas. | | deviceStatusTextVisible | boolean | Shows the name of the connected device (e.g., "Wacom STU-540"). | | additionalTextVisible | boolean | Shows helper status messages (e.g., "Ready to sign"). |

🖋️ canvasAndDrawingOptions

Adjusts the visual appearance of the digital ink.

| Field | Type | Default | Description | | :--------- | :------- | :-------- | :------------------------------------------ | | color | string | #000000 | The HEX color of the signature stroke. | | minWidth | number | 1 | The line thickness at minimum pen pressure. | | maxWidth | number | 3 | The line thickness at maximum pen pressure. |

Note: Since standard mice do not support physical pressure, the system emulates a normalized pressure of 0.5, ensuring consistent line rendering during fallback sessions.

🌐 languageOptions

Handles component localization. It can load external files or use inline definitions.

| Field | Type | Description | | :------------- | :------- | :---------------------------------------------------------------------------------------------------- | | lang | string | The active language code (supported languages - 'en', 'cs', 'pt'). | | langPath | string | URL path to fetch translation files. Expects files in [path]/[lang].json format. | | translations | object | An inline object containing key-value pairs (e.g., { "OK": "Confirm signature" }). Overrides files. |

⚙️ Logic & Events

The component provides two ways to interact with internal processes.

🛠️ Action Handlers (actionHandlers)

These allow you to inject custom logic directly into the internal button flows. Your code runs alongside the component's internal logic.

| Handler | Arguments | Description | | :------------- | :----------- | :---------------------------------------------------------------------- | | handleOk | data?: any | Extends the internal OK button logic. Receives captured signature data. | | handleClear | — | Extends the internal Clear button logic. | | handleCancel | — | Extends the internal Cancel button logic. |

🔔 Event Callbacks (eventCallbacks)

Standard event listeners triggered after specific actions. Useful for observing the component from your application state.

| Callback | Payload | Description | | :------------- | :------------------------------ | :------------------------------------------------------------------------------------------------- | | onPen | event: CustomEvent<IPenData> | Dispatched when a device or mouse fallback are in contact with component or signature pad display. | | onConnect | event: CustomEvent | Dispatched when a device or mouse fallback connects. | | onDisconnect | — | Dispatched when the hardware connection is closed. | | onOk | data: any | Dispatched when signature is confirmed. | | onClear | — | Dispatched when the canvas has been cleared. | | onCancel | — | Dispatched when the user aborts the session. | | onError | error: Error | Dispatched on critical failures (License, Driver, etc.). |

💡 Example Implementation

this.config = {
  licenseKey: "your-signosoft-license-key",
  autoconnectOptions: {
    autoConnect: true,
  },
  canvasAndDrawingOptions: {
    color: "#1a1a1a",
  },
  actionHandlers: {
    handleOk: async (data) => {
      console.log("Saving signature data...", data);
    },
  },
  eventCallbacks: {
    onConnect: (e) =>
      console.log("Pad connected:", e.detail.deviceInfo.deviceName),
    onError: (err) => console.error("Signpad Error:", err.message),
  },
};

🧩 Methods

The following methods are available on the component instance to control the signing process programmatically.

| Method | Returns | Description | | :--------------- | :----------------- | :------------------------------------------------------------------------------- | | connect() | Promise<boolean> | Connects device to component | | disconnect() | Promise<void> | Disconnects device from component | | startSigning() | Promise<void> | Initializes a new signing session on the canvas and hardware. | | stopSigning() | Promise<any> | Immediately ends the session and returns the captured signature data. | | ok() | Promise<any> | Finalizes the session, cleans the device screen, and returns the signature data. | | clear() | Promise<void> | Wipes the signature from the UI and hardware without ending the session. | | cancel() | Promise<void> | Aborts the current session and resets the component state. |

📜 connect(autoConnect = false, allowFallback = false)

This is the primary method to start using the Signpad. Because it uses the WebHID API, the first time this is called (without autoConnect), it must be triggered by a user gesture (like a button click) to satisfy browser security requirements.

Parameters:

• autoConnect (boolean): If set to true, the browser will attempt to reconnect to a previously paired and authorized device without opening the device selection dialog from WebHID.
• allowFallback (boolean): If true and no physical device is found or connected, the component will automatically transition to Mouse/Touch mode, allowing the user to sign using their cursor.

Returns:

• A Promise<boolean> that resolves to true if either a physical device or a fallback mode was successfully initialized.

📜 disconnect()

Safely terminates the communication channel with the signature tablet.

What happens during disconnect:

1. The hardware driver is stopped and released.
2. The internal cache of device information is cleared.
3. The component UI transitions back to the DISCONNECTED state.
4. Any active mouse listeners are removed.
5. A SIGN_DISCONNECT event is dispatched.

💡 Best Practices

• Initial Connection: Always call connect(false, true) from a click handler the very first time so the user can select their device from the browser list.
• Auto-Reconnect: In many workflows, you can call connect(true, true). If the user has already authorized the device in a previous session, it will connect silently.
• Cleanup: It is good practice to call disconnect() when the component is being destroyed or the user navigates away from the signing page to free up the USB port.

📜 startSigning(options?: IDrawingOptions)

Prepares the component for a new signature. It transitions the state to CONNECTING, resets any previous drawing data, and activates the pen input for either a physical device or mouse fallback.

// Example: Start a session with custom ink
await signpad.startSigning({
  color: "#0000FF",
  maxWidth: 4,
  minWidth: 2,
});

If you have autoRestartSigningAfterAction enabled in your config, the component will automatically call startSigning() again after an ok or cancel action is completed.

📜 ok()

This is the standard way to confirm a signature. It:

1. Stops the signing process.
2. Clears the physical device's screen (if connected).
3. Dispatches the SIGN_OK event.
4. Returns the final signature payload (coordinates, pressure, metadata).

📜 stopSigning()

A low-level method that forces the driver to stop capturing data and returns the raw signature object. Unlike ok(), it does not trigger the full "Finalization" flow (UI transitions or device screen clearing).

📜 clear()

Resets the drawing state on both the web canvas and the physical tablet's display. This allows the user to start their signature over without leaving the current session. It dispatches the SIGN_CLEAR event.

📜 cancel()

Stops the session immediately. It does not collect any signature data and resets the component to its ready state. This method dispatches the SIGN_CANCEL event.

🎨 Styling & Theming

The component is designed to be fully customizable to match your brand's identity. You can style it using CSS Variables or by using our built-in Theme Generator.

🛠️ Built-in Theme Generator

The easiest way to create a consistent theme is to use our CLI utility. It generates a configuration object that you can pass directly to the component.

1. Run the generator in your terminal:

npx getSignpadTheme

The CLI will guide you through:

• Output path: Where to save the file.
• Filename: What to call the file.
• Format: Choose between .js or .ts.

2. Import and apply the theme: Once generated, import the file and pass it to your configuration object:

import { myCustomTheme } from "./styles/myCustomTheme";

this.config = {
  licenseKey: "...",
  customCssVariables: myCustomTheme,
};

✍️ Manual CSS Customization

You can override the CSS variables directly in your global stylesheet to fine-tune the appearance:

signosoft-signpad {
  --primary-color-0: #0056b3;
  --sign-canvas-bg-base: #ffffff;
}

📋 Full CSS Variable Reference

Base Colors & General

| Variable | Default | Description | | :---------------------- | :------------------ | :-------------------------- | | --primary-color-0 | #4e56ea | Primary brand color. | | --primary-color-10 | #7178ee | Primary hover/accent color. | | --background-color-0 | #f1f2fd | Secondary background color. | | --background-color-10 | #e3e4fc | Main bar background color. | | --text-color-0 | #333e4a | Main text color. | | --white-color | #ffffff | Pure white color. | | --grey-color | #b5b9be | Disabled state color. | | --sign-font-family | Arial, sans-serif | Global font family. |

Layout & Constraints

| Variable | Default | Description | | :---------------------- | :---------- | :------------------------------------- | | --min-height | 48px | Minimum height for bars and buttons. | | --spacing-constraints | 16px 24px | Default padding/margin for containers. |

Top Bar

| Variable | Description | | :-------------------------- | :------------------------------- | | --sign-top-bar-bg-base | Background color of the top bar. | | --sign-top-bar-text-base | Text color in the top bar. | | --sign-top-bar-padding | Inner padding of the top bar. | | --sign-top-bar-min-height | Minimum height of the top bar. |

Canvas & Signature Line

| Variable | Description | | :---------------------------------- | :-------------------------------------------- | | --sign-canvas-bg-base | Background color of the drawing area. | | --sign-line-height | Vertical offset/height for the guide line. | | --sign-line-border-base | Color of the signature guide line. | | --sign-line-additional-text-color | Color of the helper text below the line. | | --sign-line-margin | Spacing around the guide line. | | --sign-canvas-line-text-font-size | Font size for guide line labels. | | --sign-canvas-height-offset | Canvas offset calculation for the guide line. |

Bottom Bar

| Variable | Description | | :----------------------------- | :--------------------------------------- | | --sign-bottom-bar-bg-base | Background color of the bottom bar. | | --sign-bottom-bar-padding | Inner padding of the bottom bar. | | --sign-bottom-bar-min-height | Minimum height of the bottom bar. | | --sign-bottom-bar-gap | Space between buttons in the bottom bar. |

Buttons (General)

| Variable | Default | Description | | :------------------------- | :------------ | :------------------------------- | | --sign-button-font-size | 12px - 16px | Fluid font size for all buttons. | | --sign-button-padding | 14px 16px | Inner padding for all buttons. | | --sign-button-min-height | 48px | Minimum height for buttons. |

Primary Buttons (OK, Clear, Cancel)

| Variable | Description | | :------------------------------------ | :----------------------------------- | | --sign-button-primary-bg-base | Background color of primary buttons. | | --sign-button-primary-bg-hover | Hover background color. | | --sign-button-primary-bg-disabled | Disabled background color. | | --sign-button-primary-text-base | Text color for primary buttons. | | --sign-button-primary-text-hover | Hover text color. | | --sign-button-primary-text-disabled | Disabled text color. |

Link/Connect Buttons

| Variable | Description | | :-------------------------------- | :------------------------------------------- | | --sign-button-link-bg-base | Background color for secondary/link buttons. | | --sign-button-link-text-base | Text color for secondary/link buttons. | | --sign-button-link-border-base | Border for secondary/link buttons. | | --sign-button-link-text-hover | Hover text color. | | --sign-button-link-border-hover | Hover border color. |

Status & Overlays

| Variable | Default | Description | | :-------------------------------------------- | :---------- | :--------------------------------- | | --sign-device-state-text-color-connected | green | Text color when device is ready. | | --sign-device-state-text-color-disconnected | red | Text color when disconnected. | | --sign-loading-overlay-bg-color | rgba(...) | Background of the loading spinner. | | --sign-loading-overlay-spinner-color | #4e56ea | Color of the animated spinner. | | --sign-loading-overlay-spinner-size | 30px | Size of the spinner icon. |

🤝 Feedback & Support

We are constantly working to improve our components and drivers. Your feedback is essential to us. Whether you found a bug, have a feature request, or need technical assistance, please reach out to us:

• 📧 Support Email: [email protected]
• 🌐 Official Website: www.signosoft.com

📄 License

Proprietary Commercial License

Copyright © 2026, Signosoft. All rights reserved.

This software is proprietary to Signosoft and is protected by copyright laws. It is not open source.

🔐 Commercial Usage

A valid, paid, and active commercial license agreement with Signosoft is strictly required for the use, operation, reproduction, distribution, or deployment of this software in any environment (including development, testing, staging, and production).

📜 Key Terms

• Unauthorized Use: Any use without a current, fully paid license is expressly prohibited and constitutes a violation of our intellectual property rights.
• Legal Action: Signosoft reserves the right to pursue legal action to enforce its rights and seek damages for unauthorized use.
• Restrictions: You may not reverse-engineer, decompile, or disassemble this software except as permitted by applicable law.

For information on how to obtain a valid commercial license, pricing, and support, please contact us at [email protected].

See the LICENSE file for the full legal text.