https://github.com/michaelwolz/capacitor-camera-view
🎞️ A Capacitor plugin for embedding a live camera feed directly into your app.
https://github.com/michaelwolz/capacitor-camera-view
barcode-scanner camera camera-preview capacitor capacitor-plugin qrcode-scanner
Last synced: 2 months ago
JSON representation
🎞️ A Capacitor plugin for embedding a live camera feed directly into your app.
- Host: GitHub
- URL: https://github.com/michaelwolz/capacitor-camera-view
- Owner: michaelwolz
- License: apache-2.0
- Created: 2025-03-02T07:53:21.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-20T16:08:31.000Z (4 months ago)
- Last Synced: 2026-02-20T18:10:39.816Z (4 months ago)
- Topics: barcode-scanner, camera, camera-preview, capacitor, capacitor-plugin, qrcode-scanner
- Language: TypeScript
- Homepage:
- Size: 1.33 MB
- Stars: 22
- Watchers: 2
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Capacitor Camera View
A Capacitor plugin for embedding a live camera feed directly into your app.
---
## 🚀 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:
```bash
npm install capacitor-camera-view
npx cap sync
```
### Platform Configuration
#### iOS
Add the following keys to your app's `Info.plist` file:
```xml
NSCameraUsageDescription
To capture photos and videos
```
#### Android
The `CAMERA` permission is automatically added by Capacitor. Ensure your `AndroidManifest.xml` includes it if needed for specific configurations:
```xml
```
## ▶️ Basic Usage
```typescript
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):
```css
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**](https://developer.apple.com/documentation/avfoundation/avcapturedevice/devicetype-swift.struct/builtintriplecamera). 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](https://developer.apple.com/documentation/avfoundation/avcapturedevice/devicetype-swift.struct/builtintriplecamera).
Alternatively, you can specify the `preferredCameraDeviceTypes` option in the CameraSessionConfiguration to prioritize specific virtual cameras, such as the [dual camera system](https://developer.apple.com/documentation/avfoundation/avcapturedevice/devicetype-swift.struct/builtindualcamera). 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`](https://developer.apple.com/documentation/avfoundation/avcapturemetadataoutput).
* **Android:** Utilizes Google's [**ML Kit Barcode Scanning**](https://developers.google.com/ml-kit/vision/barcode-scanning).
* **Web:** Uses the [**Barcode Detection API**](https://developer.mozilla.org/en-US/docs/Web/API/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`](https://www.npmjs.com/package/@undecaf/barcode-detector-polyfill) or [`barcode-detector`](https://www.npmjs.com/package/barcode-detector).
**Enabling Barcode Detection:**
To enable this feature, set the `enableBarcodeDetection` option to `true` when calling the `start()` method:
```typescript
await CameraView.start({ enableBarcodeDetection: true });
```
**Listening for Barcodes:**
Once enabled, you can listen for the `barcodeDetected` event to receive data about scanned barcodes:
```typescript
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`](#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](https://github.com/semantic-release/semantic-release) for automated versioning and changelog generation based on conventional commits.
## Conventional Commits
Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for your commit messages. Example:
```
feat(camera): add autofocus support
fix(android): resolve crash on startup
chore: update dependencies
```
## Resources
- [semantic-release documentation](https://semantic-release.gitbook.io/semantic-release/)
- [Conventional Commits](https://www.conventionalcommits.org/)
## API
* [`start(...)`](#start)
* [`stop()`](#stop)
* [`isRunning()`](#isrunning)
* [`capture(...)`](#capture)
* [`captureSample(...)`](#capturesample)
* [`flipCamera()`](#flipcamera)
* [`getAvailableDevices()`](#getavailabledevices)
* [`getZoom()`](#getzoom)
* [`setZoom(...)`](#setzoom)
* [`getFlashMode()`](#getflashmode)
* [`getSupportedFlashModes()`](#getsupportedflashmodes)
* [`setFlashMode(...)`](#setflashmode)
* [`isTorchAvailable()`](#istorchavailable)
* [`getTorchMode()`](#gettorchmode)
* [`setTorchMode(...)`](#settorchmode)
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions()`](#requestpermissions)
* [`addListener('barcodeDetected', ...)`](#addlistenerbarcodedetected-)
* [`removeAllListeners(...)`](#removealllisteners)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
Main plugin interface for Capacitor Camera View functionality.
### start(...)
```typescript
start(options?: CameraSessionConfiguration | undefined) => Promise
```
Start the camera view with optional configuration.
| Param | Type | Description |
| ------------- | --------------------------------------------------------------------------------- | ---------------------------------------------- |
| **`options`** | CameraSessionConfiguration | - Configuration options for the camera session |
**Since:** 1.0.0
--------------------
### stop()
```typescript
stop() => Promise
```
Stop the camera view and release resources.
**Since:** 1.0.0
--------------------
### isRunning()
```typescript
isRunning() => Promise
```
Check if the camera view is currently running.
**Returns:** Promise<IsRunningResponse>
**Since:** 1.0.0
--------------------
### capture(...)
```typescript
capture(options: T) => Promise>
```
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(...)
```typescript
captureSample(options: T) => Promise>
```
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](https://developer.mozilla.org/en-US/docs/Web/API/ImageCapture) 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()
```typescript
flipCamera() => Promise
```
Switch between front and back camera.
**Since:** 1.0.0
--------------------
### getAvailableDevices()
```typescript
getAvailableDevices() => Promise
```
Get available camera devices for capturing photos.
**Returns:** Promise<GetAvailableDevicesResponse>
**Since:** 1.0.0
--------------------
### getZoom()
```typescript
getZoom() => Promise
```
Get current zoom level information and available range.
**Returns:** Promise<GetZoomResponse>
**Since:** 1.0.0
--------------------
### setZoom(...)
```typescript
setZoom(options: { level: number; ramp?: boolean; }) => Promise
```
Set the camera zoom level.
| Param | Type | Description |
| ------------- | ----------------------------------------------- | ---------------------------- |
| **`options`** | { level: number; ramp?: boolean; } | - Zoom configuration options |
**Since:** 1.0.0
--------------------
### getFlashMode()
```typescript
getFlashMode() => Promise
```
Get current flash mode setting.
**Returns:** Promise<GetFlashModeResponse>
**Since:** 1.0.0
--------------------
### getSupportedFlashModes()
```typescript
getSupportedFlashModes() => Promise
```
Get supported flash modes for the current camera.
**Returns:** Promise<GetSupportedFlashModesResponse>
**Since:** 1.0.0
--------------------
### setFlashMode(...)
```typescript
setFlashMode(options: { mode: FlashMode; }) => Promise
```
Set the camera flash mode.
| Param | Type | Description |
| ------------- | ---------------------------------------------------------- | ---------------------------------- |
| **`options`** | { mode: FlashMode; } | - Flash mode configuration options |
**Since:** 1.0.0
--------------------
### isTorchAvailable()
```typescript
isTorchAvailable() => Promise
```
Check if the device supports torch (flashlight) functionality.
**Returns:** Promise<IsTorchAvailableResponse>
**Since:** 1.2.0
--------------------
### getTorchMode()
```typescript
getTorchMode() => Promise
```
Get the current torch (flashlight) state.
**Returns:** Promise<GetTorchModeResponse>
**Since:** 1.2.0
--------------------
### setTorchMode(...)
```typescript
setTorchMode(options: { enabled: boolean; level?: number; }) => Promise
```
Set the torch (flashlight) mode and intensity.
| Param | Type | Description |
| ------------- | -------------------------------------------------- | ----------------------------- |
| **`options`** | { enabled: boolean; level?: number; } | - Torch configuration options |
**Since:** 1.2.0
--------------------
### checkPermissions()
```typescript
checkPermissions() => Promise
```
Check camera permission status without requesting permissions.
**Returns:** Promise<PermissionStatus>
**Since:** 1.0.0
--------------------
### requestPermissions()
```typescript
requestPermissions() => Promise
```
Request camera permission from the user.
**Returns:** Promise<PermissionStatus>
**Since:** 1.0.0
--------------------
### addListener('barcodeDetected', ...)
```typescript
addListener(eventName: 'barcodeDetected', listenerFunc: (data: BarcodeDetectionData) => void) => Promise
```
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(...)
```typescript
removeAllListeners(eventName?: string | undefined) => Promise
```
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 | Since |
| -------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ----- |
| **`enableBarcodeDetection`** | boolean | Enables the barcode detection functionality | false | |
| **`barcodeTypes`** | BarcodeType[] | Specific barcode types to detect. If not provided, all supported types are detected. Specifying only the types you need can significantly improve performance and reduce battery consumption, especially on mobile devices. | undefined - all supported types are detected | 2.1.0 |
| **`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
#### BarcodeType
Supported barcode types for detection.
Specifying only the barcode types you need can improve performance
and reduce battery consumption.
'qr' | 'code128' | 'code39' | 'code39Mod43' | 'code93' | 'ean8' | 'ean13' | 'interleaved2of5' | 'itf14' | 'pdf417' | 'aztec' | 'dataMatrix' | 'upce'
#### 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'