enqr

v1.5.1

Published

3 months ago

Lightweight QR encoder for the browser & node loosely based on zxing

Downloads

0High
0Medium
0Low

wasabithumbs

qr matrix generator encoder browser zxing

EnQR

GitHub Actions Workflow Status GitHub Issues or Pull Requests npm bundle size NPM Version

A lightweight QR encoder for the browser & node loosely based on zxing. The browser bundle is about 80KB (compare to 3.6MB).

This is strictly a QR encoder & renderer, future updates should consist mainly of bug fixes.

Usage (Browser, NodeJS) • Encode Hints • Render Options • Live Demo • GitHub • NPM

Migrating to 1.5.X

Native support for EUC_JP and GB2312 charsets have been dropped, allowing a 60% reduction in bundle size. For most use cases, they can easily be replaced by UTF_8. SHIFT_JIS remains as it has special behavior in combination with Kanji mode. If you want to use these charsets, depend on EnQR 1.4 or earlier OR use a library such as iconv-lite to first encode your data to the desired charset and then pass it to EnQR as a Uint8Array or Buffer.

Usage (Browser)

<img id="qr" src="" alt="QR Code">
<script src="https://unpkg.com/[email protected]/umd/enqr.min.js" integrity="sha384-KnZr9AmTVEd8zD45lbgokG5pMpkUHXQwiqLg2aXjufzkiegPQ/YQ3pXh7N3+9Zuv" crossorigin="anonymous"></script>
<script>
    // Same as NodeJS
    enqr(
            "https://wasabithumb.github.io/",
            {
                errorCorrectionLevel: "H",
                characterSet: "ISO_8859_1"
            }
    ).renderToImage({
        image: document.querySelector("#qr"),
        trySVG: true
    }).catch(console.error);
</script>

Usage (NodeJS)

// ES6
import enqr from "enqr";
// CJS
const enqr = require("enqr");

/*
QR codes can store a lot of data types, see:
https://github.com/zxing/zxing/wiki/Barcode-Contents

These types are non-standard, but commonly agreed upon.
For URLs, you can just enter the URL:
*/
const qr = enqr("https://wasabithumb.github.io/", {
    errorCorrectionLevel: "L",
    characterSet: "UTF_8"
});

/*
The QR object returned by enqr is very similar to the
QRCode class in zxing, but with some extra methods for
rendering
*/

qr.renderToImage({
    image: document.querySelector("img#qr"),
    background: "white",
    foreground: [255, 255, 255],
    quietZone: "20%",
    trySVG: true
}).then((image) => {
    // Image has loaded
});

qr.renderToBlob({
    targetSize: 512,
    quietZone: 0,
    trySVG: false
}).then((blob) => {
    // Blob containing QR code as a PNG
});

qr.renderToURL().then((url) => {
    // Either a data: or blob: URL
});

const dataURL = qr.renderToDataURLSync();
const dataURLSVG = qr.renderToDataURLSync({ trySVG: true });
const svg = qr.renderToSVG();

// And a few more! ;)

Encode Hints

Options for the main function. Closely matches the implementation of hints in zxing.

Render Options

All options are optional. Some render options are specific to certain functions, but all functions inherit Basic options.

Basic

| Name | Type | Description | | --: | :-: | :-- | | background | string | number[] | The color of the background, default is white. | | foreground | string | number[] | The color of the foreground, default is white. | | quietZone | string${"px"\|"%"} | number | The size of the quiet zone (border). Either a number of pixels or percentage of the outer size. | | targetSize | number | The outer size of the QR code will be multiplied by the correct factor to best approximate the specified size | | floatPrecision | number | Reserved for future use |

SVG

This covers all methods that may return SVG data under any circumstances (renderToBlob, renderToURL, etc.) | Name | Type | Description | | --: | :-: | :-- | | trySVG | boolean | If true, and SVGs are supported in the current environment, the render operation may return SVG (otherwise PNG). | | svgNoWhitespace | boolean | If true, no whitespace will be included between SVG tags. | | svgCollation | 0 | 1 | 2 | 3 | An optimization that determines how pixels will be collated into shapes. Default is 3. Higher collation tends to produce smaller SVGs. Collation levels 1 & 2 may be faster to render. | | svgCustomCSS | string | function | (v1.4.0+) Adds custom styles to the SVG, e.g. .fg { stroke: red; }. See Custom CSS for more info. |

SVG Custom CSS

If svgCustomCSS is set as a string, it determines global styles for the entire SVG. The .bg and .fg selectors can be used to select background and foreground shapes respectively. svgCustomCSS can also be a function which determines CSS rules for individual elements. For example:

{
    // String syntax
    svgCustomCSS: ".fg { stroke: red; } .bg { fill: blue; }",
    // Function syntax
    svgCustomCSS: function(tagName, className, path) {
        // tagName is either "rect" or "path"
        // className is either "bg" or "fg"
        // path is SVG path data (https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d)
        return className === "fg" ?
            "stroke: red" :
            "fill: blue";
    }
}

HTML Image

Canvas

License

This project is licensed under the Apache-2.0 license, as zxing is also licensed under it. Despite not containing any zxing source code per se (and the spec for QR codes being generally available), I still found it an appropriate choice.