{"id":26140924,"url":"https://github.com/undecaf/vue-barcode-scanner","last_synced_at":"2025-04-14T01:13:52.721Z","repository":{"id":104386849,"uuid":"448572503","full_name":"undecaf/vue-barcode-scanner","owner":"undecaf","description":"A barcode/QR code scanner for Vue 2","archived":false,"fork":false,"pushed_at":"2024-07-20T17:06:47.000Z","size":927,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T15:14:21.389Z","etag":null,"topics":["barcode-scanner","component","qrcode-scanner","vue","vuejs2"],"latest_commit_sha":null,"homepage":"","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/undecaf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-16T14:07:59.000Z","updated_at":"2024-10-10T05:52:24.000Z","dependencies_parsed_at":"2024-11-15T12:31:05.624Z","dependency_job_id":null,"html_url":"https://github.com/undecaf/vue-barcode-scanner","commit_stats":{"total_commits":13,"total_committers":1,"mean_commits":13.0,"dds":0.0,"last_synced_commit":"4abc1e021f97b4fddfbb398a56bb527babe87e47"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undecaf%2Fvue-barcode-scanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undecaf%2Fvue-barcode-scanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undecaf%2Fvue-barcode-scanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undecaf%2Fvue-barcode-scanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/undecaf","download_url":"https://codeload.github.com/undecaf/vue-barcode-scanner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248352050,"owners_count":21089375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["barcode-scanner","component","qrcode-scanner","vue","vuejs2"],"created_at":"2025-03-11T02:58:26.685Z","updated_at":"2025-04-14T01:13:52.699Z","avatar_url":"https://github.com/undecaf.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A barcode/QR code scanner for Vue 2\n\n![Minified size](https://badgen.net/packagephobia/install/@undecaf/vue-barcode-scanner?color=42cc24)\n![Open issues](https://badgen.net/github/open-issues/undecaf/vue-barcode-scanner)\n![Vulnerabilities](https://snyk.io/test/npm/@undecaf/vue-barcode-scanner/badge.svg)\n![Total downloads](https://badgen.net/npm/dt/@undecaf/vue-barcode-scanner)\n[![](https://badgen.net/jsdelivr/hits/npm/@undecaf/vue-barcode-scanner)](https://www.jsdelivr.com/package/npm/@undecaf/vue-barcode-scanner)\n![License](https://badgen.net/github/license/undecaf/vue-barcode-scanner)\n\nThis Vue component, `BarcodeScanner`, offers the following features:\n\n+ Scans `\u003cimg\u003e`, `\u003ccanvas\u003e` and live `\u003cvideo\u003e` elements, `MediaStream`s (cameras), \n  image and video `Blob`s and `File`s and more\n+ Renders sources that are not DOM elements (e.g. `MediaStream`, `File`) automatically\n+ Reports detected barcodes, status and errors as events\n+ Scans videos repeatedly as long as they are playing\n+ Can restrict scanning to a region of the source area\n+ Applies user-defined styles to the scanning region and for highlighting detected barcodes\n+ Handles source and configuration changes reactively\n+ Relies on the\n  [Barcode Detection API](https://developer.mozilla.org/en-US/docs/Web/API/Barcode_Detection_API)\n  or on any available polyfill\n+ Detects all barcodes that\n  [the underlying `BarcodeDetector`](https://developer.mozilla.org/en-US/docs/Web/API/Barcode_Detection_API#supported_barcode_formats)\n  or polyfill supports\n+ Adapts the scanning frequency automatically to stay below a configurable processing load limit\n\nTry these features on this [online example](https://undecaf.github.io/vue-barcode-scanner/example/)\n([source code](https://github.com/undecaf/vue-barcode-scanner/blob/master/example)\nwith build scripts for Rollup, esbuild and Webpack/Vue CLI).\n\n\n## Contents\n\n+ [Installation](#installation)\n  + [As ES module](#as-es-module)\n  + [As plain `\u003cscript\u003e`](#as-plain-script)\n  + [Polyfilling `BarcodeDetector`](#polyfilling-barcodedetector)\n+ [Usage](#usage)\n  + [Source element](#source-element)\n  + [Attributes](#attributes)\n    + [`source`](#source)\n    + [`formats`](#formats)\n    + [`mask-css`](#mask-css)\n    + [`highlight-css`](#highlight-css)\n    + [`scanning`](#scanning)\n    + [`rate`](#rate)\n    + [`debug`](#debug)\n  + [Getting results: events](#getting-results-events)\n    + [`bcs-scanned`](#bcs-scanned)\n    + [`bcs-started`](#bcs-started)\n    + [`bcs-stopped`](#bcs-stopped)\n    + [`bcs-error`](#bcs-error)\n+ [License](#license)\n\n  \n## Installation\n\n### As ES module\n\n```shell script\n$ npm install @undecaf/vue-barcode-scanner\n    or\n$ yarn add @undecaf/vue-barcode-scanner\n```\n\nThen `import BarcodeScanner from '@undecaf/vue-barcode-scanner'` where required and place as\n`\u003cbarcode-scanner\u003e` in your template. [This CodePen](https://codepen.io/undecaf/pen/xxXBapJ)\ndemonstrates the scanner in a Vue SFC.\n\n\n### As plain `\u003cscript\u003e`\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@undecaf/vue-barcode-scanner/dist/index.js\"\u003e\u003c/script\u003e\n```\n\nThis exposes the component options object as `barcodeScanner.default`.\n[This CodePen](https://codepen.io/undecaf/pen/wvrOOEZ) shows the scanner in a Vue `\u003cscript\u003e`.\n\n\n### Polyfilling `BarcodeDetector`\n\n`BarcodeScanner` relies on the [Barcode Detection API](https://developer.mozilla.org/en-US/docs/Web/API/Barcode_Detection_API)\nto do its work. For [browsers that do not yet implement this API](https://caniuse.com/mdn-api_barcodedetector),\na polyfill will be required.\n\nThe following snippets use\n[`@undecaf/barcode-detector-polyfill`](https://www.npmjs.com/package/@undecaf/barcode-detector-polyfill)\n(written by the same author as this component) as an example.\n\nPolyfill if necessary in an ES module (also shown in [this CodePen](https://codepen.io/undecaf/pen/xxXBapJ)):\n\n```javascript\nimport { BarcodeDetectorPolyfill } from '@undecaf/barcode-detector-polyfill'\n\ntry {\n    window['BarcodeDetector'].getSupportedFormats()\n} catch {\n    window['BarcodeDetector'] = BarcodeDetectorPolyfill\n}\n    ⁝\n```\n\nIn a plain `\u003cscript\u003e` (shown in [this CodePen](https://codepen.io/undecaf/pen/wvrOOEZ)):\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@undecaf/zbar-wasm/dist/index.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@undecaf/barcode-detector-polyfill/dist/index.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n    try {\n        window['BarcodeDetector'].getSupportedFormats()\n    } catch {\n        window['BarcodeDetector'] = barcodeDetectorPolyfill.BarcodeDetectorPolyfill\n    }\n        ⁝\n\u003c/script\u003e\n```\n\n\n## Usage\n\n### Source element\n\n`BarcodeScanner` needs an image or video source that is to be scanned for barcodes.\nThis can be an `\u003cimg\u003e`, `\u003ccanvas\u003e` or `\u003cvideo\u003e` element, or a container or a Vue component\nhaving one of these elements as descendant (for other source types, see the [`source` attribute](#source)).\nFor example:\n\n```html\n\u003cbarcode-scanner ...\u003e\n  \u003cvideo ...\u003e\u003c/video\u003e\n\u003c/barcode-scanner\u003e\n```\n\nThe source element/container must be the only child of `\u003cbarcode-scanner\u003e`.\nIf located inside a container then `\u003cimg\u003e`/`\u003ccanvas\u003e`/`\u003cvideo\u003e` must cover that container exactly \nin order for [masks](#mask-css) and [barcode highlights](#highlight-css) to appear in correct positions.\nThe [`source` attribute](#source) may specify a CSS selector for a particular source element inside the container.\n\nThe source element and its `src` and `srcObject` attributes are reactive, i.e. changed content\nis scanned automatically. Video sources are scanned repeatedly while being played.\nTo scan animated `\u003ccanvas\u003e` content, [capture it as `MediaStream`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/captureStream)\nand pass that to the [`source` attribute](#source).\n\n\n### Attributes\n\nAll attributes are reactive. Try them in the [example project](https://undecaf.github.io/vue-barcode-scanner/example/)!\n\n+ \u003ca name=\"source\"\u003e`source`\u003c/a\u003e: the image/video source that is to be shown/played inside `\u003cbarcode-scanner\u003e`\n  and that is to be scanned for barcodes.\n  Must be specified if `\u003cbarcode-scanner\u003e` does not contain a [source element](#source-element).\n\n  May be any of:\n  + [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)\n    and [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File)\n    with any `image/*` or `video/*` type supported by the browser\n  + [`MediaStream`](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream)\n  + [`ImageData`](https://developer.mozilla.org/en-US/docs/Web/API/ImageData/ImageData)\n  + [`ImageBitmap`](https://developer.mozilla.org/en-US/docs/Web/API/ImageBitmap)\n  + [`OffscreenCanvas`](https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas)\n\n  `MediaStream` and `video/*` `Blob`s/`File`s are scanned repeatedly while being played, see [`rate`](#rate) below.\n\n  If the [source element](#source-element) is a container with multiple `\u003cimg\u003e`, `\u003ccanvas\u003e` or `\u003cvideo\u003e`\n  elements then `source` must be a \n  [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors)\n  that selects one of them.\n\n+ \u003ca name=\"formats\"\u003e`formats`\u003c/a\u003e (optional): a string array of the barcode formats to be detected. Getting the available formats:\n\n  ```javascript\n  const formats = await BarcodeDetector.getSupportedFormats()\n  ```\n  \n  If this attribute is omitted then all supported formats will be detected.\n\n+ \u003ca name=\"mask-css\"\u003e`mask-css`\u003c/a\u003e (optional): the CSS class(es) for a `\u003cdiv\u003e` that overlays the source and defines \n  a reduced scanning area.\n  Only content inside the border box of that `\u003cdiv\u003e` will be scanned if this attribute is specified.\n  This can increase performance considerably.\n\n  The `\u003cdiv\u003e` is managed by the `BarcodeScanner` component. `position:absolute` is enforced, and coordinates and dimensions\n  should be specified as `%` of the source size. For example:\n\n  ```css\n  .centered-mask {  /* centered, 50% of source width, 80% of source height */\n    left: 25%;\n    top: 10%;\n    width: 50%;\n    height: 80%;\n    box-shadow: 0 0 0 10000px rgba(0, 0, 0, 0.4);  /* dims the surrounding area */\n  }\n  ```\n  \n  CSS class `.detected` is added to the `\u003cdiv\u003e` automatically if any barcode was detected.\n  The names of the detected barcode `format`s (in original spelling and in kebab case)\n  are also added as CSS classes. This allows visual feedback on detection, for example:\n\n  ```css\n  .centered-mask.detected {   /* green border on barcode detection */\n    border: rgb(128, 255, 128) solid 3px;\n  }\n  \n  .centered-mask.qr-code::before {    /* shows the detected format as text */\n    content: \"It's a QR code!\";\n    display: block;\n    text-align: center;\n    color: rgb(255, 255, 255);\n    background-color: rgb(128, 255, 128);\n  }\n  ```\n  \n  More examples can be found in the [mask style examples](https://github.com/undecaf/vue-barcode-scanner/blob/master/example/src/css/mask.css).\n\n+ \u003ca name=\"highlight-css\"\u003e`highlight-css`\u003c/a\u003e (optional): the CSS class(es) for the `\u003cdiv\u003e`s that each enclose a detected barcode. \n  These `\u003cdiv\u003e`s are placed and sized automatically, therefore the CSS styles must not affect their position and size.\n  For example:\n\n  ```css\n  .simple-highlight {   /* blue border and translucent blue background */\n    border: rgb(64, 64, 255) solid 2px;\n    background-color: rgba(64, 64, 255, 0.3);\n  }\n  ```\n  \n  Each `\u003cdiv\u003e` also receives the name of the respective barcode `format` (in original spelling and in kebab case)\n  as additional CSS classes. This allows format-specific highlighting, for example:\n\n  ```css\n  .simple-highlight.code-39 {   /* highlights code 39 barcodes in red */\n    border-color: rgb(255, 64, 64);\n    background-color: rgba(255, 64, 64, 0.3);\n  }\n  ```\n  \n  More examples can be found in the [highlight style examples](https://github.com/undecaf/vue-barcode-scanner/blob/master/example/src/css/highlight.css).\n\n  If this property is omitted then detected barcodes will be enclosed in a green (`#80ff80`) border.\n  To disable highlighting entirely, set `:highlight-css=\"null\"`.\n\n+ \u003ca name=\"scanning\"\u003e`scanning`\u003c/a\u003e (optional): as a `boolean` input, starts and stops scanning; as a`boolean` output,\n  indicates whether scanning is in progress. In order to work in this bidirectional mode, a _variable_ must be bound \n  to this attribute with the\n  [`.sync` modifier](https://vuejs.org/v2/guide/components-custom-events.html#sync-Modifier).\n\n  Usually this attribute is not needed because scanning starts automatically whenever the source, \n  [`formats`](#formats) or [`mask-css`](#mask-css) changes.\n\n+ \u003ca name=\"rate\"\u003e`rate`\u003c/a\u003e (optional): the desired scans per second as a string like `15/s`, or the JavaScript\n  processing load limit for repeated scanning as a string like `50%`. The numbers must be integers.\n\n  If missing or invalid then `rate` defaults to `20/s`.\n\n+ \u003ca name=\"debug\"\u003e`debug`\u003c/a\u003e (optional): if `true` then debug messages and events are logged at the console; defaults to `false`.\n  This impacts performance, not recommended for production. \n\n\n### Getting results: events\n\n+ \u003ca name=\"bcs-scanned\"\u003e`bcs-scanned`\u003c/a\u003e: emitted after each scan cycle, regardless of whether a barcode was detected or not.\n  Detected barcodes are passed as an array of objects in the event payload, one element per barcode.\n  Each object has the following properties\n  ([see here for details](https://developer.mozilla.org/en-US/docs/Web/API/BarcodeDetector/detect#return_value)):\n\n  + `format`: the detected barcode format (one of the specified [`formats`](#formats))\n  + `rawValue`: the decoded barcode, always a `string` decoded from raw data\n  + `boundingBox`: the [`DOMRectReadOnly`](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly) enclosing the\n    barcode in the `source`\n  + `cornerPoints`: an arry of four `{x, y}` pairs in clockwise order, representing four corner points of the detected barcode.\n    `BarcodeDetectorPolyfill` returns the `boundingBox` corner points.\n\n  Additional properties may be returned by `BarcodeDetector` polyfills.\n\n+ \u003ca name=\"bcs-started\"\u003e`bcs-started`\u003c/a\u003e: signals that scanning has started automatically or as requested by \n  [`scanning`](#scanning) and that one (for an image source)\n  or several (for a video source) [`bcs-scanned`](#bcs-scanned) events are to be expected.\n\n+ \u003ca name=\"bcs-stopped\"\u003e`bcs-stopped`\u003c/a\u003e: emitted after an image source was scanned once or when repeated scanning of a video source\n  stopped because the video stopped playing or as requested by [`scanning`](#scanning).\n\n+ \u003ca name=\"bcs-error\"\u003e`bcs-error`\u003c/a\u003e: indicates an error with the details passed as event payload.\n  \n\nIf desired then the names of the events described above can be imported as constants:\n\n```javascript\nimport { SCANNED_EVENT, STARTED_EVENT, STOPPED_EVENT, ERROR_EVENT } from 'undecaf/vue-barcode-scanner'\n```\n\nIn a [plain script](#as-plain-script), these constants are named `barcodeScanner.SCANNED_EVENT` etc. \n\n## License\n\nSoftware: [MIT](http://opensource.org/licenses/MIT)\n\nDocumentation: [CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fundecaf%2Fvue-barcode-scanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fundecaf%2Fvue-barcode-scanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fundecaf%2Fvue-barcode-scanner/lists"}