React Webcam Component

Common errors

• NotAllowedError: Permission denied

  cause The user denied webcam access permission or the page is not served over HTTPS.
  fix Prompt the user to grant camera permissions and ensure the application is running on a secure origin (HTTPS or localhost).

• TypeError: Cannot read properties of undefined (reading 'getScreenshot')

  cause Attempting to call `getScreenshot` on a `webcamRef.current` that is `null` or `undefined` because the Webcam component hasn't rendered or mounted yet.
  fix Ensure the `webcamRef.current` exists before calling `getScreenshot`. This often means checking `if (webcamRef.current)` before accessing its methods.

• MediaStreamError: Only secure origins are allowed.

  cause The browser's `getUserMedia` API was invoked from an insecure origin (HTTP instead of HTTPS).
  fix Serve your application over HTTPS. For local development, use `https://localhost`.

• Webcam showing blank screen

  cause This can be due to various reasons: permission denied, no camera detected, incorrect video constraints, or browser compatibility issues.
  fix Check browser console for `MediaStreamError` messages. Verify camera is connected and not in use by another application. Review `videoConstraints` for validity and ensure HTTPS is used. Implement `onUserMediaError` to debug specific errors.

Warnings

• breaking Accessing the webcam via `getUserMedia` (which react-webcam uses) is restricted to secure contexts (HTTPS or localhost). Browsers will throw a `NotAllowedError` or `SecurityError` if the page is loaded over HTTP.
  Fix: Ensure your application is served over HTTPS in production and development (e.g., using `https://localhost` or a tunneling service).
• gotcha The `getScreenshot` method should only be called once the webcam stream is active and the component's `ref` is populated. Calling it too early can lead to `null` or `undefined` issues, or an empty screenshot.
  Fix: Use React's `useRef` and conditionally call `getScreenshot` after the component has mounted and `onUserMedia` has fired, or within an event handler triggered by user interaction.
• gotcha Webcam access requires explicit user permission. If the user denies permission, `onUserMediaError` will be called with a `MediaStreamError`, and the webcam stream will not activate, resulting in a blank video area.
  Fix: Implement robust error handling with the `onUserMediaError` prop to inform the user about permission issues and guide them on how to grant access (e.g., checking browser settings).
• gotcha The `forceScreenshotSourceSize` prop, when true, forces `getScreenshot` to use the dimensions of the underlying video stream, potentially overriding `minScreenshotHeight`/`minScreenshotWidth` or dimensions passed directly to `getScreenshot`.
  Fix: Be mindful of this prop's interaction with other dimension-related settings for `getScreenshot` to avoid unexpected image sizes.

Install

• npm install react-webcam npm
• yarn add react-webcam yarn
• pnpm add react-webcam pnpm

Imports

• Webcam
  wrong:

  import { Webcam } from 'react-webcam';

  correct:

  import Webcam from 'react-webcam';

  The primary Webcam component is a default export.
• WebcamProps
  wrong:

  import { WebcamProps } from 'react-webcam';

  correct:

  import type { WebcamProps } from 'react-webcam';

  Use 'type' import for TypeScript interfaces to ensure they are stripped from runtime bundles.
• Webcam (CJS)
  wrong:

  const Webcam = require('react-webcam');

  correct:

  const Webcam = require('react-webcam').default;

  For CommonJS environments, explicitly access the '.default' property as it's an ESM default export.

Quickstart

Demonstrates how to integrate the Webcam component, configure video constraints, and capture a screenshot, handling potential errors.

import React, { useRef, useState, useCallback } from 'react';
import Webcam from 'react-webcam';

const videoConstraints = {
  width: 1280,
  height: 720,
  facingMode: 'user',
};

const WebcamCapture = () => {
  const webcamRef = useRef(null);
  const [imageSrc, setImageSrc] = useState(null);

  const capture = useCallback(() => {
    if (webcamRef.current) {
      const screenshot = webcamRef.current.getScreenshot();
      setImageSrc(screenshot);
      console.log('Screenshot captured:', screenshot ? 'Yes' : 'No');
    }
  }, [webcamRef]);

  return (
    <div className="webcam-container">
      <Webcam
        audio={false}
        ref={webcamRef}
        screenshotFormat="image/jpeg"
        width={640}
        height={360}
        videoConstraints={videoConstraints}
        onUserMediaError={(error) => console.error('Webcam error:', error)}
      />
      <button onClick={capture}>Capture photo</button>
      {imageSrc && (
        <div>
          <h3>Captured Image:</h3>
          <img src={imageSrc} alt="webcam-screenshot" />
        </div>
      )}
    </div>
  );
};

export default WebcamCapture;