@melihbirim/signature-pad

A lightweight React component for collecting signatures with draw and type modes. Zero dependencies beyond React.

Installation

npm install @melihbirim/signature-pad

Requires React 18+.

Quick Start

import { SignaturePad } from '@melihbirim/signature-pad';
import { useState } from 'react';

function App() {
  const [signature, setSignature] = useState<string>();

  const handleUpload = async (file: File): Promise<string> => {
    const formData = new FormData();
    formData.append('file', file);
    const response = await fetch('/api/upload', { method: 'POST', body: formData });
    const data = await response.json();
    return data.path;
  };

  return (
    <SignaturePad
      value={signature}
      onChange={setSignature}
      onUpload={handleUpload}
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | string \| undefined | - | Current signature path/URL | | onChange | (value?: string) => void | - | Called when signature changes | | onUpload | (file: File) => Promise<string> | Required | Upload function, returns path/URL | | width | number | 600 | Canvas width in pixels | | height | number | 200 | Canvas height in pixels | | getFullUrl | (path: string) => string | (p) => p | Convert path to full URL for display | | watermark | WatermarkConfig | - | Add metadata overlay (IP, timestamp, timezone) | | typedFont | string | "Brush Script MT", cursive | Font for typed signatures | | labels | LabelsConfig | - | Customize button/label text | | styles | StylesConfig | - | Custom CSS styles | | headless | boolean | false | Render only canvas, no UI | | renderToolbar | (props) => ReactNode | - | Custom toolbar component | | renderSignature | (props) => ReactNode | - | Custom signature display | | onUploadStart | () => void | - | Called before upload starts | | onUploadEnd | (path: string) => void | - | Called after upload succeeds | | onUploadError | (error: Error) => void | - | Called on upload failure | | onMessage | (type, text) => void | - | Custom message handler |

Imperative API

Access methods via ref:

const ref = useRef<SignaturePadRef>(null);

<SignaturePad ref={ref} onUpload={handleUpload} />

// Methods
ref.current?.clear();                    // Clear canvas
ref.current?.uploadSignature();          // Trigger upload
ref.current?.setMode('draw' | 'type');   // Switch modes
ref.current?.getCanvas();                // Get canvas element

Upload Examples

AWS S3 with Presigned URL

const handleUpload = async (file: File): Promise<string> => {
  const { data } = await axios.post('/api/s3/presigned-url', {
    filename: file.name,
    contentType: file.type,
  });
  await axios.put(data.uploadUrl, file, {
    headers: { 'Content-Type': file.type },
  });
  return data.key;
};

Direct Server Upload

const handleUpload = async (file: File): Promise<string> => {
  const formData = new FormData();
  formData.append('signature', file);
  const response = await fetch('/api/signatures', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
    body: formData,
  });
  const { filePath } = await response.json();
  return filePath;
};

Customization

Custom Labels

<SignaturePad
  onUpload={handleUpload}
  labels={{
    draw: 'Draw',
    type: 'Type',
    clear: 'Clear',
    useSignature: 'Save',
    removeSignature: 'Remove',
    typePlaceholder: 'Your name',
  }}
/>

Custom Styles

<SignaturePad
  onUpload={handleUpload}
  styles={{
    container: { border: '2px solid #000' },
    canvas: { borderRadius: 8 },
    preview: { maxWidth: 400 },
  }}
/>

Watermark

<SignaturePad
  onUpload={handleUpload}
  watermark={{
    enabled: true,
    ipAddress: '192.168.1.1',
    timezone: 'America/New_York',
    fontSize: 10,
    color: '#666',
  }}
/>

Headless Mode

<SignaturePad
  value={signature}
  onChange={setSignature}
  onUpload={handleUpload}
  headless={true}
  renderToolbar={({ mode, onModeChange, onClear, onUpload }) => (
    <div>
      <button onClick={() => onModeChange('draw')}>Draw</button>
      <button onClick={() => onModeChange('type')}>Type</button>
      <button onClick={onClear}>Clear</button>
      <button onClick={onUpload}>Save</button>
    </div>
  )}
/>

Upload State Tracking

function App() {
  const [uploading, setUploading] = useState(false);

  return (
    <SignaturePad
      onUpload={handleUpload}
      onUploadStart={() => setUploading(true)}
      onUploadEnd={() => setUploading(false)}
      onUploadError={(err) => {
        setUploading(false);
        console.error(err);
      }}
    />
  );
}

Features

• Draw with mouse or touch (smooth Bezier curves)
• Type signatures with custom fonts
• DPI-aware rendering for Retina displays
• Imperative API via ref
• Upload lifecycle hooks
• Watermark support
• Headless mode for custom UI
• TypeScript support
• Zero dependencies

License

MIT