パッケージの詳細

react-native-signature-canvas

YanYuanFE161.7kMIT5.0.1

A performant, customizable React Native signature canvas with advanced error handling, WebView optimization, and TypeScript support for iOS, Android, and Expo

react-native, react component, ios, android

readme

React Native Signature Canvas

npm GitHub last commit runs with expo

A React Native component for capturing signatures or drawing on a canvas with a smooth, native feel. Works on iOS, Android, and Expo.

Features

  • Cross-platform support (iOS, Android, Expo)
  • Smooth, responsive drawing experience with optimized performance
  • Customizable pen color, size, and background
  • Support for background and overlay images
  • Export signatures as PNG, JPEG, or SVG
  • Undo/redo functionality
  • Drawing and erasing modes
  • Full TypeScript support with enhanced type definitions
  • 🆕 Advanced error handling with automatic recovery
  • 🆕 Performance monitoring and optimization
  • 🆕 Flexible WebView customization via webviewProps
  • 🆕 Enhanced security with configurable restrictions
  • 🆕 Memory management and leak prevention

Installation

For React Native ≥ 0.60.0 or Expo SDK ≥ 35.0.0

yarn add react-native-signature-canvas

or

npm install --save react-native-signature-canvas

This package depends on react-native-webview. If you're using React Native CLI (not Expo), you'll need to install react-native-webview separately:

yarn add react-native-webview
cd ios && pod install

For React Native < 0.60.0 or Expo SDK < 33.0.0

npm install --save react-native-signature-canvas@1.4.2

Basic Usage

import React, { useRef, useState } from 'react';
import { StyleSheet, View, Image } from 'react-native';
import SignatureCanvas from 'react-native-signature-canvas';

const SignatureScreen = () => {
  const [signature, setSignature] = useState(null);
  const [isLoading, setIsLoading] = useState(false);
  const ref = useRef();

  const handleSignature = (signature) => {
    console.log('Signature captured:', signature);
    setSignature(signature);
    setIsLoading(false);
  };

  const handleEmpty = () => {
    console.log('Signature is empty');
    setIsLoading(false);
  };

  const handleClear = () => {
    console.log('Signature cleared');
    setSignature(null);
  };

  const handleError = (error) => {
    console.error('Signature pad error:', error);
    setIsLoading(false);
  };

  const handleEnd = () => {
    setIsLoading(true);
    ref.current?.readSignature();
  };

  return (
    <View style={styles.container}>
      <View style={styles.preview}>
        {signature && (
          <Image
            resizeMode="contain"
            style={{ width: 335, height: 114 }}
            source={{ uri: signature }}
          />
        )}
      </View>
      <SignatureCanvas
        ref={ref}
        onEnd={handleEnd}
        onOK={handleSignature}
        onEmpty={handleEmpty}
        onClear={handleClear}
        onError={handleError}
        autoClear={true}
        descriptionText="Sign here"
        clearText="Clear"
        confirmText={isLoading ? "Processing..." : "Save"}
        penColor="#000000"
        backgroundColor="rgba(255,255,255,0)"
        webviewProps={{
          // Custom WebView optimization
          cacheEnabled: true,
          androidLayerType: "hardware",
        }}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  preview: {
    width: 335,
    height: 114,
    backgroundColor: '#F8F8F8',
    justifyContent: 'center',
    alignItems: 'center',
    marginTop: 15,
  },
});

export default SignatureScreen;

Props

Prop Type Default Description
androidHardwareAccelerationDisabled boolean false Disable hardware acceleration on Android
autoClear boolean false Auto clear signature after clicking the Confirm button
backgroundColor string rgba(255,255,255,0) Background color of the canvas
bgHeight number 0 Height of the background image
bgWidth number 0 Width of the background image
bgSrc string null Background image source URI
clearText string Clear Clear button text
confirmText string Confirm Save button text
customHtml (injectedJavaScript: string) => string null Custom HTML template for the canvas
dataURL string "" Base64 string to draw saved signature
descriptionText string Sign above Description text for signature
dotSize number null Radius of a single dot
imageType string image/png Image type for export (image/png, image/jpeg, image/svg+xml)
minWidth number 0.5 Minimum width of a line
maxWidth number 2.5 Maximum width of a line
nestedScrollEnabled boolean false Enable nested scrolling for use inside a ScrollView
showsVerticalScrollIndicator boolean true Show vertical scroll indicator in WebView
onOK function - Callback after saving non-empty signature
onEmpty function - Callback after trying to save an empty signature
onClear function - Callback after clearing the signature
onGetData function - Callback when getData() is called
onBegin function - Callback when a new stroke is started
onEnd function - Callback when the stroke has ended
onLoadEnd function - Callback when the WebView canvas load ended
onUndo function - Callback when undo() is called
onRedo function - Callback when redo() is called
onDraw function - Callback when drawing is enabled
onErase function - Callback when erasing is enabled
onChangePenColor function - Callback after changing the pen color
onChangePenSize function - Callback after changing the pen size
overlayHeight number 0 Height of the overlay image
overlayWidth number 0 Width of the overlay image
overlaySrc string null Overlay image source URI (must be PNG with transparent background)
penColor string black Color of the pen
rotated boolean false Rotate signature pad 90 degrees
style object - Style of the wrapper view
scrollable boolean false Enable scrolling in the signature pad
trimWhitespace boolean false Trim image whitespace
webStyle string - WebView style to override default style
webviewContainerStyle object - Style for the WebView container
androidLayerType `none\ software\ hardware` hardware Sets the Android WebView layer type
onError function - Callback when an error occurs
webviewProps object {} Additional props to pass to the underlying WebView

