vue barcode scanner

A barcode/QR code scanner for Vue 2

undecaf

Vue

A barcode/QR code scanner for Vue 2

Minified size
Open issues

Total downloads

License

This Vue component, BarcodeScanner, offers the following features:

Scans <img>, <canvas> and live <video> elements, MediaStreams (cameras),
image and video Blobs and Files and more
Renders sources that are not DOM elements (e.g. MediaStream, File) automatically
Reports detected barcodes, status and errors as events
Scans videos repeatedly as long as they are playing
Can restrict scanning to a region of the source area
Applies user-defined styles to the scanning region and for highlighting detected barcodes
Handles source and configuration changes reactively
Relies on the
Barcode Detection API
or on any available polyfill
Detects all barcodes that
the underlying BarcodeDetector
or polyfill supports
Adapts the scanning frequency automatically to stay below a configurable processing load limit

Try these features on this online example
(source code
with build scripts for Rollup, esbuild and Webpack/Vue CLI).

Installation
Usage
License

Installation

As ES module

$ npm install @undecaf/vue-barcode-scanner
    or
$ yarn add @undecaf/vue-barcode-scanner

Then import BarcodeScanner from '@undecaf/vue-barcode-scanner' where required and place as
<barcode-scanner> in your template. This CodePen
demonstrates the scanner in a Vue SFC.

As plain `<script>`

<script src="https://cdn.jsdelivr.net/npm/@undecaf/vue-barcode-scanner/dist/index.js"></script>

This exposes the component options object as barcodeScanner.default.
This CodePen shows the scanner in a Vue <script>.

Polyfilling `BarcodeDetector`

BarcodeScanner relies on the Barcode Detection API
to do its work. For browsers that do not yet implement this API,
a polyfill will be required.

The following snippets use
@undecaf/barcode-detector-polyfill
(written by the same author as this component) as an example.

Polyfill if necessary in an ES module (also shown in this CodePen):

import { BarcodeDetectorPolyfill } from '@undecaf/barcode-detector-polyfill'

try {
    window['BarcodeDetector'].getSupportedFormats()
} catch {
    window['BarcodeDetector'] = BarcodeDetectorPolyfill
}
    ⁝

In a plain <script> (shown in this CodePen):

<script src="https://cdn.jsdelivr.net/npm/@undecaf/zbar-wasm/dist/index.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@undecaf/barcode-detector-polyfill/dist/index.js"></script>
<script>
    try {
        window['BarcodeDetector'].getSupportedFormats()
    } catch {
        window['BarcodeDetector'] = barcodeDetectorPolyfill.BarcodeDetectorPolyfill
    }
        ⁝
</script>

Usage

Source element

BarcodeScanner needs an image or video source that is to be scanned for barcodes.
This can be an <img>, <canvas> or <video> element, or a container or a Vue component
having one of these elements as descendant (for other source types, see the source attribute).
For example:

<barcode-scanner ...>
  <video ...></video>
</barcode-scanner>

The source element/container must be the only child of <barcode-scanner>.
If located inside a container then <img>/<canvas>/<video> must cover that container exactly
in order for masks and barcode highlights to appear in correct positions.
The source attribute may specify a CSS selector for a particular source element inside the container.

The source element and its src and srcObject attributes are reactive, i.e. changed content
is scanned automatically. Video sources are scanned repeatedly while being played.
To scan animated <canvas> content, capture it as MediaStream
and pass that to the source attribute.

Attributes

All attributes are reactive. Try them in the example project!

source: the image/video source that is to be shown/played inside <barcode-scanner>
and that is to be scanned for barcodes.
Must be specified if <barcode-scanner> does not contain a source element.

