@uniplat/html5-qrcode
Advanced tools
If interested, please reach out at minhazav@gmail.com.
Important The project is in maintenance mode until further notice. The author shall not be able to make any bug fixes or improvements for the time-being. Pull requests also won't be merged for the timebeing. If you have a fork you can maintain - please share the details to minhazav@gmail.com. I am happy to advertise them here! Ok to use the project as is. Example: scanapp.org.
Use this lightweight library to easily / quickly integrate QR code, bar code, and other common code scanning capabilities to your web application.
🔲 Support scanning different types of bar codes and QR codes.
🖥 Supports different platforms be it Android, IOS, MacOs, Windows or Linux
🌐 Supports different browsers like Chrome, Firefox, Safari, Edge, Opera ...
📷 Supports scanning with camera as well as local files
➡️ Comes with an end to end library with UI as well as a low level library to build your own UI with.
🔦 Supports customisations like flash/torch support, zooming etc.
Supports two kinds of APIs
Html5QrcodeScanner — End-to-end scanner with UI, integrate with less than ten lines of code.
Html5Qrcode — Powerful set of APIs you can use to build your UI without worrying about camera setup, handling permissions, reading codes, etc.
Support for scanning local files on the device is a new addition and helpful for the web browser which does not support inline web-camera access in smartphones. Note: This doesn't upload files to any server — everything is done locally.
 |  |
|---|---|
| Demo at scanapp.org | Demo at qrcode.minhazav.dev - Scanning different types of codes |
Help incentivise feature development, bug fixing by supporting the sponsorhip goals of this project. See list of sponsered feature requests here.
The documentation for this project has been moved to scanapp.org/html5-qrcode-docs.
We are working continuously on adding support for more and more platforms. If you find a platform or a browser where the library is not working, please feel free to file an issue. Check the demo link to test it out.
Legends
Means full support — inline webcam and file based
Means partial support — only file based, webcam in progress Firefox |  Chrome |  Safari |  Opera |  Edge |
|---|---|---|---|---|
| | | | |
Chrome | Firefox | Edge | Opera |  Opera Mini |  UC |
|---|---|---|---|---|---|
| | | | | |
Safari | Chrome | Firefox | Edge |
|---|---|---|---|
| * | * | |
* Supported for IOS versions >= 15.1
Before version 15.1, Webkit for IOS is used by Chrome, Firefox, and other browsers in IOS and they do not have webcam permissions yet. There is an ongoing issue on fixing the support for iOS - issue/14
The library can be easily used with several other frameworks, I have been adding examples for a few of them and would continue to add more.
 |  |  |  |  |
