@capgo/camera-preview

v8.11.1

Published

a day ago

Camera preview

Downloads

40,621

0High
0Medium
0Low

riderx

capacitor plugin camera preview native zoom focus flash lense video photo image capture barcode qr scanner

Capacitor Camera Preview Plugin

NPM Version NPM Downloads GitHub Repo stars GitHub Actions Workflow Status GitHub License Maintenance

Why Camera Preview?

A free, fully-featured alternative to paid camera plugins, built for maximum flexibility and performance:

Complete UI control - Build your own camera interface with HTML/JS overlays instead of native constraints
Full hardware access - Manual focus, zoom, exposure controls, flash modes, multiple cameras
Video recording - Record with custom settings, no arbitrary limitations
Universal device support - Tested across hundreds of Android and iOS devices
Performance optimized - Direct camera stream access, efficient memory usage
Modern package management - Supports both Swift Package Manager (SPM) and CocoaPods (SPM-ready for Capacitor 8)
Same JavaScript API - Compatible interface with paid alternatives

Unlike restrictive paid plugins, you get full camera control to build exactly the experience you want - from QR scanners to professional video apps.

This plugin is compatible Capacitor 7 and above.

Use v6 for Capacitor 6 and below.

PR's are greatly appreciated.

-- @riderx, current maintainers

Remember to add the style below on your app's HTML or body element:

:root {
  --ion-background-color: transparent !important;
}

Take into account that this will make transparent all ion-content on application, if you want to show camera preview only in one page, just add a custom class to your ion-content and make it transparent:

.my-custom-camera-preview-content {
  --background: transparent;
}

If the camera preview is not displaying after applying the above styles, apply transparent background color to the root div element of the parent component Ex: VueJS >> App.vue component

<template>
  <ion-app id="app">
    <ion-router-outlet />
  </ion-app>
</template>

<style>
#app {
  background-color: transparent !important;
}
<style>

If it don't work in dark mode here is issue who explain how to fix it: https://github.com/capacitor-community/camera-preview/issues/199

Good to know

Video and photo taken with the plugin are never removed, so do not forget to remove them after used to not bloat the user phone.

use https://capacitorjs.com/docs/apis/filesystem#deletefile for that

Touch & Gestures (JS‑Driven)

Native tap‑to‑focus and pinch‑to‑zoom gesture handling are intentionally disabled on both Android and iOS.
Handle all user interactions in your HTML/JS layer, then call the plugin methods:
- Focus: await CameraPreview.setFocus({ x, y }) with normalized coordinates (0–1) relative to the preview bounds.
- Zoom: await CameraPreview.setZoom({ level }) using your own gesture/UI logic.
Rationale: native gesture recognizers can conflict with your HTML touch handlers and block UI interactions. Keeping gestures in JS guarantees your UI receives touches as intended.
The enableZoom start option is removed. Use JS gestures + setZoom(...).
Tip: When using toBack: true, the WebView is in front of the camera and receives touches; design your overlay UI there and drive focus/zoom through the JS API.

Fast base64 from file path (no bridge)

When using storeToFile: true, you can avoid sending large base64 strings over the Capacitor bridge:

import { CameraPreview, getBase64FromFilePath } from '@capgo/camera-preview'

await CameraPreview.start({ storeToFile: true });
// Take a picture and get a file path
const { value: filePath } = await CameraPreview.capture({ quality: 85 })

// Convert the file to base64 entirely on the JS side (fast, no bridge)
const base64 = await getBase64FromFilePath(filePath)

// Optionally cleanup the temp file natively
await CameraPreview.deleteFile({ path: filePath })

Exposure controls (iOS & Android)

This plugin exposes camera exposure controls on iOS and Android:

Exposure modes: "AUTO" | "LOCK" | "CONTINUOUS" | "CUSTOM"
Exposure compensation (EV bias): get range { min, max, step }, read current value, and set new value

Platform notes:

iOS: The camera starts in CONTINUOUS by default. Switching to AUTO or CONTINUOUS resets EV to 0. The step value is approximated to 0.1 since iOS does not expose the bias step.
Android: AE lock/unlock and mode are handled via CameraX + Camera2 interop. The step value comes from CameraX ExposureState and may vary per device.

Example (TypeScript):

import { CameraPreview } from '@capgo/camera-preview';

// Query supported modes
const { modes } = await CameraPreview.getExposureModes();
console.log('Supported exposure modes:', modes);

// Get current mode
const { mode } = await CameraPreview.getExposureMode();
console.log('Current exposure mode:', mode);

