@rdlabo/capacitor-codescanner

Scan QR codes and barcodes with a native Capacitor modal.

The camera runs inside the modal, so you do not manage a camera view in your web assets. Use a single scan or continuous multi-scan; each catch delivers event.code.

Full documentation: https://docs.rdlabo.dev/projects/capacitor-codescanner

Documentation: Read the full documentation

Install

npm install @rdlabo/capacitor-codescanner
npx cap sync

Camera permission (required before first scan)

The plugin uses the device camera. On iOS, add a usage description to your app Info.plist (for example ios/App/App/Info.plist):

<key>NSCameraUsageDescription</key>
<string>This app needs camera access to scan QR codes and barcodes.</string>

Android declares android.permission.CAMERA in the plugin manifest; the OS may still prompt at runtime when you present the scanner. After editing native config, sync and rebuild the native app (npx cap sync, then open Xcode / Android Studio or your usual Capacitor native build).

Usage

See CodeScanner. Start the scan from a user action such as a button, after install and camera setup.

Register a listener, present the modal from a button handler, then remove the handle after present settles (including when the user closes the modal without a scan):

import { CodeScanner } from '@rdlabo/capacitor-codescanner';
import type { PluginListenerHandle } from '@capacitor/core';

const scanQRCode = async () => {
  let handle: PluginListenerHandle | undefined;
  try {
    handle = await CodeScanner.addListener('CodeScannerCatchEvent', (event) => {
      console.log('Scanned code:', event.code);
    });

    await CodeScanner.present({
      detectionWidth: 0.6,
      detectionHeight: 0.15,
      isMulti: false,
    });
  } finally {
    await handle?.remove();
  }
};

When to use

Use this plugin when you want a ready-to-use scanning modal without building a custom camera UI. It is useful for:

• Scanning QR codes or barcodes on receipts, products, or tickets.
• Collecting multiple codes in one session with isMulti: true.

Features

• Automatic light control: turns on the flashlight in dark environments by default.
• Vibration feedback: vibrates when a code is detected.
• Detection area overlay: shows a red frame around the active scan area.
• Detected code highlight: draws a red frame around the detected code.
• Close button: a default close button in the upper right corner.
• Multi-scan mode: keeps scanning until the user closes the modal when isMulti: true.

Platform notes

• iOS and Android: fully supported.
• Web: not supported because the plugin requires native camera access.

API

• present(...)
• addListener('CodeScannerCatchEvent', ...)
• Interfaces
• Type Aliases

present(...)

present(scannerOption: ScannerOption) => Promise<void>

Param	Type
scannerOption	ScannerOption

---

addListener('CodeScannerCatchEvent', ...)

addListener(eventName: 'CodeScannerCatchEvent', listenerFunc: (event: { code: string; }) => void) => Promise<PluginListenerHandle>

Param	Type
eventName	'CodeScannerCatchEvent'
listenerFunc	(event: { code: string; }) => void

Returns: Promise<PluginListenerHandle>

---

Interfaces

ScannerOption

Prop	Type	Description
detectionWidth	number	Width of the detection area relative to the available width (0–1). Default is 0.4.
detectionHeight	number	Height of the detection area relative to the detection width. Default is 1 on iOS; 0.15–0.2 is typical on Android.
enableCloseButton	boolean	Enable close button on the top left of the scanning area (default: true)
sheetScreenRatio	number	Specify the ratio of the scanning area (sheet modal size) to the screen size. Default is 0.9 for android, 1(pageSheet) for iOS.
CodeTypes	MetadataObjectTypes[]	Specify the types of codes to recognize (default: ["qr", "code39", "ean13"])
isMulti	boolean	Enable multi scan mode (default: false)
enableAutoLight	boolean	Enable auto light when environment is dark (default: true)

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

Type Aliases

MetadataObjectTypes

'aztec' | 'code128' | 'code39' | 'code39Mod43' | 'code93' | 'dataMatrix' | 'ean13' | 'ean8' | 'face' | 'interleaved2of5' | 'itf14' | 'pdf417' | 'qr' | 'upce' | 'catBody' | 'dogBody' | 'humanBody' | 'salientObject'

Prerelease channels

An open, non-draft pull request can be published to the npm beta dist-tag after its Validation and Package Candidate workflows pass. A repository owner or maintainer must add a comment whose entire body is:

/beta

The request authorizes only the pull request head SHA that existed when the comment was added. The workflow revalidates the owner or maintainer permission and head SHA immediately before publishing. Any new commit requires CI to pass again and a fresh owner or maintainer /beta comment. Fork pull requests are supported. Pull requests that change a release-gating workflow cannot be beta-published until those workflow changes land on main.

Beta versions use <base>-beta.pr<PR number>.sha<12-character SHA>. The candidate is built in a read-only workflow without npm publishing credentials. The privileged release workflow publishes only the validated immutable package artifact with lifecycle scripts disabled. A notification failure cannot invalidate a successful npm publish.

When a pull request is merged into main, it is automatically published to beta only after the required CI and Package Candidate succeed for that exact merge commit. Direct pushes to main do not publish a candidate.

Only npm run release creates a release tag. Stable vX.Y.Z tags publish to npm latest; revision/prerelease tags publish to next. Neither beta nor next publishing changes the npm latest dist-tag.

Maintainers

• rdlabo

License

This project is licensed under the MIT License.