@undecaf/vue-barcode-scanner

A barcode/QR code scanner for Vue 2

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).

Contents

• Installation

  • As ES module
  • As plain <script>
  • Polyfilling BarcodeDetector

• Usage

  • Source element
  • Attributes
    • source
    • formats
    • mask-css
    • highlight-css
    • scanning
    • rate
    • debug
  • Getting results: events
    • bcs-scanned
    • bcs-started
    • bcs-stopped
    • bcs-error

• 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 {
    (new window['BarcodeDetector']()).getContext('2d')
} 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 {
        (new window['BarcodeDetector']()).getContext('2d')
    } 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 available 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 example styles.

• 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 example styles.

  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 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 a BarcodeDetector polyfill.

• bcs-started: signals that scanning has started automatically or as requested by scanning and that one (for an image source) or more (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