// Set mode (AUTO | LOCK | CONTINUOUS | CUSTOM)
await CameraPreview.setExposureMode({ mode: 'CONTINUOUS' });

// Get EV range (with step)
const { min, max, step } = await CameraPreview.getExposureCompensationRange();
console.log('EV range:', { min, max, step });

// Read current EV
const { value: currentEV } = await CameraPreview.getExposureCompensation();
console.log('Current EV:', currentEV);

// Increment EV by one step and clamp to range
const nextEV = Math.max(min, Math.min(max, currentEV + step));
await CameraPreview.setExposureCompensation({ value: nextEV });

Example app (Ionic):

Exposure mode toggle (sun icon) cycles through modes.
EV controls (+/−) are placed in a top‑right floating action bar, outside the preview area.

Barcode scanning

Barcode scanning reuses the active camera preview, so the preview can still sit behind the WebView while your HTML overlay stays interactive.

import { CameraPreview } from '@capgo/camera-preview';

await CameraPreview.addListener('barcodeScanned', ({ barcodes }) => {
  console.log('Barcodes:', barcodes);
});

await CameraPreview.start({
  position: 'rear',
  toBack: true,
  barcodeScanner: {
    formats: ['qr_code'],
    detectionInterval: 500,
  },
});

Use barcodeScanner: true to scan all supported formats. You can also call startBarcodeScanner() and stopBarcodeScanner() after the preview is running to scan only during a specific flow.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/camera-preview/

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/camera-preview` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

yarn add @capgo/camera-preview

or

npm install @capgo/camera-preview

Then run

npx cap sync

Optional Configuration

To use certain features of this plugin, you will need to add the following permissions/keys to your native project configurations.

Android

In your android/app/src/main/AndroidManifest.xml:

Audio Recording (disableAudio: false):

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

Saving to Gallery (saveToGallery: true):

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

Location in EXIF Data (withExifLocation: true):

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

iOS

In your ios/App/App/Info.plist, you must provide descriptions for the permissions your app requires. The keys are added automatically, but you need to provide the string values.

Audio Recording (disableAudio: false):

<key>NSMicrophoneUsageDescription</key>
<string>To record audio with videos</string>

Saving to Gallery (saveToGallery: true):

<key>NSPhotoLibraryUsageDescription</key>
<string>To save photos to your gallery</string>

Location in EXIF Data (withExifLocation: true):

<key>NSLocationWhenInUseUsageDescription</key>
<string>To add location data to your photos</string>

Haptics during video recording (allowHapticsAndSystemSoundsDuringRecording: true): When recording video with audio enabled (disableAudio: false), iOS suppresses haptic feedback by default. Opt in on startRecordVideo() to allow haptics while recording, for example to warn users before a time limit expires:
```
import { Haptics, ImpactStyle } from '@capacitor/haptics';

await CameraPreview.startRecordVideo({
  disableAudio: false,
  allowHapticsAndSystemSoundsDuringRecording: true,
});

