🚀 Features

• 📹 Embed a live camera feed directly into your app.
• 📸 Capture photos or frames from the camera preview.
• 🔍 Barcode detection support.
• 📱 Virtual device support for automatic lens selection based on zoom level and focus (iOS only).
• 🔦 Control zoom, flash and torch modes programmatically.
• ⚡ High performance with optimized native implementations.
• 🎯 Simple to use with a clean and intuitive API.
• 🌐 Works seamlessly on iOS, Android, and Web.

🪧 Demo

📦 Installation

Install the plugin using npm:

npm install capacitor-camera-view
npx cap sync

Platform Configuration

iOS

Add the following keys to your app's Info.plist file:

<key>NSCameraUsageDescription</key>
<string>To capture photos and videos</string>

Android

The CAMERA permission is automatically added by Capacitor. Ensure your AndroidManifest.xml includes it if needed for specific configurations:

<uses-permission android:name="android.permission.CAMERA" />

▶️ Basic Usage

import { CameraView } from 'capacitor-camera-view';

// Start the camera preview
const startCamera = async () => {
  try {
    await CameraView.start();
    console.log('Camera started');
    // Add the CSS class to make the WebView transparent
    document.body.classList.add('camera-running');
  } catch (e) {
    console.error('Error starting camera:', e);
  }
};

// Stop the camera preview
const stopCamera = async () => {
  try {
    document.body.classList.remove('camera-running');
    await CameraView.stop();
    console.log('Camera stopped');
  } catch (e) {
    console.error('Error stopping camera:', e);
  }
};

// Capture a photo
const capturePhoto = async () => {
  try {
    const result = await CameraView.capture();
    console.log('Photo captured:', result.photo); // Base64 encoded string
  } catch (e) {
    console.error('Error capturing photo:', e);
  }
};

⚠️ Make the WebView transparent when starting the camera view

To display the camera view through your app, you need to ensure that the WebView is made transparent. For Ionic applications, this can be done by adding the following styles to your global CSS file and applying the respective class to the body element as soon as you start the camera (see example app on how to do this in Angular):

body.camera-running {
  visibility: hidden;
  --background: transparent;
  --ion-background-color: transparent;
}

.camera-modal {
  visibility: visible;
}

📸 Virtual Camera Support for iOS

On supported iPhone models (like the Pro series), this plugin can utilize the virtual triple camera. This feature combines the ultra-wide, wide, and telephoto cameras into a single virtual device. iOS will then automatically switch between the physical cameras based on factors like zoom level and lighting conditions, providing seamless transitions and optimal image quality across a wider zoom range. You can enable this by setting the useTripleCameraIfAvailable option to true when calling start().

Pros:

• Smoother zooming experience across different focal lengths.
• Automatic selection of the best lens for the current scene and zoom factor.

Cons:

• Slightly higher resource usage compared to using a single physical camera (the camera view will take a little longer until initialized).
• Only available on specific iPhone models with triple camera systems.

For more details on the underlying technology, refer to Apple's documentation on AVCaptureDevice.builtInTripleCamera.

Alternatively, you can specify the preferredCameraDeviceTypes option in the CameraSessionConfiguration to prioritize specific virtual cameras, such as the dual camera system. While this provides similar functionality, the useTripleCameraIfAvailable option offers the advantage of a smoother transition during camera initialization and lens switching (blurred overlay).

🔍 Barcode Detection

This plugin supports real-time barcode detection directly from the live camera feed.

How it works:

• iOS: Utilizes the native AVCaptureMetadataOutput.
• Android: Utilizes Google's ML Kit Barcode Scanning.
• Web: Uses the Barcode Detection API where available in the browser.

[!NOTE] Web Support: The Barcode Detection API is not supported in all browsers (e.g., Windows browsers). For full browser compatibility, consider using a polyfill such as @undecaf/barcode-detector-polyfill or barcode-detector.

Enabling Barcode Detection: To enable this feature, set the enableBarcodeDetection option to true when calling the start() method:

await CameraView.start({ enableBarcodeDetection: true });

Listening for Barcodes: Once enabled, you can listen for the barcodeDetected event to receive data about scanned barcodes:

import { CameraView } from 'capacitor-camera-view';

CameraView.addListener('barcodeDetected', (data) => {
  console.log('Barcode detected:', data.value, data.type);
  // Handle the detected barcode data (e.g., display it, navigate)
});

See the BarcodeDetectionData interface for details on the event payload.

🧪 Example App

To see the plugin in action, check out the example app in the example-app folder. The app demonstrates how to integrate and use the Capacitor Camera View plugin in an Ionic Angular project.

Semantic Release

This project uses semantic-release for automated versioning and changelog generation based on conventional commits.

Conventional Commits

Follow the Conventional Commits specification for your commit messages. Example:

feat(camera): add autofocus support
fix(android): resolve crash on startup
chore: update dependencies

Resources

• semantic-release documentation
• Conventional Commits

API

• start(...)
• stop()
• isRunning()
• capture(...)
• captureSample(...)
• flipCamera()
• getAvailableDevices()
• getZoom()
• setZoom(...)
• getFlashMode()
• getSupportedFlashModes()
• setFlashMode(...)
• isTorchAvailable()
• getTorchMode()
• setTorchMode(...)
• checkPermissions()
• requestPermissions()
• addListener('barcodeDetected', ...)
• removeAllListeners(...)
• Interfaces
• Type Aliases

Main plugin interface for Capacitor Camera View functionality.

start(...)

start(options?: CameraSessionConfiguration | undefined) => Promise<void>

Start the camera view with optional configuration.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------------------- | ---------------------------------------------- | | options | CameraSessionConfiguration | - Configuration options for the camera session |

Since: 1.0.0

stop()

stop() => Promise<void>

Stop the camera view and release resources.

Since: 1.0.0

isRunning()

isRunning() => Promise<IsRunningResponse>

Check if the camera view is currently running.

Returns: Promise<IsRunningResponse>

Since: 1.0.0

capture(...)

capture<T extends CaptureOptions>(options: T) => Promise<CaptureResponse<T>>

Capture a photo using the current camera configuration.

| Param | Type | Description | | ------------- | -------------- | ------------------------------- | | options | T | - Capture configuration options |

Returns: Promise<CaptureResponse<T>>

Since: 1.0.0

captureSample(...)

captureSample<T extends CaptureOptions>(options: T) => Promise<CaptureResponse<T>>

Captures a frame from the current camera preview without using the full camera capture pipeline.

Unlike capture() which may trigger hardware-level photo capture on native platforms, this method quickly samples the current video stream. This is suitable computer vision or simple snapshots where high fidelity is not required.

On web this method does exactly the same as capture() as it only captures a frame from the video stream because unfortunately ImageCapture API is not yet well supported on the web.

| Param | Type | Description | | ------------- | -------------- | ------------------------------- | | options | T | - Capture configuration options |

Returns: Promise<CaptureResponse<T>>

Since: 1.0.0

flipCamera()

flipCamera() => Promise<void>

Switch between front and back camera.

Since: 1.0.0

getAvailableDevices()

getAvailableDevices() => Promise<GetAvailableDevicesResponse>

Get available camera devices for capturing photos.

Returns: Promise<GetAvailableDevicesResponse>

Since: 1.0.0

getZoom()

getZoom() => Promise<GetZoomResponse>

Get current zoom level information and available range.

Returns: Promise<GetZoomResponse>

Since: 1.0.0

setZoom(...)

setZoom(options: { level: number; ramp?: boolean; }) => Promise<void>

Set the camera zoom level.

| Param | Type | Description | | ------------- | ----------------------------------------------- | ---------------------------- | | options | { level: number; ramp?: boolean; } | - Zoom configuration options |

Since: 1.0.0

getFlashMode()

getFlashMode() => Promise<GetFlashModeResponse>

Get current flash mode setting.

Returns: Promise<GetFlashModeResponse>