|---|---|---|---|---|
| Html5 | VueJs | ElectronJs | React | Lit |
Code scanning is dependent on Zxing-js library. We will be working on top of it to add support for more types of code scanning. If you feel a certain type of code would be helpful to have, please file a feature request.
| Code | Example |
|---|---|
| QR Code |  |
| AZTEC |  |
| CODE_39 |  |
| CODE_93 |  |
| CODE_128 |  |
| ITF |  |
| EAN_13 |  |
| EAN_8 |  |
| PDF_417 |  |
| UPC_A |  |
| UPC_E |  |
| DATA_MATRIX |  |
| MAXICODE* |  |
| RSS_14* |  |
| RSS_EXPANDED* |  |
*Formats are not supported by our experimental integration with native BarcodeDetector API integration (Read more).
See an end to end scanner experience at scanapp.org.
This is a cross-platform JavaScript library to integrate QR code, bar codes & a few other types of code scanning capabilities to your applications running on HTML5 compatible browser.
Supports:
Find detailed guidelines on how to use this library on scanapp.org/html5-qrcode-docs.
Scan this image or visit blog.minhazav.dev/research/html5-qrcode.html
Check these articles on how to use this library:
Figure: Screenshot from Google Chrome running on MacBook Pro
Find the full API documentation at scanapp.org/html5-qrcode-docs/docs/apis.
configuration in start() methodConfiguration object that can be used to configure both the scanning behavior and the user interface (UI). Most of the fields have default properties that will be used unless a different value is provided. If you do not want to override anything, you can just pass in an empty object {}.
fps — Integer, Example = 10A.K.A frame per second, the default value for this is 2, but it can be increased to get faster scanning. Increasing too high value could affect performance. Value >1000 will simply fail.
qrbox — QrDimensions or QrDimensionFunction (Optional), Example = { width: 250, height: 250 }Use this property to limit the region of the viewfinder you want to use for scanning. The rest of the viewfinder would be shaded. For example, by passing config { qrbox : { width: 250, height: 250 } }, the screen will look like:
This can be used to set a rectangular scanning area with config like:
let config = { qrbox : { width: 400, height: 150 } }
This config also accepts a function of type
/**
* A function that takes in the width and height of the video stream
* and returns QrDimensions.
*
* Viewfinder refers to the video showing camera stream.
*/
type QrDimensionFunction =
(viewfinderWidth: number, viewfinderHeight: number) => QrDimensions;
This allows you to set dynamic QR box dimensions based on the video dimensions. See this blog article for example: Setting dynamic QR box size in Html5-qrcode - ScanApp blog
This might be desirable for bar code scanning.
If this value is not set, no shaded QR box will be rendered and the scanner will scan the entire area of video stream.
aspectRatio — Float, Example 1.777778 for 16:9 aspect ratioUse this property to render the video feed in a certain aspect ratio. Passing a nonstandard aspect ratio like 100000:1 could lead to the video feed not even showing up. Ideal values can be:
| Value | Aspect Ratio | Use Case |
|---|---|---|
| 1.333334 | 4:3 | Standard camera aspect ratio |
| 1.777778 | 16:9 | Full screen, cinematic |
| 1.0 | 1:1 | Square view |
If you do not pass any value, the whole viewfinder would be used for scanning.
Note: this value has to be smaller than the width and height of the QR code HTML element.
disableFlip — Boolean (Optional), default = falseBy default, the scanner can scan for horizontally flipped QR Codes. This also enables scanning QR code using the front camera on mobile devices which are sometimes mirrored. This is false by default and I recommend changing this only if:
Here's an example of a normal and mirrored QR Code
| Normal QR Code | Mirrored QR Code |
|---|---|
|  |
rememberLastUsedCamera — Boolean (Optional), default = trueIf true the last camera used by the user and weather or not permission was granted would be remembered in the local storage. If the user has previously granted permissions — the request permission option in the UI will be skipped and the last selected camera would be launched automatically for scanning.
If true the library shall remember if the camera permissions were previously
granted and what camera was last used. If the permissions is already granted for
"camera", QR code scanning will automatically * start for previously used camera.
supportedScanTypes - Array<Html5QrcodeScanType> | []This is only supported for
Html5QrcodeScanner.
Default = [Html5QrcodeScanType.SCAN_TYPE_CAMERA, Html5QrcodeScanType.SCAN_TYPE_FILE]
This field can be used to:
Camera or File based scan.How to use:
function onScanSuccess(decodedText, decodedResult) {
// handle the scanned code as you like, for example:
console.log(`Code matched = ${decodedText}`, decodedResult);
}
let config = {
fps: 10,
qrbox: {width: 100, height: 100},
rememberLastUsedCamera: true,
// Only support camera scan type.
supportedScanTypes: [Html5QrcodeScanType.SCAN_TYPE_CAMERA]
};
let html5QrcodeScanner = new Html5QrcodeScanner(
"reader", config, /* verbose= */ false);
html5QrcodeScanner.render(onScanSuccess);
For file based scan only choose:
supportedScanTypes: [Html5QrcodeScanType.SCAN_TYPE_FILE]
For supporting both as it is today, you can ignore this field or set as:
supportedScanTypes: [
Html5QrcodeScanType.SCAN_TYPE_CAMERA,
Html5QrcodeScanType.SCAN_TYPE_FILE]
To set the file based scan as defult change the order:
supportedScanTypes: [
Html5QrcodeScanType.SCAN_TYPE_FILE,
Html5QrcodeScanType.SCAN_TYPE_CAMERA]
showTorchButtonIfSupported - boolean | undefinedThis is only supported for
Html5QrcodeScanner.
If true the rendered UI will have button to turn flash on or off based on device + browser support. The value is false by default.
By default, both camera stream and image files are scanned against all the
supported code formats. Both Html5QrcodeScanner and Html5Qrcode classes can
be configured to only support a subset of supported formats. Supported formats
are defined in
enum Html5QrcodeSupportedFormats.
enum Html5QrcodeSupportedFormats {
QR_CODE = 0,
AZTEC,
CODABAR,
CODE_39,
CODE_93,
CODE_128,
DATA_MATRIX,
MAXICODE,
ITF,
EAN_13,
EAN_8,
PDF_417,
RSS_14,
RSS_EXPANDED,
UPC_A,
UPC_E,
UPC_EAN_EXTENSION,
}
I recommend using this only if you need to explicitly omit support for certain formats or want to reduce the number of scans done per second for performance reasons.
Html5Qrcodeconst html5QrCode = new Html5Qrcode(
"reader", { formatsToSupport: [ Html5QrcodeSupportedFormats.QR_CODE ] });
const qrCodeSuccessCallback = (decodedText, decodedResult) => {
/* handle success */
};
const config = { fps: 10, qrbox: { width: 250, height: 250 } };
// If you want to prefer front camera
html5QrCode.start({ facingMode: "user" }, config, qrCodeSuccessCallback);
Html5QrcodeScannerfunction onScanSuccess(decodedText, decodedResult) {
// Handle the scanned code as you like, for example:
console.log(`Code matched = ${decodedText}`, decodedResult);
}
const formatsToSupport = [
Html5QrcodeSupportedFormats.QR_CODE,
Html5QrcodeSupportedFormats.UPC_A,
Html5QrcodeSupportedFormats.UPC_E,
Html5QrcodeSupportedFormats.UPC_EAN_EXTENSION,
];
const html5QrcodeScanner = new Html5QrcodeScanner(
"reader",
{
fps: 10,
qrbox: { width: 250, height: 250 },
formatsToSupport: formatsToSupport
},
/* verbose= */ false);
html5QrcodeScanner.render(onScanSuccess);
The library now supports some experimental features which are supported in the library but not recommended for production usage either due to limited testing done or limited compatibility for underlying APIs used. Read more about it here. Some experimental features include:
Code changes should only be made to /src only.
Run npm install to install all dependencies.
Run npm run-script build to build JavaScript output. The output JavaScript distribution is built to /dist/html5-qrcode.min.js. If you are developing on Windows OS, run npm run-script build-windows.
Testing
npm testSend a pull request
./src. Do not change ./dist manually.@all-contributors please add @mebjas for this new feature or tests
You can contribute to the project in several ways:
This project would not be possible without all of our fantastic contributors and sponsors. If you'd like to support the maintenance and upkeep of this project you can donate via GitHub Sponsors.
Sponsor the project for priortising feature requests / bugs relevant to you. (Depends on scope of ask and bandwidth of the contributors).
Help incentivise feature development, bug fixing by supporting the sponsorhip goals of this project. See list of sponsered feature requests here.
Also, huge thanks to following organizations for non monitery sponsorships
The decoder used for the QR code reading is from Zxing-js https://github.com/zxing-js/library
FAQs
A cross platform HTML5 QR Code & bar code scanner
We found that @uniplat/html5-qrcode demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.