// Later, while recording:
await Haptics.impact({ style: ImpactStyle.Medium });
```

Extra Android installation steps

Important camera-preview 3+ requires Gradle 7. Open android/app/src/main/AndroidManifest.xml and above the closing </manifest> tag add this line to request the CAMERA permission:

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

For more help consult the Capacitor docs.

Extra iOS installation steps

You will need to add two permissions to Info.plist. Follow the Capacitor docs and add permissions with the raw keys NSCameraUsageDescription and NSMicrophoneUsageDescription. NSMicrophoneUsageDescription is only required, if audio will be used. Otherwise set the disableAudio option to true, which also disables the microphone permission request.

Extra Web installation steps

Add import '@capgo/camera-preview' to you entry script in ionic on app.module.ts, so capacitor can register the web platform from the plugin

Example with Capacitor uploader:

Documentation for the uploader

  import { CameraPreview } from '@capgo/camera-preview'
  import { Uploader } from '@capgo/capacitor-uploader';


  async function record() {
    await CameraPreview.startRecordVideo({ storeToFile: true })
    await new Promise(resolve => setTimeout(resolve, 5000))
    const fileUrl = await CameraPreview.stopRecordVideo()
    console.log(fileUrl.videoFilePath)
    await uploadVideo(fileUrl.videoFilePath)
  }

  async function uploadVideo(filePath: string) {
    Uploader.addListener('events', (event) => {
      switch (event.name) {
        case 'uploading':
          console.log(`Upload progress: ${event.payload.percent}%`);
          break;
        case 'completed':
          console.log('Upload completed successfully');
          console.log('Server response status code:', event.payload.statusCode);
          break;
        case 'failed':
          console.error('Upload failed:', event.payload.error);
          break;
      }
    });
    try {
      const result = await Uploader.startUpload({
        filePath,
        serverUrl: 'S#_PRESIGNED_URL',
        method: 'PUT',
        headers: {
          'Content-Type': 'video/mp4',
        },
        mimeType: 'video/mp4',
      });
      console.log('Video uploaded successfully:', result.id);
    } catch (error) {
      console.error('Error uploading video:', error);
      throw error;
    }
  }

API

The main interface for the CameraPreview plugin.

start(...)

start(options: CameraPreviewOptions) => Promise<{ width: number; height: number; x: number; y: number; }>

Starts the camera preview.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------- | ------------------------------------------- | | options | CameraPreviewOptions | - The configuration for the camera preview. |

Returns: Promise<{ width: number; height: number; x: number; y: number; }>

Since: 0.0.1

stop(...)

stop(options?: { force?: boolean | undefined; } | undefined) => Promise<void>

Stops the camera preview.

| Param | Type | Description | | ------------- | --------------------------------- | ------------------------------------------------- | | options | { force?: boolean; } | - Optional configuration for stopping the camera. |

Since: 0.0.1

capture(...)

capture(options: CameraPreviewPictureOptions) => Promise<{ value: string; exif: ExifData; }>

Captures a picture from the camera.

If storeToFile was set to true when starting the preview, the returned value will be an absolute file path on the device instead of a base64 string. Use getBase64FromFilePath to get the base64 string from the file path.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- | | options | CameraPreviewPictureOptions | - The options for capturing the picture. |

Returns: Promise<{ value: string; exif: ExifData; }>

Since: 0.0.1

captureSample(...)

captureSample(options: CameraSampleOptions) => Promise<{ value: string; }>

Captures a single frame from the camera preview stream.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------- | --------------------------------------- | | options | CameraSampleOptions | - The options for capturing the sample. |

Returns: Promise<{ value: string; }>

Since: 0.0.1

startBarcodeScanner(...)

startBarcodeScanner(options?: BarcodeScannerOptions | undefined) => Promise<void>

Starts barcode scanning on the active camera preview.

The scanner reuses the current camera session and emits barcodeScanned events. Call stopBarcodeScanner() when scanning is no longer needed.

Android uses the lightweight Google Play Services ML Kit model. If the model is not installed yet, first scans may return no result until Google Play Services finishes downloading it.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | BarcodeScannerOptions |

Since: 8.8.0

stopBarcodeScanner()

stopBarcodeScanner() => Promise<void>

Stops barcode scanning while keeping the camera preview running.

Since: 8.8.0

getSupportedFlashModes()

getSupportedFlashModes() => Promise<{ result: CameraPreviewFlashMode[]; }>

Gets the flash modes supported by the active camera.

Returns: Promise<{ result: CameraPreviewFlashMode[]; }>

Since: 0.0.1

setAspectRatio(...)

setAspectRatio(options: { aspectRatio: CameraPreviewAspectRatio; x?: number; y?: number; }) => Promise<{ width: number; height: number; x: number; y: number; }>

Set the aspect ratio of the camera preview.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | options | { aspectRatio: CameraPreviewAspectRatio; x?: number; y?: number; } | - The desired aspect ratio and optional position. - aspectRatio: The desired aspect ratio ('4:3', '16:9', or 'fill') - x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally. - y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically. |

Returns: Promise<{ width: number; height: number; x: number; y: number; }>

Since: 7.5.0

getAspectRatio()

getAspectRatio() => Promise<{ aspectRatio: CameraPreviewAspectRatio; }>

Gets the current aspect ratio of the camera preview.

Returns: Promise<{ aspectRatio: CameraPreviewAspectRatio; }>

Since: 7.5.0

setGridMode(...)

setGridMode(options: { gridMode: GridMode; }) => Promise<void>

Sets the grid mode of the camera preview overlay.

| Param | Type | Description | | ------------- | ------------------------------------------------------------ | -------------------------------------------------- | | options | { gridMode: GridMode; } | - The desired grid mode ('none', '3x3', or '4x4'). |

Since: 8.0.0

getGridMode()

getGridMode() => Promise<{ gridMode: GridMode; }>

Gets the current grid mode of the camera preview overlay.

Returns: Promise<{ gridMode: GridMode; }>

Since: 8.0.0

checkPermissions(...)

checkPermissions(options?: Pick<PermissionRequestOptions, "disableAudio"> | undefined) => Promise<CameraPermissionStatus>

Checks the current camera (and optionally microphone) permission status without prompting the system dialog.

Returns: Promise<CameraPermissionStatus>

Since: 8.7.0

requestPermissions(...)

requestPermissions(options?: PermissionRequestOptions | undefined) => Promise<CameraPermissionStatus>

Requests camera (and optional microphone) permissions. If permissions are already granted or denied, the current status is returned without prompting. When showSettingsAlert is true and permissions are denied, a platform specific alert guiding the user to the app settings will be presented.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------- | | options | PermissionRequestOptions | - Configuration for the permission request behaviour. |

Returns: Promise<CameraPermissionStatus>

Since: 8.7.0

getHorizontalFov()

getHorizontalFov() => Promise<{ result: number; }>

Gets the horizontal field of view (FoV) for the active camera. Note: This can be an estimate on some devices.

Returns: Promise<{ result: number; }>

Since: 0.0.1

getSupportedPictureSizes()

getSupportedPictureSizes() => Promise<{ supportedPictureSizes: SupportedPictureSizes[]; }>

Gets the supported picture sizes for all cameras.

Returns: Promise<{ supportedPictureSizes: SupportedPictureSizes[]; }>

Since: 7.4.0

setFlashMode(...)

setFlashMode(options: { flashMode: CameraPreviewFlashMode | string; }) => Promise<void>

Sets the flash mode for the active camera.

| Param | Type | Description | | ------------- | ----------------------------------- | ------------------------- | | options | { flashMode: string; } | - The desired flash mode. |

Since: 0.0.1

flip()

flip() => Promise<void>

Toggles between the front and rear cameras.

Since: 0.0.1

setOpacity(...)

setOpacity(options: CameraOpacityOptions) => Promise<void>

Sets the opacity of the camera preview.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------- | ---------------------- | | options | CameraOpacityOptions | - The opacity options. |

Since: 0.0.1

stopRecordVideo()

stopRecordVideo() => Promise<RecordingFinishedEvent>

Stops an ongoing video recording.

Returns: Promise<RecordingFinishedEvent>

Since: 0.0.1

startRecordVideo(...)

startRecordVideo(options: CameraPreviewOptions) => Promise<void>

Starts recording a video.

Supports frameRate, videoCodec, videoStabilizationMode, maxDuration, maxFileSize, disableAudio, allowHapticsAndSystemSoundsDuringRecording, and mirrorFrontCamera on each call.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------- | ---------------------------------- | | options | CameraPreviewOptions | - The options for video recording. |

Since: 0.0.1

setVideoQuality(...)

setVideoQuality(options: { quality: VideoQuality; }) => Promise<void>

Sets the video recording quality for the active camera session.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------- | ---------------------------- | | options | { quality: VideoQuality; } | - The desired video quality. |

Since: 8.5.0

getVideoQuality()

getVideoQuality() => Promise<{ quality: VideoQuality; }>

Gets the current video recording quality.

Returns: Promise<{ quality: VideoQuality; }>

Since: 8.5.0

getSupportedVideoQualities()

getSupportedVideoQualities() => Promise<{ qualities: VideoQuality[]; }>

Returns the video qualities supported by the active camera.

Returns: Promise<{ qualities: VideoQuality[]; }>

Since: 8.5.0

setVideoCodec(...)

setVideoCodec(options: { codec: VideoCodec; }) => Promise<void>

Sets the video codec used when recording.

| Param | Type | Description | | ------------- | ------------------------------------------------------------- | -------------------- | | options | { codec: VideoCodec; } | - The desired codec. |

Since: 8.5.0

getVideoCodec()

getVideoCodec() => Promise<{ codec: VideoCodec; }>

Gets the current video codec used for recording.

Returns: Promise<{ codec: VideoCodec; }>

Since: 8.5.0

getSupportedVideoCodecs()

getSupportedVideoCodecs() => Promise<{ codecs: VideoCodec[]; }>

Returns the video codecs supported by the active camera.

Returns: Promise<{ codecs: VideoCodec[]; }>

Since: 8.5.0

isVideoStabilizationSupported()

isVideoStabilizationSupported() => Promise<{ supported: boolean; }>

Checks whether video stabilization is supported by the active camera.

Returns: Promise<{ supported: boolean; }>

Since: 8.5.2

getSupportedVideoStabilizationModes()

getSupportedVideoStabilizationModes() => Promise<{ modes: VideoStabilizationMode[]; }>

Returns the video stabilization modes supported by the active camera.

Returns: Promise<{ modes: VideoStabilizationMode[]; }>

Since: 8.5.2

getVideoStabilizationMode()

getVideoStabilizationMode() => Promise<{ mode: VideoStabilizationMode; }>

Gets the current video stabilization mode.

Returns: Promise<{ mode: VideoStabilizationMode; }>

Since: 8.5.2

setVideoStabilizationMode(...)

setVideoStabilizationMode(options: { mode: VideoStabilizationMode; }) => Promise<void>

Sets the video stabilization mode for recording. Cannot be changed while a recording is in progress. You can also pass videoStabilizationMode in startRecordVideo() options.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------------ | --------------------------------- | | options | { mode: VideoStabilizationMode; } | - The desired stabilization mode. |

Since: 8.5.2

isRunning()

isRunning() => Promise<{ isRunning: boolean; }>

Checks if the camera preview is currently running.

Returns: Promise<{ isRunning: boolean; }>

Since: 7.5.0

getAvailableDevices()

getAvailableDevices() => Promise<{ devices: CameraDevice[]; }>

Gets all available camera devices.

Returns: Promise<{ devices: CameraDevice[]; }>

Since: 7.5.0

getZoom()

getZoom() => Promise<{ min: number; max: number; current: number; lens: LensInfo; }>

Gets the current zoom state, including min/max and current lens info.

Returns: Promise<{ min: number; max: number; current: number; lens: LensInfo; }>

Since: 7.5.0

getZoomButtonValues()

getZoomButtonValues() => Promise<{ values: number[]; }>

Returns zoom button values for quick switching.

iOS/Android: includes 0.5 if ultra-wide available; 1 and 2 if wide available; 3 if telephoto available
Web: unsupported

Returns: Promise<{ values: number[]; }>

Since: 7.5.0

setZoom(...)

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

Sets the zoom level of the camera.

| Param | Type | Description | | ------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | options | { level: number; ramp?: boolean; autoFocus?: boolean; } | - The desired zoom level. ramp is currently unused. autoFocus defaults to true. |

Since: 7.5.0

getFlashMode()

getFlashMode() => Promise<{ flashMode: FlashMode; }>

Gets the current flash mode.

Returns: Promise<{ flashMode: CameraPreviewFlashMode; }>

Since: 7.5.0

removeAllListeners()

removeAllListeners() => Promise<void>

Removes all registered listeners.

Since: 7.5.0

setDeviceId(...)

setDeviceId(options: { deviceId: string; }) => Promise<void>

Switches the active camera to the one with the specified deviceId.

| Param | Type | Description | | ------------- | ---------------------------------- | ------------------------------------ | | options | { deviceId: string; } | - The ID of the device to switch to. |

Since: 7.5.0

getDeviceId()

getDeviceId() => Promise<{ deviceId: string; }>

Gets the ID of the camera device that is currently bound. On Android, if a physical-lens request falls back to a logical camera, this returns the bound logical camera ID.

Returns: Promise<{ deviceId: string; }>

Since: 7.5.0

getPreviewSize()

getPreviewSize() => Promise<{ x: number; y: number; width: number; height: number; }>

Gets the current preview size and position.

Returns: Promise<{ x: number; y: number; width: number; height: number; }>

Since: 7.5.0

setPreviewSize(...)

setPreviewSize(options: { x?: number; y?: number; width: number; height: number; }) => Promise<{ width: number; height: number; x: number; y: number; }>

Sets the preview size and position.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | -------------------------------- | | options | { x?: number; y?: number; width: number; height: number; } | The new position and dimensions. |

Returns: Promise<{ width: number; height: number; x: number; y: number; }>

Since: 7.5.0

setFocus(...)

setFocus(options: { x: number; y: number; }) => Promise<void>

Sets the camera focus to a specific point in the preview.

Note: The plugin does not attach any native tap-to-focus gesture handlers. Handle taps in your HTML/JS (e.g., on the overlaying UI), then pass normalized coordinates here.

| Param | Type | Description | | ------------- | -------------------------------------- | -------------------- | | options | { x: number; y: number; } | - The focus options. |

Since: 7.5.0

addListener('screenResize', ...)

addListener(eventName: 'screenResize', listenerFunc: (data: { width: number; height: number; x: number; y: number; }) => void) => Promise<PluginListenerHandle>

Adds a listener for screen resize events.

| Param | Type | Description | | ------------------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------- | | eventName | 'screenResize' | - The event name to listen for. | | listenerFunc | (data: { width: number; height: number; x: number; y: number; }) => void | - The function to call when the event is triggered. |