react-native-signature-canvas

While webviewProps allows for extensive customization, it cannot override the Core Props required for the signature pad to function. These protected props take precedence over anything defined in webviewProps:

• ref: Internal WebView reference
• source: HTML content for signature pad
• onMessage: Message handler for signature events
• onError: Error handler
• onLoadEnd: Load completion handler
• onLoadStart: Load start handler
• onLoadProgress: Load progress handler
• javaScriptEnabled: Must be true for the signature pad to work
• useWebKit: Uses modern WebKit engine

In newer versions, individual WebView-related props should be consolidated into the webviewProps object. While old individual props are supported for backward compatibility, the new pattern is preferred.

Before:

<SignatureCanvas
  androidLayerType="hardware"
  androidHardwareAccelerationDisabled={false}
/>

After:

<SignatureCanvas
  webviewProps={{
    androidLayerType: "hardware",
    androidHardwareAccelerationDisabled: false,
  }}
/>

To use the signature canvas, install the main package. If you are using a React Native CLI project (not Expo), you must also install react-native-webview and run pod install for iOS.

# Install the package
npm install react-native-signature-canvas

# For React Native CLI projects, also install WebView
npm install react-native-webview
cd ios && pod install # iOS only

Before building the app, you must start Metro, the JavaScript build tool for React Native. Run this command from the root of your project:

# Using npm
npm start

# OR using Yarn
yarn start

Version 5.x is fully backward compatible with v4.x. It introduces two key new features:

1. Enhanced error handling: Use the onError callback to catch and handle errors.
2. WebView customization: Use the webviewProps prop to pass configuration directly to the underlying WebView.

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

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

For iOS, you must first install CocoaPods dependencies.

1. If you are setting up for the first time, install CocoaPods via Ruby bundler:

   bundle install

2. Install or update native dependencies:

   bundle exec pod install

3. Build and run the app:

# Using npm
npm run ios

# OR using Yarn
yarn ios

For older versions of React Native (< 0.60.0) or Expo SDK (< 33.0.0), install version 1.4.2 specifically.

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

Depending on your device requirements, you can use different webviewProps configurations to balance performance and memory usage.

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

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

While development is powered by Fast Refresh, you can perform a full reload to reset the app state:

• Android: Press the <kbd>R</kbd> key twice or select "Reload" from the Dev Menu (accessed via <kbd>Ctrl</kbd> + <kbd>M</kbd> on Windows/Linux or <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> on macOS).
• iOS: Press <kbd>R</kbd> in the iOS Simulator.

Use the onError prop to catch errors. While the component automatically attempts to recover from recoverable errors, you can use this callback to log errors or update your UI.

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>
)}

With Metro running, open a new terminal window and run the following command to build and launch the app on an Android emulator or connected device:

# Using npm
npm run android

# OR using Yarn
yarn android

You can pass configuration directly to the underlying WebView using the webviewProps prop. This is useful for optimizing performance or security.

### High Performance Setup
```jsx
<SignatureCanvas
  webviewProps={{
    cacheEnabled: true,
    androidLayerType: "hardware",
    androidHardwareAccelerationDisabled: false,
  }}
/>

Low Memory Setup

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

Security Focused Setup

<SignatureCanvas
  webviewProps={{
    allowFileAccess: false,
    allowFileAccessFromFileURLs: false,
    mixedContentMode: "never",
    allowsLinkPreview: false,
  }}
/>