Since: 1.0.0

getSupportedFlashModes()

getSupportedFlashModes() => Promise<GetSupportedFlashModesResponse>

Get supported flash modes for the current camera.

Returns: Promise<GetSupportedFlashModesResponse>

Since: 1.0.0

setFlashMode(...)

setFlashMode(options: { mode: FlashMode; }) => Promise<void>

Set the camera flash mode.

| Param | Type | Description | | ------------- | ---------------------------------------------------------- | ---------------------------------- | | options | { mode: FlashMode; } | - Flash mode configuration options |

Since: 1.0.0

isTorchAvailable()

isTorchAvailable() => Promise<IsTorchAvailableResponse>

Check if the device supports torch (flashlight) functionality.

Returns: Promise<IsTorchAvailableResponse>

Since: 1.2.0

getTorchMode()

getTorchMode() => Promise<GetTorchModeResponse>

Get the current torch (flashlight) state.

Returns: Promise<GetTorchModeResponse>

Since: 1.2.0

setTorchMode(...)

setTorchMode(options: { enabled: boolean; level?: number; }) => Promise<void>

Set the torch (flashlight) mode and intensity.

| Param | Type | Description | | ------------- | -------------------------------------------------- | ----------------------------- | | options | { enabled: boolean; level?: number; } | - Torch configuration options |

Since: 1.2.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check camera permission status without requesting permissions.

Returns: Promise<PermissionStatus>

Since: 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request camera permission from the user.

Returns: Promise<PermissionStatus>

Since: 1.0.0

addListener('barcodeDetected', ...)

addListener(eventName: 'barcodeDetected', listenerFunc: (data: BarcodeDetectionData) => void) => Promise<PluginListenerHandle>

Listen for barcode detection events. This event is emitted when a barcode is detected in the camera preview.

| Param | Type | Description | | ------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | eventName | 'barcodeDetected' | - The name of the event to listen for ('barcodeDetected') | | listenerFunc | (data: BarcodeDetectionData) => void | - The callback function to execute when a barcode is detected |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners(...)

removeAllListeners(eventName?: string | undefined) => Promise<void>

Remove all listeners for this plugin.

| Param | Type | Description | | --------------- | ------------------- | --------------------------------------------- | | eventName | string | - Optional event name to remove listeners for |

Since: 1.0.0

Interfaces

CameraSessionConfiguration

Configuration options for starting a camera session.

| Prop | Type | Description | Default | | -------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | enableBarcodeDetection | boolean | Enables the barcode detection functionality | false | | position | CameraPosition | Position of the camera to use | 'back' | | deviceId | string | Specific device ID of the camera to use If provided, takes precedence over position | | | useTripleCameraIfAvailable | boolean | Whether to use the triple camera if available (iPhone Pro models only) | false | | preferredCameraDeviceTypes | CameraDeviceType[] | Ordered list of preferred camera device types to use (iOS only). The system will attempt to use the first available camera type in the list. If position is also provided, the system will use the first available camera type that matches the position and is in the list. This will fallback to the default camera type if none of the preferred types are available. | undefined - system will decide based on position/deviceId | | zoomFactor | number | The initial zoom factor to use | 1.0 | | containerElementId | string | Optional HTML ID of the container element where the camera view should be rendered. If not provided, the camera view will be appended to the document body. Web only. | |

IsRunningResponse

Response for checking if the camera view is running.

| Prop | Type | Description | | --------------- | -------------------- | ------------------------------------------------------------ | | isRunning | boolean | Indicates if the camera view is currently active and running |

CaptureOptions

Configuration options for capturing photos and samples.

| Prop | Type | Description | Default | Since | | ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | quality | number | The JPEG quality of the captured photo/sample on a scale of 0-100 | | 1.1.0 | | saveToFile | boolean | If true, saves to a temporary file and returns the web path instead of base64. The web path can be used to set the src attribute of an image for efficient loading and rendering. This reduces the data that needs to be transferred over the bridge, which can improve performance especially for high-resolution images. | false | 1.1.0 |