May be any of:
- Blob
  and File
  with any image/* or video/* type supported by the browser
- MediaStream
- ImageData
- ImageBitmap
- OffscreenCanvas
MediaStream and video/* Blobs/Files are scanned repeatedly while being played, see rate below.

If the source element is a container with multiple <img>, <canvas> or <video>
elements then source must be a
CSS selector
that selects one of them.
formats (optional): a string array of the barcode formats to be detected. Getting the available formats:
```
const formats = await BarcodeDetector.getSupportedFormats()
```
If this attribute is omitted then all supported formats will be detected.
mask-css (optional): the CSS class(es) for a <div> that overlays the source and defines
a reduced scanning area.
Only content inside the border box of that <div> will be scanned if this attribute is specified.
This can increase performance considerably.

The <div> is managed by the BarcodeScanner component. position:absolute is enforced, and coordinates and dimensions
should be specified as % of the source size. For example:
```
.centered-mask {  /* centered, 50% of source width, 80% of source height */
  left: 25%;
  top: 10%;
  width: 50%;
  height: 80%;
  box-shadow: 0 0 0 10000px rgba(0, 0, 0, 0.4);  /* dims the surrounding area */
}
```
CSS class .detected is added to the <div> automatically if any barcode was detected.
The names of the detected barcode formats (in original spelling and in kebab case)
are also added as CSS classes. This allows visual feedback on detection, for example:
```
.centered-mask.detected {   /* green border on barcode detection */
  border: rgb(128, 255, 128) solid 3px;
}

.centered-mask.qr-code::before {    /* shows the detected format as text */
  content: "It's a QR code!";
  display: block;
  text-align: center;
  color: rgb(255, 255, 255);
  background-color: rgb(128, 255, 128);
}
```
More examples can be found in the mask style examples.
highlight-css (optional): the CSS class(es) for the <div>s that each enclose a detected barcode.
These <div>s are placed and sized automatically, therefore the CSS styles must not affect their position and size.
For example:
```
.simple-highlight {   /* blue border and translucent blue background */
  border: rgb(64, 64, 255) solid 2px;
  background-color: rgba(64, 64, 255, 0.3);
}
```
Each <div> also receives the name of the respective barcode format (in original spelling and in kebab case)
as additional CSS classes. This allows format-specific highlighting, for example:
```
.simple-highlight.code-39 {   /* highlights code 39 barcodes in red */
  border-color: rgb(255, 64, 64);
  background-color: rgba(255, 64, 64, 0.3);
}
```
More examples can be found in the highlight style examples.

If this property is omitted then detected barcodes will be enclosed in a green (#80ff80) border.
To disable highlighting entirely, set :highlight-css="null".
scanning (optional): as a boolean input, starts and stops scanning; as aboolean output,
indicates whether scanning is in progress. In order to work in this bidirectional mode, a variable must be bound
to this attribute with the
.sync modifier.

Usually this attribute is not needed because scanning starts automatically whenever the source,
formats or mask-css changes.
rate (optional): the desired scans per second as a string like 15/s, or the JavaScript
processing load limit for repeated scanning as a string like 50%. The numbers must be integers.

If missing or invalid then rate defaults to 20/s.
debug (optional): if true then debug messages and events are logged at the console; defaults to false.
This impacts performance, not recommended for production.

Getting results: events

bcs-scanned: emitted after each scan cycle, regardless of whether a barcode was detected or not.
Detected barcodes are passed as an array of objects in the event payload, one element per barcode.
Each object has the following properties
(see here for details):
- format: the detected barcode format (one of the specified formats)
- rawValue: the decoded barcode, always a string decoded from raw data
- boundingBox: the DOMRectReadOnly enclosing the
  barcode in the source
- cornerPoints: an arry of four {x, y} pairs in clockwise order, representing four corner points of the detected barcode.
  BarcodeDetectorPolyfill returns the boundingBox corner points.
Additional properties may be returned by BarcodeDetector polyfills.
bcs-started: signals that scanning has started automatically or as requested by
scanning and that one (for an image source)
or several (for a video source) bcs-scanned events are to be expected.
bcs-stopped: emitted after an image source was scanned once or when repeated scanning of a video source
stopped because the video stopped playing or as requested by scanning.
bcs-error: indicates an error with the details passed as event payload.

If desired then the names of the events described above can be imported as constants:

import { SCANNED_EVENT, STARTED_EVENT, STOPPED_EVENT, ERROR_EVENT } from 'undecaf/vue-barcode-scanner'

In a plain script, these constants are named barcodeScanner.SCANNED_EVENT etc.

License

Software: MIT

Documentation: CC-BY-SA 4.0

vue barcode scanner

A barcode/QR code scanner for Vue 2

Contents

Installation

As ES module

As plain <script>

Polyfilling BarcodeDetector

Usage

Source element

Attributes

Getting results: events

License

As plain `<script>`

Polyfilling `BarcodeDetector`