Methods

Access these methods using a ref to the SignatureCanvas component.

Method Description
clearSignature() Clear the current signature
changePenColor(color) Change pen color
changePenSize(minW, maxW) Change pen size
draw() Enable drawing mode
erase() Enable erasing mode
getData() Triggers the onGetData callback with signature data
readSignature() Read the current signature and trigger callbacks
undo() Undo last stroke
redo() Redo last stroke

WebView Customization (New!)

The webviewProps parameter allows you to customize the underlying WebView behavior while maintaining signature functionality:

<SignatureCanvas
  // ... other props
  webviewProps={{
    // Performance optimization
    cacheEnabled: true,
    androidLayerType: "hardware",
    androidHardwareAccelerationDisabled: false,

    // Security settings
    allowFileAccess: false,
    allowFileAccessFromFileURLs: false,
    mixedContentMode: "never",

    // UI customization
    decelerationRate: 'fast',
    bounces: false,

    // Any other WebView props...
  }}
/>

Performance Optimization Examples

// High-performance mode
<SignatureCanvas
  webviewProps={{
    cacheEnabled: true,
    androidLayerType: "hardware",
    androidHardwareAccelerationDisabled: false,
  }}
/>

// Low-memory mode
<SignatureCanvas
  webviewProps={{
    cacheEnabled: false,
    androidLayerType: "software",
    androidHardwareAccelerationDisabled: true,
  }}
/>

Error Handling (Enhanced!)

const [error, setError] = useState(null);

const handleError = (error) => {
  console.error('Signature error:', error);
  setError(error.message);
  // Error recovery is automatic, but you can handle it here
};

<SignatureCanvas
  onError={handleError}
  // Component automatically retries on recoverable errors
/>

{error && (
  <Text style={{ color: 'red' }}>Error: {error}</Text>
)}

Advanced Usage

Using a Background Image

const imgWidth = 300;
const imgHeight = 200;
const style = `.m-signature-pad {box-shadow: none; border: none; } 
              .m-signature-pad--body {border: none;}
              .m-signature-pad--footer {display: none; margin: 0px;}
              body,html {
              width: ${imgWidth}px; height: ${imgHeight}px;}`;

<View style={{ width: imgWidth, height: imgHeight }}>
  <SignatureCanvas
    ref={ref}
    bgSrc="https://example.com/background.jpg"
    bgWidth={imgWidth}
    bgHeight={imgHeight}
    webStyle={style}
    onOK={handleSignature}
  />
</View>

Using an Overlay Image

const imgWidth = 256;
const imgHeight = 256;
const style = `.m-signature-pad {box-shadow: none; border: none; } 
              .m-signature-pad--body {border: none;}
              .m-signature-pad--footer {display: none; margin: 0px;}
              body,html {
              width: ${imgWidth}px; height: ${imgHeight}px;}`;

<View style={{ width: imgWidth, height: imgHeight }}>
  <SignatureCanvas
    ref={ref}
    overlaySrc="https://example.com/overlay.png" // Must be PNG with transparent background
    overlayWidth={imgWidth}
    overlayHeight={imgHeight}
    webStyle={style}
    onOK={handleSignature}
  />
</View>

Using in a Modal

import React, { useState, useRef } from 'react';
import { StyleSheet, View, TouchableOpacity, Modal, Text } from 'react-native';
import SignatureCanvas from 'react-native-signature-canvas';

const SignatureModal = ({ onSignature }) => {
  const [show, setShow] = useState(false);
  const ref = useRef();

  const handleSignature = (signature) => {
    onSignature(signature);
    setShow(false);
  };

  return (
    <View>
      <TouchableOpacity onPress={() => setShow(true)}>
        <Text>Open Signature Pad</Text>
      </TouchableOpacity>

      {show && (
        <Modal>
          <SignatureCanvas
            ref={ref}
            onOK={handleSignature}
            onEmpty={() => console.log('Empty')}
            descriptionText="Sign here"
            penColor="rgba(255,117,2,1)"
          />
        </Modal>
      )}
    </View>
  );
};

Scrollable Signature Canvas

import React, { useRef, useState } from 'react';
import { View, StyleSheet, ScrollView } from 'react-native';
import SignatureCanvas from 'react-native-signature-canvas';

const ScrollableSignature = () => {
  const [scrollEnabled, setScrollEnabled] = useState(true);
  const signatureRef = useRef(null);

  return (
    <ScrollView scrollEnabled={scrollEnabled}>
      <View style={styles.container}>
        <SignatureCanvas
          ref={signatureRef}
          style={styles.canvas}
          onBegin={() => setScrollEnabled(false)}
          onEnd={() => setScrollEnabled(true)}
        />
      </View>
    </ScrollView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
  },
  canvas: {
    width: '90%',
    height: 300,
    borderWidth: 1,
    borderColor: '#000',
  },
});

