React DropZone 📤

The CardScanDropZone component provides an alternative to camera-based scanning by offering a drag-and-drop file upload interface for insurance card processing. This component is perfect for desktop workflows where users have digital images of their insurance cards ready to upload.

Installation

$ npm i @cardscan.ai/insurance-cardscan-react
$ yarn add @cardscan.ai/insurance-cardscan-react

Usage

Import the component into your project:

import { CardScanDropZone } from "@cardscan.ai/insurance-cardscan-react";

Basic Example

import React from "react";
import { render } from "react-dom";
import { CardScanDropZone } from "@cardscan.ai/insurance-cardscan-react";

function onSuccess(card) {
  console.log("Card processed successfully:", card);
}

function onError(error) {
  console.error('Error occurred:', error);
}

// See Authentication on where to get this sessionToken
const sessionToken = 'JWT_TOKEN'

function App() {
  return (
    <div className="App">
      <div className="DropZoneContainer">
        <CardScanDropZone
          live={false}
          sessionToken={sessionToken}
          onSuccess={onSuccess}
          onError={onError}
          enableBackside={true}
          layout="side-by-side"
        />
      </div>
    </div>
  );
}

const rootElement = document.getElementById('root');
render(<App />, rootElement);

Compatibility

  • Node Versions: 14, 16, 18

  • React Versions: >=17.0.2, 18.2.0+

  • Webpack Versions: 4.x, 5.x

  • Babel Versions: 6.x, 7.x

Peer Dependencies

  • React: >=17.0.2

  • React-DOM: >=17.0.2

  • react-dropzone: ^14.0.0

Configuration

Available Props

<CardScanDropZone
  // Required
  live={false}
  sessionToken={token}
  onSuccess={onSuccess}

  // Recommended
  onCancel={onCancel}
  onError={onError}
  onProgress={onProgress}
  
  // Dropzone Options
  enableBackside={true}
  layout="side-by-side"
  
  // UI Customization
  messages={messages}
  frontDropIndicator={frontDropIndicator}
  backDropIndicator={backDropIndicator}
  successIndicator={successIndicator}
  errorIndicator={errorIndicator}
  
  // Styling
  widgetBackgroundColor="#ffffff"
  primaryColor="#007bff"
  progressBarColor="#28a745"
/>

Main Props

Prop
Required
Type
Description

live

true

Boolean

Toggle production or sandbox version. Default: false

sessionToken

true

String

JWT token for the current user, see Authentication

onSuccess

true

Function

Called on successful card processing. First argument is the processed card data.

onCancel

false

Function

Triggered when user cancels the upload process.

onError

false

Function

Called when an error occurs during upload or processing.

onProgress

false

Function

Progress updates during card processing.

enableBackside

false

Boolean

Enable uploading of both front and back card sides. Default: false

layout

false

String

Layout mode: "side-by-side" or "sequential". Default: "side-by-side"

Layout Options

The layout prop controls how the front and back upload zones are displayed:

Side-by-Side Layout

<CardScanDropZone
  layout="side-by-side"
  enableBackside={true}
  // ... other props
/>

Both drop zones are visible simultaneously, allowing users to see both upload areas at once.

Sequential Layout

<CardScanDropZone
  layout="sequential"
  enableBackside={true}
  // ... other props
/>

The back drop zone is hidden until the front card is successfully uploaded and processed.

File Requirements

The CardScanDropZone component enforces the following file requirements:

  • File Types: JPEG, PNG

  • File Size: Maximum 5MB per file

  • Image Quality: Clear, well-lit images for best OCR results

Upload Workflow

  1. Front Card Upload: User drags and drops or clicks to select the front card image

  2. File Validation: Component validates file type and size

  3. Upload & Processing: File is uploaded via secure S3 direct upload and processed

  4. Real-time Updates: WebSocket connection provides live processing status

  5. Back Card (Optional): If enableBackside is true, back card upload becomes available

  6. Completion: onSuccess callback is triggered with complete card data

UI Customization

Custom Messages

const customMessages = {
  frontDropTitle: "Upload Front of Insurance Card",
  frontDropSubtitle: "Drag and drop or click to select",
  backDropTitle: "Upload Back of Insurance Card", 
  backDropSubtitle: "Drag and drop or click to select",
  frontProcessingTitle: "Processing Front Card...",
  backProcessingTitle: "Processing Back Card...",
  uploadingTitle: "Uploading...",
  successTitle: "Upload Complete!",
  errorTitle: "Upload Failed",
  fileTooLargeError: "File size must be under 5MB",
  invalidFileTypeError: "Please upload a JPEG or PNG file"
};

