{"id":15634711,"url":"https://github.com/paulmillr/qr","last_synced_at":"2025-05-15T10:03:02.985Z","repository":{"id":132468828,"uuid":"608684383","full_name":"paulmillr/qr","owner":"paulmillr","description":"Minimal 0-dep QR code generator \u0026 reader","archived":false,"fork":false,"pushed_at":"2025-05-14T12:21:31.000Z","size":219,"stargazers_count":212,"open_issues_count":4,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-14T12:54:28.878Z","etag":null,"topics":["qr","qr-code","qrcode","qrcode-generator","qrcode-reader","qrcode-scanner"],"latest_commit_sha":null,"homepage":"https://paulmillr.com/apps/qr/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulmillr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/funding.yml","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,"zenodo":null},"funding":{"github":"paulmillr"}},"created_at":"2023-03-02T14:28:41.000Z","updated_at":"2025-05-14T12:21:35.000Z","dependencies_parsed_at":"2023-12-23T16:12:19.515Z","dependency_job_id":"5dd66545-c70a-4b6a-87ac-a5703a29812e","html_url":"https://github.com/paulmillr/qr","commit_stats":{"total_commits":39,"total_committers":4,"mean_commits":9.75,"dds":0.07692307692307687,"last_synced_commit":"afff28ee80154207a3dda46ca552f1028a4f0fa6"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmillr%2Fqr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmillr%2Fqr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmillr%2Fqr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmillr%2Fqr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulmillr","download_url":"https://codeload.github.com/paulmillr/qr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254172369,"owners_count":22026644,"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":["qr","qr-code","qrcode","qrcode-generator","qrcode-reader","qrcode-scanner"],"created_at":"2024-10-03T10:56:00.179Z","updated_at":"2025-05-15T10:03:01.334Z","avatar_url":"https://github.com/paulmillr.png","language":"JavaScript","readme":"# paulmillr-qr\n\nMinimal 0-dep QR code generator \u0026 reader.\n\n- πŸ”’ Auditable, 0-dependency\n- 🏞️ Encoding (generating) supports ASCII, term, gif and svg codes\n- πŸ“· Decoding (reading) supports camera feed input, files and non-browser environments\n- πŸ” Extensive tests ensure correctness: 100MB+ of vectors\n- πŸͺΆ 35KB for encoding + decoding, 18KB for encoding (1000 lines of code)\n\nCheck out:\n\n- [paulmillr.com/apps/qr/](https://paulmillr.com/apps/qr/) - interactive demo\n- [qrBTF.com](https://qrbtf.com/en) - uses the library to generate custom, styled codes\n- [cuer](https://github.com/wevm/cuer) - React component based on the library\n- [metamask-sdk](https://github.com/MetaMask/metamask-sdk/blob/3d0ba19610853ec9259bb1aad459b1eaea799375/packages/sdk/package.json#L56) - is using the library\n\nWhy other libraries are less optimal:\n\n- [jsQR](https://github.com/cozmo/jsQR) is dead, [zxing-js](https://github.com/zxing-js/) is [dead](https://github.com/zxing-js/library/commit/b797504c25454db32aa2db410e6502b6db12a401), [qr-scanner](https://github.com/nimiq/qr-scanner/) uses jsQR and doesn't work outside of browser, [qcode-decoder](https://github.com/cirocosta/qcode-decoder) is broken version of jsQR and doesn't work outside of browser, [qrcode](https://github.com/nuintun/qrcode) is fork of jsQR without adoption\n- [instascan](https://github.com/schmich/instascan) is too big: over 1MB+ (it's zxing compiled to js via emscripten)\n\n## Usage\n\nA standalone file [qr.js](https://github.com/paulmillr/qr/releases) is also available.\n\n\u003e `npm install qr`\n\n\u003e `jsr add jsr:@paulmillr/qr`\n\n- [Encoding](#encoding)\n- [Decoding](#decoding)\n - [Decoding options](#decoding-options)\n - [Decoding algorithm](#decoding-algorithm)\n - [Decoding test vectors](#decoding-test-vectors)\n - [DOM helpers for web apps](#dom-helpers-for-web-apps)\n- [Using with Kotlin](#using-with-kotlin)\n- [Security](#security)\n- [Speed](#speed)\n\n## Encoding\n\n```ts\nimport encodeQR from 'qr';\n\n// import decodeQR from 'qr/decode';\n// See separate README section for decoding.\n\nconst txt = 'Hello world';\nconst ascii = encodeQR(txt, 'ascii'); // Not all fonts are supported\nconst terminalFriendly = encodeQR(txt, 'term'); // 2x larger, all fonts are OK\nconst gifBytes = encodeQR(txt, 'gif'); // Uncompressed GIF\nconst svgElement = encodeQR(txt, 'svg'); // SVG vector image element\nconst array = encodeQR(txt, 'raw'); // 2d array for canvas or other libs\n\n// Options\n// Custom error correction level\n// low: 7%, medium: 15% (default), quartile: 25%, high: 30%\nconst highErrorCorrection = encodeQR(txt, 'gif', { ecc: 'high' });\n// Custom encoding: 'numeric', 'alphanumeric' or 'byte'\nconst customEncoding = encodeQR(txt, 'gif', { encoding: 'byte' });\n// Default scale is 2: each block is 2x2 pixels.\nconst larger = encodeQR(txt, 'gif', { scale: 4 });\n// All options\n// type QrOpts = {\n// ecc?: 'low' | 'medium' | 'quartile' | 'high';\n// encoding?: 'numeric' | 'alphanumeric' | 'byte' | 'kanji' | 'eci';\n// version?: number; // 1..40, QR code version\n// mask?: number; // 0..7, mask number\n// border?: number; // Border size, default 2.\n// scale?: number; // Scale to this number. Scale=2 -\u003e each block will be 2x2 pixels\n// };\n\nconsole.log(ascii);\n\u003e β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ\n\u003e β–ˆβ–ˆ β–„β–„β–„β–„β–„ β–ˆ β–€β–„β–„β–ˆ β–ˆβ–ˆβ–€β–„β–„β–„β–„β–ˆ β–€β–ˆ β–„β–„β–„β–„β–„ β–ˆβ–ˆ\n\u003e β–ˆβ–ˆ β–ˆ β–ˆ β–ˆβ–€β–„β–€β–„ β–„β–„β–ˆβ–„β–ˆ β–ˆβ–ˆβ–€β–ˆβ–€β–€β–ˆ β–ˆ β–ˆ β–ˆβ–ˆ\n\u003e β–ˆβ–ˆ β–ˆβ–„β–„β–„β–ˆ β–ˆβ–ˆ β–„β–„β–ˆβ–„β–€β–€ β–€ β–ˆβ–ˆ β–„ β–„β–ˆ β–ˆβ–„β–„β–„β–ˆ β–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–„β–„β–„β–„β–„β–„β–„β–ˆ β–€ β–€ β–ˆβ–„β–€ β–€ β–€β–„β–ˆ β–ˆ β–ˆβ–„β–„β–„β–„β–„β–„β–„β–ˆβ–ˆ\n\u003e β–ˆβ–ˆ β–ˆ β–€ β–„β–„β–€β–€β–€ β–ˆβ–€ β–„ β–€β–€β–„β–€ β–„β–ˆ β–€β–ˆ β–€β–„β–„β–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–€β–€β–€ β–€β–„β–„β–ˆβ–ˆβ–„β–€β–€β–„β–ˆβ–€ β–€β–„β–ˆ β–€β–€β–€ β–„ β–ˆβ–„β–„β–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–„β–€β–€β–„β–„β–ˆβ–ˆ β–€ β–€ β–„β–„β–ˆβ–ˆβ–„ β–„β–„ β–„ β–ˆβ–€β–ˆ β–ˆ β–ˆβ–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–ˆ β–„β–€β–„β–ˆβ–„β–„β–„β–ˆ β–€β–ˆβ–ˆβ–„β–„β–„β–€β–€β–ˆβ–„β–€ β–„β–ˆβ–€ β–ˆβ–ˆβ–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–€β–€ β–„ β–€β–„ β–„β–„β–ˆβ–ˆβ–€β–„β–€β–€β–ˆβ–ˆβ–ˆβ–ˆβ–„β–„β–„ β–ˆβ–„ β–ˆ β–ˆβ–€β–€β–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–€β–€β–„ β–„β–€β–„ β–€β–€β–ˆβ–„β–€β–€β–„β–„β–€β–€ β–ˆβ–„β–„β–€β–ˆβ–€ β–€β–„ β–ˆβ–„ β–€β–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–€β–„β–€β–ˆβ–ˆ β–„β–„ β–€β–ˆβ–„β–ˆβ–€ β–€ β–€β–ˆβ–„β–€β–€ β–ˆβ–„β–€β–€ β–ˆ β–ˆ β–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–ˆβ–€β–ˆβ–„β–€β–„β–„ β–ˆ β–ˆ β–ˆβ–ˆ β–ˆβ–ˆ β–„ β–ˆ β–„β–„β–„ β–„β–€β–€β–„β–„ β–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–„β–ˆβ–„β–„β–„β–ˆβ–„β–ˆ β–„ β–„β–€β–ˆβ–€β–€ β–„β–€ β–ˆβ–€ β–„ β–„β–„β–„ β–€β–„β–€β–„β–ˆβ–ˆ\n\u003e β–ˆβ–ˆ β–„β–„β–„β–„β–„ β–ˆ β–„β–ˆβ–„β–€β–€ β–€β–ˆ β–ˆβ–„β–ˆ β–ˆβ–„β–ˆ β–€β–€β–„β–€β–ˆβ–ˆ\n\u003e β–ˆβ–ˆ β–ˆ β–ˆ β–ˆβ–€ β–„β–€β–ˆ β–ˆβ–ˆ β–„β–„β–€β–ˆβ–ˆ β–„β–„ β–„β–ˆ β–ˆβ–ˆ\n\u003e β–ˆβ–ˆ β–ˆβ–„β–„β–„β–ˆ β–ˆβ–„ β–ˆβ–ˆβ–€ β–„β–„ β–€β–ˆ β–„ β–€β–„β–„β–ˆβ–€β–ˆβ–ˆ\n\u003e β–ˆβ–ˆβ–„β–„β–„β–„β–„β–„β–„β–ˆβ–„β–ˆβ–ˆβ–ˆβ–„β–ˆβ–„β–ˆβ–„β–„β–„β–„β–ˆβ–„β–ˆβ–„β–ˆβ–ˆβ–ˆβ–ˆβ–„β–„β–ˆβ–ˆβ–ˆβ–ˆβ–ˆ\n\u003e β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€β–€\n```\n\n## Decoding\n\nGIF reader is not included in the package (it would take a lot of space).\nDecoding raw bitmap is still possible.\n\n```js\nimport encodeQR from 'qr';\nimport decodeQR from 'qr/decode';\nimport { Bitmap } from 'qr';\n\n// Scale so it would be 100x100 instead of 25x25\nconst opts = { scale: 4 };\n\n// a) Decode using raw bitmap, dependency-free\nfunction decodeRawBitmap() {\n const bmBits = encodeQR('Hello world', 'raw', opts);\n const bm = new Bitmap({ width: bmBits[0].length, height: bmBits.length });\n bm.data = bmBits;\n const decoded = decodeQR(bm.toImage());\n console.log('decoded(pixels)', decoded);\n}\n/*\nOutput:\ndecoded(pixels) Hello world\ndecoded(gif) Hello world\n*/\n\n// b) Decode using external GIF decoder\nimport gif from 'omggif'; // npm install omggif@1.0.10\nfunction parseGIF(image) {\n const r = new gif.GifReader(image);\n const data = [];\n r.decodeAndBlitFrameRGBA(0, data);\n const { width, height } = r.frameInfo(0);\n return { width, height, data };\n}\nfunction decodeWithExternal() {\n const gifBytes = encodeQR('Hello world', 'gif', opts);\n const decoded = decodeQR(parseGIF(gifBytes));\n console.log('decoded(gif)', decoded);\n}\n\n// c) draw gif/svg to browser DOM canvas\nimport { svgToPng } from 'qr/dom';\nconst png = svgToPng(encodeQR('Hello world', 'svg'), 512, 512);\n```\n\n### Decoding options\n\n```ts\nexport type Point4 = { x: number; y: number }[];\nexport type Image = {\n height: number;\n width: number;\n data: Uint8Array | Uint8ClampedArray | number[];\n};\nexport type DecodeOpts = {\n // By default we assume that image has 4 channel per pixel (RGBA). isRGB: true will force to use only one\n isRGB?: boolean;\n // Returns 4 center (3 finder pattern + 1 alignment pattern) points if detected\n detectFn?: (points: Point4) =\u003e void;\n // Returns RGBA image of detected QR code\n qrFn?: (img: Image) =\u003e void;\n};\nexport default function decodeQR(img: Image, opts: DecodeOpts = {});\n```\n\n### Decoding algorithm\n\nQR code decoding is challenging; it is essentially a computer vision problem. There are two main scenarios:\n\n- Decoding from files: This can be slow because it needs to handle complicated cases such as blur or rotation.\n- Decoding from a camera feed: This must be fast; even if one frame fails, the next frame can succeed.\n\nThe state-of-the-art approach for this, as with other computer vision problems, is using neural networks. However, using them would make the library hard to audit. Additionally, since JavaScript can't access hardware accelerators, it would likely be very slow. We also avoid using WebGL because it is complex and exposes users to fingerprinting.\n\nThe implemented reader algorithm is inspired by [ZXing](https://github.com/zxing/zxing):\n\n1. `toBitmap`: Convert the image to a bitmap of black and white segments. This is the slowest part and the most important.\n2. `detect`: Find three finder patterns and one alignment pattern (for versions \u003e 1). This is trickyβ€”they can be rotated and distorted by perspective. A square might appear as a quadrilateral with unknown size. The best we can do is count runs of the same color and select patterns with almost the same ratio of runs.\n3. `transform`: Once patterns have been found, correct the perspective and transform the quadrilateral into a square.\n4. `decodeBitmap`: Execute the encoding in reverse: read information via a zig-zag pattern, de-interleave bytes, correct errors, convert to bits, and finally, read segments from bits to create the string.\n5. **Finished!**\n\n### Decoding test vectors\n\nTo test our QR code decoding, we use an excellent dataset\nfrom [BoofCV](http://boofcv.org/index.php?title=Performance:QrCode). BoofCV decodes 73% of the test cases,\nwhile ZXing decodes 49%. Our implementation is nearly at parity with ZXing, primarily because ECI (Extended\nChannel Interpretation) support is not yet included. The test vectors are preserved in a Git repository at\n[github.com/paulmillr/qr-code-vectors](https://github.com/paulmillr/qr-code-vectors).\n\n**Note for Testing on iOS Safari:** Accessing the camera on iOS Safari requires HTTPS. This means that the file: protocol or non-encrypted http cannot be used. Ensure your testing environment uses https:.\n\nThe QR code specification is available for purchase at [iso.org](https://www.iso.org/standard/62021.html) for 200 CHF.\n\n### DOM helpers for web apps\n\nCheck out `dom.ts` for browser-related camera code that would make your apps simpler.\n\n## Using with Kotlin\n\n```kotlin\n@JsModule(\"@paulmillr/qr\")\n@JsNonModule\nexternal object Qr {\n @JsName(\"default\")\n fun encodeQR(text: String, output: String = definedExternally, opts: dynamic = definedExternally): Uint8Array\n}\n\n// then\nval bytes = Qr.encodeQR(\"text\", \"gif\", js(\"{ scale: 10 }\"))\nval blob = Blob(arrayOf(bytes), BlobPropertyBag(\"image/gif\"))\nval imgSrc = URL.createObjectURL(blob)\n```\n\n## Security\n\nThere are multiple ways a single text can be encoded in a QR code, which can lead to potential security implications:\n\n- **Segmentation Differences:** For example, `abc123` can be encoded as:\n `[{type: 'alphanum', data: 'abc'}, {type: 'num', data: '123'}]` or `[{type: 'alphanum', data: 'abc123'}]`\n- **Mask Selection Algorithms:** Different libraries may use different algorithms for mask selection.\n- **Default Settings:** Variations in error correction levels and how many bits are stored before upgrading versions.\n\nIf an adversary can access multiple QR codes generated from a specific library, they may be able to fingerprint the user. This fingerprinting could be used to exfiltrate data from air-gapped systems. In such cases, the adversary would need to create a library-specific exploit.\n\nWe mitigate these risks by:\n\n- **Cross-Testing:** We currently cross-test against python-qrcode, which is closer to the specification\n than some JavaScript implementations.\n- **Single Segment Encoding:** We always use single-segment encoding.\n While this may not be the most optimal for performance, it reduces the amount of fingerprinting data.\n\nFuture plans:\n\n- **Testing Against Multiple Libraries:** To further improve security and reduce fingerprinting, we can\n cross-test against three to four popular libraries.\n\n## Speed\n\nBenchmarks measured with Apple M2 on MacOS 13 with node.js 19.\n\n```\n======== encode/ascii ========\nencode/paulmillr-qr x 1,794 ops/sec @ 557ΞΌs/op\nencode/qrcode-generator x 3,128 ops/sec @ 319ΞΌs/op Β± 1.12% (min: 293ΞΌs, max: 3ms)\nencode/nuintun x 1,872 ops/sec @ 533ΞΌs/op\n======== encode/gif ========\nencode/paulmillr-qr x 1,771 ops/sec @ 564ΞΌs/op\nencode/qrcode-generator x 1,773 ops/sec @ 563ΞΌs/op\nencode/nuintun x 1,883 ops/sec @ 530ΞΌs/op\n======== encode: big ========\nencode/paulmillr-qr x 87 ops/sec @ 11ms/op\nencode/qrcode-generator x 124 ops/sec @ 8ms/op\nencode/nuintun x 143 ops/sec @ 6ms/op\n======== decode ========\ndecode/paulmillr-qr x 96 ops/sec @ 10ms/op Β± 1.39% (min: 9ms, max: 32ms)\ndecode/jsqr x 34 ops/sec @ 28ms/op\ndecode/nuintun x 35 ops/sec @ 28ms/op\ndecode/instascan x 79 ops/sec @ 12ms/op Β± 6.73% (min: 9ms, max: 223ms)\n======== Decoding quality ========\nblurred(45): paulmillr-qr=12 (26.66%) jsqr=13 (28.88%) nuintun=13 (28.88%) instascan=11 (24.44%)\n```\n\n## License\n\nCopyright (c) 2023 Paul Miller (paulmillr.com)\n\nCopyright (c) 2019 ZXing authors\n\nThe library paulmillr-qr is dual-licensed under the Apache 2.0 OR MIT license.\nYou can select a license of your choice.\n\nThe library contains code inspired by [ZXing](https://github.com/zxing/zxing), which is licensed under Apache 2.0.\n\nThe license to the use of the QR Code stipulated by JIS (Japanese Industrial Standards) and the ISO are not necessary.\nThe specification for QR Code has been made available for use by any person or organization. (Obtaining QR Code Specification)\nThe word β€œQR Code” is registered trademark of DENSO WAVE INCORPORATED in Japan and other countries.\nTo use the word β€œQR Code” in your publications or web site, etc, please indicate a sentence QR Code is registered trademark of DENSO WAVE INCORPORATED.\nThis registered trademark applies only for the word β€œQR Code”, and not for the QR Code pattern (image).\n(https://www.qrcode.com/en/faq.html)\n","funding_links":["https://github.com/sponsors/paulmillr"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulmillr%2Fqr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulmillr%2Fqr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulmillr%2Fqr/lists"}