Performance & Reliability

Automatic Error Recovery

  • Smart retry logic with exponential backoff
  • Circuit breaker pattern to prevent cascading failures
  • Memory leak prevention with automatic cleanup
  • Performance monitoring with automatic optimization

Performance Features

  • Debounced resize handling for smooth interaction
  • Memory pressure detection with adaptive optimization
  • Optimized rendering with reduced re-renders
  • Device-specific optimization based on hardware capabilities

Security Enhancements

  • Configurable WebView security via webviewProps
  • Input validation for all methods and callbacks
  • XSS protection with content security policies
  • File access restrictions by default

Migration Guide

From v4.6.x to v4.7.x

This version is fully backward compatible. New features:

// NEW: Enhanced error handling
<SignatureCanvas
  onError={(error) => console.error(error)} // New callback
/>

// NEW: WebView customization
<SignatureCanvas
  webviewProps={{ // New prop
    cacheEnabled: false,
    androidLayerType: "software"
  }}
/>

Troubleshooting

Common Issues

Issue: Signature pad not loading

// Solution: Add error handling and check WebView props
<SignatureCanvas
  onError={(error) => console.log('Error:', error)}
  onLoadEnd={() => console.log('Loaded successfully')}
  webviewProps={{
    startInLoadingState: true,
    renderLoading: () => <ActivityIndicator />
  }}
/>

Issue: Poor performance on older devices

// Solution: Use low-performance mode
<SignatureCanvas
  webviewProps={{
    androidLayerType: "software",
    androidHardwareAccelerationDisabled: true,
    cacheEnabled: false
  }}
/>

Issue: Memory issues

// Solution: The component now handles this automatically
// But you can customize via webviewProps if needed
<SignatureCanvas
  webviewProps={{
    cacheEnabled: false, // Reduce memory usage
    androidLayerType: "software" // Use software rendering
  }}
/>

API Reference

For detailed API documentation, see:

Core Technology

This component is built on:

  • signature_pad.js for the core signature functionality
  • React Native WebView for cross-platform rendering
  • Enhanced with performance monitoring and error recovery systems

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to help improve this component.

Development Setup

# Clone the repository
git clone https://github.com/YanYuanFE/react-native-signature-canvas.git

# Install dependencies
cd react-native-signature-canvas
npm install

# Run example apps
cd example/expo-app
npm install && npm start

Changelog

v4.7.x (Latest)

  • 🆕 Added webviewProps for WebView customization
  • 🆕 Enhanced error handling with automatic recovery
  • 🆕 Performance monitoring and optimization
  • 🆕 Memory leak prevention
  • 🆕 Improved TypeScript definitions
  • 🔧 Fixed global variable pollution in WebView JavaScript
  • 🔧 Added input validation for all methods
  • ⚡ Optimized rendering performance

View full changelog

License

MIT License - see LICENSE file for details.

Buy Me a Coffee ☕

If you find this project helpful, consider supporting its development with cryptocurrency donations:

Cryptocurrency Donations

Currency Address QR Code
Bitcoin (BTC) bc1phyz9agr0m9l2w9pd8w85w4da2jt3wl4cre7vv0qq4uesm3fv00pscu96tux BTC QR
Ethereum (ETH) 0xf5dfe16b1e64e8e3a92063fb2922447e13b48945 ETH QR
Solana (SOL) 3VuhyeTj3hMSrmzq7NctHkgFxvJrmtAUQTzagEBEu3Vm SOL QR

Other Ways to Support

  • ⭐ Star this repository
  • 🐛 Report bugs and issues
  • 💡 Suggest new features
  • 🤝 Contribute code improvements
  • 📢 Share this project with others

Your support helps maintain and improve this open-source project. Thank you! 🙏


Made with ❤️ for the React Native community

更新履歴

5.0.0 (2025-06-28)

Bug Fixes

  • add originWhitelist prop (068c646)
  • backgorund color to transparent and loader color to transparent (3001d4e)
  • fix canvas not display for android api 28 (835669b)

Features

  • add onLoadEnd prop (49a8664)
  • add showsVerticalScrollIndicator prop (a4d64c5)
  • export SignatureViewProps (8f0c321)

4.5.1 (2023-05-04)

Bug Fixes

Features

  • update rn latest example (f9a568f)

4.3.0 (2021-08-11)

4.2.1 (2021-08-04)

Bug Fixes

4.2.0 (2021-07-24)

4.1.0 (2021-07-14)

4.0.0 (2021-04-15)

Bug Fixes

Features

3.6.0 (2021-03-02)

3.5.2 (2021-02-26)

3.5.1 (2021-02-18)

Bug Fixes

3.3.0 (2020-11-13)

Bug Fixes

Features

3.2.0 (2020-10-07)

Bug Fixes

Features

  • minSize and dotSize prop (d6804ab)

3.1.0 (2020-07-31)

Bug Fixes

Features