<CardScanDropZone
  messages={customMessages}
  // ... other props
/>

Custom Components

Replace default UI elements with your own React components:

const CustomFrontIndicator = () => (
  <div className="custom-drop-indicator">
    <h3>📄 Drop Front Card Here</h3>
  </div>
);

const CustomSuccessIndicator = () => (
  <div className="custom-success">
    <h3>✅ Card Processed Successfully!</h3>
  </div>
);

<CardScanDropZone
  frontDropIndicator={<CustomFrontIndicator />}
  successIndicator={<CustomSuccessIndicator />}
  // ... other props
/>

CSS Styling

The component supports CSS custom properties for easy theming:

.cardscan-dropzone {
  --dropzone-bg-color: #f8f9fa;
  --dropzone-border-color: #dee2e6;
  --dropzone-text-color: #212529;
  --dropzone-primary-color: #007bff;
  --dropzone-success-color: #28a745;
  --dropzone-error-color: #dc3545;
  --dropzone-border-radius: 8px;
}

Or use the styling props:

<CardScanDropZone
  widgetBackgroundColor="#ffffff"
  primaryColor="#007bff"
  progressBarColor="#28a745"
  // ... other props
/>

State Management

The CardScanDropZone uses XState for robust state management with the following states:

  • Initial: Ready for front card upload

  • FrontUploading: Front card being uploaded

  • FrontProcessing: Front card being processed by ML pipeline

  • BackAvailable: Ready for back card upload (if enabled)

  • BackUploading: Back card being uploaded

  • BackProcessing: Back card being processed

  • Success: Both cards processed successfully

  • Error: Upload or processing failed

Callbacks

onSuccess Callback

const handleSuccess = (cardData) => {
  console.log('Processed card data:', cardData);
  // cardData contains extracted information from both front and back
};

<CardScanDropZone
  onSuccess={handleSuccess}
  // ... other props
/>

onError Callback

const handleError = (error) => {
  console.error('Upload error:', error);
  // Error object contains type, message, and code
};

<CardScanDropZone
  onError={handleError}
  // ... other props
/>

onProgress Callback

const handleProgress = (progress) => {
  console.log(`Processing: ${progress.cardSide} - State: ${progress.state}`);
};

<CardScanDropZone
  onProgress={handleProgress}
  // ... other props
/>

Error Handling

The component handles various error scenarios:

Error Type
Description
User Action

FileTooLarge

File exceeds 5MB limit

Select a smaller file

InvalidFileType

File is not JPEG/PNG

Select a valid image file

UploadFailed

Network or server error

Try uploading again

ProcessingFailed

ML processing failed

Try with a clearer image

AuthenticationError

Invalid session token

Refresh authentication

Integration with CardScanView

The DropZone component can be used alongside the camera-based CardScanView:

const [uploadMethod, setUploadMethod] = useState('camera');

return (
  <div>
    <div className="method-selector">
      <button onClick={() => setUploadMethod('camera')}>
        📸 Use Camera
      </button>
      <button onClick={() => setUploadMethod('upload')}>
        📤 Upload Files
      </button>
    </div>
    
    {uploadMethod === 'camera' ? (
      <CardScanView
        sessionToken={sessionToken}
        onSuccess={onSuccess}
        onError={onError}
      />
    ) : (
      <CardScanDropZone
        sessionToken={sessionToken}
        onSuccess={onSuccess}
        onError={onError}
        enableBackside={true}
      />
    )}
  </div>
);

Best Practices

  1. File Validation: Always handle file validation errors gracefully

  2. User Feedback: Provide clear visual feedback during upload and processing

  3. Error Recovery: Allow users to retry failed uploads easily

  4. Accessibility: Ensure keyboard navigation and screen reader support

  5. Mobile Considerations: Consider using CardScanView for mobile devices where camera access is preferred

Troubleshooting

Common Issues

Files not uploading:

  • Check session token validity

  • Verify file size is under 5MB

  • Ensure file format is JPEG or PNG

Processing takes too long:

  • Images with poor quality may require more processing time

  • Consider implementing a timeout mechanism

Styling not applying:

  • Ensure CSS custom properties have sufficient specificity

  • Check for conflicting styles from other components

Need Help? Contact [email protected] for assistance with the CardScanDropZone component.

PreviousReact ⚛NextReact Native ⚛

Last updated

Was this helpful?