GetAvailableDevicesResponse

Response for getting available camera devices.

| Prop | Type | Description | | ------------- | --------------------------- | ------------------------------------ | | devices | CameraDevice[] | An array of available camera devices |

CameraDevice

Represents a physical camera device on the device.

| Prop | Type | Description | | ---------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- | | id | string | The unique identifier of the camera device | | name | string | The human-readable name of the camera device | | position | CameraPosition | The position of the camera device (front or back) | | deviceType | CameraDeviceType | The type of the camera device (e.g., wide, ultra-wide, telephoto) - iOS only |

GetZoomResponse

Response for getting zoom level information.

| Prop | Type | Description | | ------------- | ------------------- | -------------------------------- | | min | number | The minimum zoom level supported | | max | number | The maximum zoom level supported | | current | number | The current zoom level |

GetFlashModeResponse

Response for getting the current flash mode.

| Prop | Type | Description | | --------------- | ----------------------------------------------- | ------------------------------ | | flashMode | FlashMode | The current flash mode setting |

GetSupportedFlashModesResponse

Response for getting supported flash modes.

| Prop | Type | Description | | ---------------- | ------------------------ | ------------------------------------------------------- | | flashModes | FlashMode[] | An array of flash modes supported by the current camera |

IsTorchAvailableResponse

Response for checking torch availability.

| Prop | Type | Description | | --------------- | -------------------- | ----------------------------------------------------------------- | | available | boolean | Indicates if the device supports torch (flashlight) functionality |

GetTorchModeResponse

Response for getting the current torch mode.

| Prop | Type | Description | | ------------- | -------------------- | -------------------------------------------------------------------------------------------- | | enabled | boolean | Indicates if the torch is currently enabled | | level | number | The current torch intensity level (0.0 to 1.0, iOS only). Always 1.0 on Android when enabled |

PermissionStatus

Response for the camera permission status.

| Prop | Type | Description | | ------------ | ----------------------------------------------------------- | ---------------------------------- | | camera | PermissionState | The state of the camera permission |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

BarcodeDetectionData

Data for a detected barcode.

| Prop | Type | Description | | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------- | | value | string | The decoded string value of the barcode | | displayValue | string | The display value of the barcode (may differ from the raw value) | | type | string | The type/format of the barcode (e.g., 'qr', 'code128', etc.) | | boundingRect | BoundingRect | The bounding rectangle of the barcode in the camera frame. |

BoundingRect

Rectangle defining the boundary of the barcode in the camera frame. Coordinates are normalized between 0 and 1 relative to the camera frame.

| Prop | Type | Description | | ------------ | ------------------- | -------------------------------------------------------------------------------- | | x | number | X-coordinate of the top-left corner | | y | number | Y-coordinate of the top-left corner | | width | number | Width of the bounding rectangle (should match the actual width of the barcode) | | height | number | Height of the bounding rectangle (should match the actual height of the barcode) |

Type Aliases

CameraPosition

Position options for the camera.

• 'front': Front-facing camera
• 'back': Rear-facing camera

'front' | 'back'

CameraDeviceType

Available camera device types for iOS. Maps to AVCaptureDevice DeviceTypes in iOS.

'wideAngle' | 'ultraWide' | 'telephoto' | 'dual' | 'dualWide' | 'triple' | 'trueDepth'

CaptureResponse

Response for capturing a photo This will contain either a base64 encoded string or a web path to the captured photo, depending on the saveToFile option in the CaptureOptions.

T['saveToFile'] extends true ? { /** The web path to the captured photo that can be used to set the src attribute of an image for efficient loading and rendering (when saveToFile is true) / webPath: string; } : { /* The base64 encoded string of the captured photo (when saveToFile is false or undefined) */ photo: string; }

FlashMode

Flash mode options for the camera.

• 'off': Flash disabled
• 'on': Flash always on
• 'auto': Flash automatically enabled in low-light conditions

'off' | 'on' | 'auto'

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'