{"id":21660174,"url":"https://github.com/EddyVerbruggen/nativescript-barcodescanner","last_synced_at":"2025-07-17T23:31:01.533Z","repository":{"id":33535116,"uuid":"37181227","full_name":"EddyVerbruggen/nativescript-barcodescanner","owner":"EddyVerbruggen","description":"🔎 NativeScript QR / barcode (bulk)scanner plugin","archived":false,"fork":false,"pushed_at":"2023-04-16T14:52:17.000Z","size":16165,"stargazers_count":293,"open_issues_count":59,"forks_count":73,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-11-21T11:51:24.472Z","etag":null,"topics":["barcode","barcode-scanner","ean13","ean8","nativescript","nativescript-plugin","qr-code"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/EddyVerbruggen.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}},"created_at":"2015-06-10T07:06:28.000Z","updated_at":"2024-09-10T21:36:50.000Z","dependencies_parsed_at":"2022-09-06T23:31:09.243Z","dependency_job_id":null,"html_url":"https://github.com/EddyVerbruggen/nativescript-barcodescanner","commit_stats":{"total_commits":234,"total_committers":22,"mean_commits":"10.636363636363637","dds":0.1709401709401709,"last_synced_commit":"eafe2657c871055d3947f9e4cf7b9e09d100e30f"},"previous_names":[],"tags_count":62,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-barcodescanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-barcodescanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-barcodescanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-barcodescanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EddyVerbruggen","download_url":"https://codeload.github.com/EddyVerbruggen/nativescript-barcodescanner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226306104,"owners_count":17603932,"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","barcode-scanner","ean13","ean8","nativescript","nativescript-plugin","qr-code"],"created_at":"2024-11-25T09:32:25.239Z","updated_at":"2024-11-25T09:34:25.882Z","avatar_url":"https://github.com/EddyVerbruggen.png","language":"TypeScript","funding_links":[],"categories":["Awesome {N} [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)","TypeScript"],"sub_categories":["Table of Contents"],"readme":"# NativeScript BarcodeScanner\n\n[![Build Status][build-status]][build-url]\n[![NPM version][npm-image]][npm-url]\n[![Downloads][downloads-image]][npm-url]\n[![Twitter Follow][twitter-image]][twitter-url]\n\n[build-status]:https://travis-ci.org/EddyVerbruggen/nativescript-barcodescanner.svg?branch=master\n[build-url]:https://travis-ci.org/EddyVerbruggen/nativescript-barcodescanner\n[npm-image]:http://img.shields.io/npm/v/nativescript-barcodescanner.svg\n[npm-url]:https://npmjs.org/package/nativescript-barcodescanner\n[downloads-image]:http://img.shields.io/npm/dm/nativescript-barcodescanner.svg\n[twitter-image]:https://img.shields.io/twitter/follow/eddyverbruggen.svg?style=social\u0026label=Follow%20me\n[twitter-url]:https://twitter.com/eddyverbruggen\n\n\u003e 💡 Plugin version 4.0.0+ is compatible with NativeScript 7+. If you need to target older NativeScript versions, please stick to plugin version 3.4.2.\n\n\u003e ⚠️ With 4.1.0+ you can use `beepOnScan` on iOS again (it used to crash in older 4.x versions).\n\n## Want a quick demo?\n\n\u003e Note that running this only makes sense on a real device.\n\n```bash\ngit clone https://github.com/EddyVerbruggen/nativescript-barcodescanner barcodedemo\ncd barcodedemo/src\n```\n\n#### Fullscreen, programmatically (iOS and Android)\n\n```bash\nnpm run demo.android (or demo.ios / demo.ios.device)\n```\n\n#### Embedded (iOS only)\n\n```bash\nnpm run demo.ios\n```\n\n## Supported barcode types\n\n### iOS and Android\n* CODE_39\n* CODE_93\n* CODE_128\n* DATA_MATRIX\n* EAN_8\n* EAN_13\n* ITF (also known as ITF14)\n* PDF_417 (on Android only when passed in explicity via `formats`)\n* QR_CODE\n* UPC_A\n* UPC_E\n\n### Android only\n* CODABAR\n* MAXICODE\n* RSS_14\n\n### iOS only\n* AZTEC\n* CODE_39_MOD_43\n* INTERLEAVED_2_OF_5\n\n### A note about `UPC_A` and `EAN_13`\nWhen either (or both) of these are specified, both can be returned.\nYou can check the actual type by inspecting the `format` property of the result object.\nFor details, see [#176](https://github.com/EddyVerbruggen/nativescript-barcodescanner/issues/176).\n\n## Installation\nFrom the command prompt go to your app's root folder and execute:\n```\ntns plugin add nativescript-barcodescanner\n```\n\n## Embedding the scanner (iOS)\n\n\u003e If you need to embed the scanner for Android as well, please consider using the Machine Learning powered Barcode scanner I've added to the [ML Kit feature of the NativeScript Firebase plugin](https://github.com/EddyVerbruggen/nativescript-plugin-firebase/blob/master/docs/ML_KIT.md#barcode-scanning)!\n\n\u003cimg src=\"docs/ios_embedded_scanner.png\" width=\"281px\"/\u003e\n\nAs you can see, you can style the view any way you like, and even overlay it with an image or button.\nTo recreate the layout above, look at [these lines in the demo app](https://github.com/EddyVerbruggen/nativescript-barcodescanner/blob/23395bec3e5a26622146daea96dd6407a8413f70/demo/app/main-page.xml#L17-L31).\n\n\u003e 💡 TIP: If you don't destroy the component/page which embed the scanner (but instead show a modal, or navigate \"forward\") you can \"pause\" the scanner (since plugin version 3.4.0). Simply set that `pause` property to `true` when applicable.\n \n### XML\n```xml\n\u003cPage xmlns=\"http://schemas.nativescript.org/tns.xsd\" xmlns:Barcode=\"nativescript-barcodescanner\"\u003e\n```\n\nHere's an example tag, showing all currently supported options. The property defaults are equal to the `scan` function.\n\n```xml\n\u003ciOS\u003e\n    \u003cBarcode:BarcodeScannerView\n      class=\"scanner-round\"\n      formats=\"QR_CODE, EAN_13\"\n      beepOnScan=\"true\"\n      reportDuplicates=\"true\"\n      preferFrontCamera=\"false\"\n      pause=\"{{ pause }}\"\n      scanResult=\"{{ onScanResult }}\" /\u003e\n\u003c/iOS\u003e\n```\n\n### Embedding in Angular\nComponent / Module:\n\n```typescript\nimport { registerElement } from \"nativescript-angular/element-registry\";\nregisterElement(\"BarcodeScanner\", () =\u003e require(\"nativescript-barcodescanner\").BarcodeScannerView);\n```\n\nView:\n\n```html\n\u003cBarcodeScanner\n      class=\"scanner-round\"\n      formats=\"QR_CODE, EAN_13\"\n      beepOnScan=\"true\"\n      reportDuplicates=\"true\"\n      preferFrontCamera=\"false\"\n      [pause]=\"pause\"\n      (scanResult)=\"onScanResult($event)\"\u003e\n\u003c/BarcodeScanner\u003e\n```\n\n### Embedding in Vue\nmain.ts:\n\n```typescript\nVue.registerElement('BarcodeScanner', () =\u003e require('nativescript-barcodescanner').BarcodeScannerView)\n```\n\nView:\n\n```html\n\u003cBarcodeScanner\n    row=\"1\"\n    height=\"300\"\n    formats=\"QR_CODE, EAN_13, UPC_A\"\n    beepOnScan=\"true\"\n    reportDuplicates=\"true\"\n    preferFrontCamera=\"false\"\n    :pause=\"pause\"\n    @scanResult=\"onScanResult\"\n    v-if=\"isIOS\"\u003e\n\u003c/BarcodeScanner\u003e\n```\n\nSee 'demo-vue' for details.\n\n## iOS runtime permission reason\nYou've probably seen a permission popup like this before (this plugin will trigger one as well, automatically):\n\n\u003cimg src=\"docs/ios_permission_custom_reason.png\" width=\"271px\" height=\"167px\"/\u003e\n\niOS 10+ requires not only this popup, but also a _reason_. In this case it's \"We'd like to use the Camera ..\".\n\nYou can provide your own reason for accessing the camera by adding something like this to `app/App_Resources/ios/Info.plist`:\n\n```xml\n  \u003ckey\u003eNSCameraUsageDescription\u003c/key\u003e\n  \u003cstring\u003eMy reason justifying fooling around with your camera\u003c/string\u003e\n```\n\n_To not crash your app in case you forgot to provide the reason this plugin adds an empty reason to the `.plist` during build. This value gets overridden by anything you specify yourself._\n\n## Usage\nTip: during a scan you can use the volume up/down buttons to toggle the torch.\n\n### function: scan (single mode)\n\n#### TypeScript\n\n```typescript\n  import { BarcodeScanner } from \"nativescript-barcodescanner\";\n  let barcodescanner = new BarcodeScanner();\n\n  barcodescanner.scan({\n    formats: \"QR_CODE, EAN_13\",\n    cancelLabel: \"EXIT. Also, try the volume buttons!\", // iOS only, default 'Close'\n    cancelLabelBackgroundColor: \"#333333\", // iOS only, default '#000000' (black)\n    message: \"Use the volume buttons for extra light\", // Android only, default is 'Place a barcode inside the viewfinder rectangle to scan it.'\n    showFlipCameraButton: true,   // default false\n    preferFrontCamera: false,     // default false\n    showTorchButton: true,        // default false\n    beepOnScan: true,             // Play or Suppress beep on scan (default true)\n    fullScreen: true,             // Currently only used on iOS; with iOS 13 modals are no longer shown fullScreen by default, which may be actually preferred. But to use the old fullScreen appearance, set this to 'true'. Default 'false'.\n    torchOn: false,               // launch with the flashlight on (default false)\n    closeCallback: () =\u003e { console.log(\"Scanner closed\")}, // invoked when the scanner was closed (success or abort)\n    resultDisplayDuration: 500,   // Android only, default 1500 (ms), set to 0 to disable echoing the scanned text\n    orientation: orientation,     // Android only, default undefined (sensor-driven orientation), other options: portrait|landscape\n    openSettingsIfPermissionWasPreviouslyDenied: true, // On iOS you can send the user to the settings app if access was previously denied\n    presentInRootViewController: true // iOS-only; If you're sure you're not presenting the (non embedded) scanner in a modal, or are experiencing issues with fi. the navigationbar, set this to 'true' and see if it works better for your app (default false).\n  }).then((result) =\u003e {\n      // Note that this Promise is never invoked when a 'continuousScanCallback' function is provided\n      alert({\n        title: \"Scan result\",\n        message: \"Format: \" + result.format + \",\\nValue: \" + result.text,\n        okButtonText: \"OK\"\n      });\n    }, (errorMessage) =\u003e {\n      console.log(\"No scan. \" + errorMessage);\n    }\n  );\n```\n\n\u003e Note that `result.format` above is one of [these](https://github.com/EddyVerbruggen/nativescript-barcodescanner/blob/241411a14f89171309bb94f3ca6da3bb45433e5e/src/barcodescanner-common.ts#L5).\n\n#### JavaScript\n```js\n  var BarcodeScanner = require(\"nativescript-barcodescanner\").BarcodeScanner;\n  var barcodescanner = new BarcodeScanner();\n\n  barcodescanner.scan({\n    formats: \"QR_CODE,PDF_417\",   // Pass in of you want to restrict scanning to certain types\n    cancelLabel: \"EXIT. Also, try the volume buttons!\", // iOS only, default 'Close'\n    cancelLabelBackgroundColor: \"#333333\", // iOS only, default '#000000' (black)\n    message: \"Use the volume buttons for extra light\", // Android only, default is 'Place a barcode inside the viewfinder rectangle to scan it.'\n    showFlipCameraButton: true,   // default false\n    preferFrontCamera: false,     // default false\n    showTorchButton: true,        // default false\n    beepOnScan: true,             // Play or Suppress beep on scan (default true)\n    fullScreen: true,             // Currently only used on iOS; with iOS 13 modals are no longer shown fullScreen by default, which may be actually preferred. But to use the old fullScreen appearance, set this to 'true'. Default 'false'.\n    torchOn: false,               // launch with the flashlight on (default false)\n    closeCallback: function () { console.log(\"Scanner closed\"); }, // invoked when the scanner was closed (success or abort)\n    resultDisplayDuration: 500,   // Android only, default 1500 (ms), set to 0 to disable echoing the scanned text\n    orientation: \"landscape\",     // Android only, optionally lock the orientation to either \"portrait\" or \"landscape\"\n    openSettingsIfPermissionWasPreviouslyDenied: true // On iOS you can send the user to the settings app if access was previously denied\n  }).then(\n      function(result) {\n        console.log(\"Scan format: \" + result.format);\n        console.log(\"Scan text:   \" + result.text);\n      },\n      function(error) {\n        console.log(\"No scan: \" + error);\n      }\n  );\n```\n\n### function: scan (bulk / continuous mode)\nIn this mode the scanner will continuously report scanned codes back to your code,\nbut it will only be dismissed if the user tells it to, or you call `stop` programmatically.\n\nThe plugin handles duplicates for you so don't worry about checking those;\nevery result withing the same scan session is unique unless you set `reportDuplicates` to `true`.\n\nHere's an example of scanning 3 unique QR codes and then stopping scanning programmatically.\nYou'll notice that the Promise will no longer receive the result as there may be many results:\n\n#### JavaScript\n```js\n  var count = 0;\n  barcodescanner.scan({\n    formats: \"QR_CODE\",\n    // this callback will be invoked for every unique scan in realtime!\n    continuousScanCallback: function (result) {\n      count++;\n      console.log(result.format + \": \" + result.text + \" (count: \" + count + \")\");\n      if (count === 3) {\n        barcodescanner.stop();\n      }\n    },\n    closeCallback: function () { console.log(\"Scanner closed\"); }, // invoked when the scanner was closed\n    reportDuplicates: false // which is the default\n  }).then(\n      function() {\n        console.log(\"We're now reporting scan results in 'continuousScanCallback'\");\n      },\n      function(error) {\n        console.log(\"No scan: \" + error);\n      }\n  );\n```\n\n### function: available\nNote that the iOS implementation will always return `true` at the moment,\non Android we actually check for a camera to be available.\n\n#### JavaScript\n```js\n  var barcodescanner = require(\"nativescript-barcodescanner\");\n\n  barcodescanner.available().then(\n      function(avail) {\n        console.log(\"Available? \" + avail);\n      }\n  );\n```\n\n### function: hasCameraPermission / requestCameraPermission\nOn Android 6+ you need to request permission to use the camera at runtime when targeting API level 23+.\nEven if the `uses-permission` tag for the Camera is present in `AndroidManifest.xml`.\n\nOn iOS 10+ there's something similar going on.\n\nSince version 1.5.0 you can let the plugin handle this for you\n(if need be a prompt will be shown to the user when the scanner launches),\nbut if for some reason you want to handle permissions yourself you can use these functions.\n\n#### JavaScript\n```js\n  barcodescanner.hasCameraPermission().then(\n      function(granted) {\n        // if this is 'false' you probably want to call 'requestCameraPermission' now\n        console.log(\"Has Camera Permission? \" + result);\n      }\n  );\n\n  // if no permission was granted previously this wil open a user consent screen\n  barcodescanner.requestCameraPermission().then(\n      function() {\n        console.log(\"Camera permission requested\");\n      }\n  );\n```\n\n### Usage with `nativescript-angular`\n\nYou may have injected the `BarcodeScanner` class in your component constructor in the past,\nbut please don't do that anymore because in release builds you may experience a crash.\n\nSo instead of:\n\n```typescript\n// my-component.ts\nimport { Component, Inject } from '@angular/core';\nimport { BarcodeScanner } from 'nativescript-barcodescanner';\n\n@Component({ ... })\n  export class MyComponent {\n    constructor(private barcodeScanner: BarcodeScanner) {\n  }\n\n  //use the barcodescanner wherever you need it. See general usage above.\n  scanBarcode() {\n    this.barcodeScanner.scan({ ... });\n  }\n}\n```\n\nSimply do:\n\n```typescript\n// my-component.ts\nimport { Component, Inject } from '@angular/core';\nimport { BarcodeScanner } from 'nativescript-barcodescanner';\n\n@Component({ ... })\n  //use the barcodescanner wherever you need it. See general usage above.\n  scanBarcode() {\n    new BarcodeScanner().scan({ ... });\n  }\n}\n```\n\n#### Webpack usage\nIf you run into an error when Webpacking, open `app.module.ts` and add this:\n\n```typescript\nimport { BarcodeScanner } from \"nativescript-barcodescanner\";\n\nexport function createBarcodeScanner() {\n  return new BarcodeScanner();\n}\n\nproviders: [\n  { provide: BarcodeScanner, useFactory: (createBarcodeScanner) }\n]\n```\n\n## Troubleshooting\nIf you get the error `TypeError: Cannot read property 'zxing' of undefined` on android, try the following steps:\n1. Delete the app from your device\n2. Remove the folder `platforms/android`. This triggers a complete rebuild\n3. run `tns run android`\n\n## Dependencies / Related Projects\n\nThis plugin wraps libaries for Android and iOS to make the barcode scanner easily accessible via a unified API. The Libraries used are:\n\n### iOS\n\nCustom Framework to access iOS APIs: https://github.com/EddyVerbruggen/ios-framework-barcodescanner\n\n### Android\n\nZXing: https://github.com/zxing/zxing/releases\n\nAs using that library as a direct dependency was not practical, there is a library-project that adopts the sources from ZXing and copiles them into a AAR for usage on android: https://github.com/EddyVerbruggen/barcodescanner-lib-aar/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEddyVerbruggen%2Fnativescript-barcodescanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEddyVerbruggen%2Fnativescript-barcodescanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEddyVerbruggen%2Fnativescript-barcodescanner/lists"}