vue-qr-scanner

📷 A modern Vue 3 QR/Barcode scanner component with an overlay ROI (Region of Interest), auto–fallback between BarcodeDetector API → ZXing WASM, and customizable UI.

✨ Features

• Vue 3 Component — drop straight into your Vite/Nuxt projects.
• Overlay ROI (Region of Interest) with dark mask outside the scan area.
• Border styles: full box or corner/bracket style (like native scanner apps).
• Auto fallback from BarcodeDetector API to ZXing WASM.
• Torch & Camera Switch controls exposed via slot.
• Square / Rectangle ROI with adjustable aspect ratio.
• ROI filtering (only emit detections inside the ROI).
• Custom video size (videoWidth & videoHeight).
• Debug mode for engine logs and detection streaks.

Install

npm install vue-qr-scanner
# or
yarn add vue-qr-scanner

Usage

Basic Example

<template>
    <QrScanner 
        roi-shape="rect" 
        :roi-aspect="2" 
        :roi-size-ratio="0.7"
        @detect="onDetect"
        @engine-change="onEngineChange"
    />
</template>

<script setup lang="ts">
import { QrScanner } from 'vue-qr-scanner'

function onDetect(codes) {
  console.log('Detected:', codes[0]?.rawValue)
}
function onEngineChange(engine) {
  console.log('Engine switched to:', engine)
}
</script>

or

<template>
  <QrScanner v-slot:controls="{ state, toggleTorch, switchCamera }"
             :video-width="400"
             :video-height="400"
             :prefer-wasm="true"
             :wasm-url="wasmUrl"
             @detect="onDetect">
    <div class="controls">
      <button @click="toggleTorch">
         Torch: {{ state.torch ? 'ON' : 'OFF' }}
      </button>
      <button @click="switchCamera">
         Switch to {{ state.usingBack ? 'Front' : 'Back' }} Camera
      </button>
    </div>
  </QrScanner>
</template>

<script setup lang="ts">
import wasmUrl from '@/assets/modules/zxing_reader.wasm?url'
import { QrScanner } from 'vue-qr-scanner'

function onDetect(codes) {
  console.log('Detected code:', codes[0]?.rawValue)
}
</script>

Props

Scanner Control | Prop | Type | Default | Description | | ---------------- | ---------- | ------------- | ------------------------------------------------------------------------------------- | | formats | string[] | ['qr_code'] | List of formats for BarcodeDetector. ZXing WASM will attempt all supported formats. | | frameInterval | number | 1 | Process every Nth frame (throttle). | | mirrorWhenUser | boolean | true | Mirror overlay when using the front-facing camera. |

ROI (Region of Interest) | Prop | Type | Default | Description | | ---------------------- | -------------------- | ----------- | ------------------------------------------------------------- | | roiShape | 'square' \| 'rect' | 'square' | Shape of the ROI. | | roiAspect | number | 1.6 | Aspect ratio (width/height) when roiShape="rect". | | roiSizeRatio | number | 0.6 | ROI size relative to the short side of the video (0–1). | | roiPadding | number | 0 | Extra padding inside the ROI (shrinks scan area). | | roiRadius | number | 12 | Corner radius of the ROI border. | | roiBorderStyle | 'full' \| 'corner' | 'corner' | Border style: full box or corner brackets. | | roiBorderWidth | number | 3 | Border width for 'full' style (or fallback for 'corner'). | | roiCornerLength | number | 28 | Corner bracket length for 'corner' style. | | roiCornerWidth | number | 0 | Corner bracket width (0 = use roiBorderWidth). | | roiBorderColorIdle | string | '#ffffff' | Border color when idle. | | roiBorderColorActive | string | '#22c55e' | Border color when a code is detected. | | roiInnerFillOpacity | number | 0.12 | Light fill inside ROI (0–1). Set 0 to disable. | | showMask | boolean | true | Show dark mask outside ROI. | | useRoi | boolean | true | Crop detection to ROI area. | | filterInsideRoi | boolean | false | Only emit detection if the code’s centroid lies inside ROI. |

Video | Prop | Type | Default | Description | | ------------- | ------------------ | -------- | -------------------------------- | | videoWidth | number \| string | '100%' | Video width (px or CSS string). | | videoHeight | number \| string | 'auto' | Video height (px or CSS string). |

Playback & Detection Control | Prop | Type | Default | Description | | ----------------- | --------- | ------- | ------------------------------------------------------------------------------------- | | paused | boolean | false | Pause camera preview & scanning from outside. | | releaseOnPause | boolean | false | When pausing, also stop camera tracks (saves battery/permission). Will reacquire on resume. | | detectEnabled | boolean | true | If false, do not emit @detect (overlay still updates). | | scanOnce | boolean | false | Stop scanning after first successful detection. |

Engine & Debug | Prop | Type | Default | Description | | ----------------- | --------- | ------- | ------------------------------------------------------------------------------------- | | preferWasm | boolean | false | Force ZXing WASM instead of BarcodeDetector. | | bdTimeoutMs | number | 2500 | Auto–fallback to WASM if BarcodeDetector returns no results after N ms. | | bdMaxZeroFrames | number | 30 | Auto–fallback to WASM if BarcodeDetector returns no results for N consecutive frames. | | debug | boolean | false | Log engine info and detection counts to console. |

WASM File | Prop | Type | Default | Description | | ----------------- | --------- | ------- | ------------------------------------------------------------------------------------- | | wasmUrl | string | '' | Override .wasm file URL. If empty, uses zxing-wasm default.. |

License

MIT