@cheprasov/qrcode

The library is for generating QR codes like SVG, HTML5 Canvas, PNG and JPG files, or text.

Features:

• The library has classes for generation SVG, Canvas, PNG / JPG or text with QR code.

• it is easy to use and configure (error correction level, type number, padding and so on).

• Supports inverting of data.

• The library is covered by tests.

• Easy to extend the classes or create own class for generation QR code.

• SVG (see class QRCodeSVG)

  • Returns generated QR code as SVG (xml) or DataURL.
  • Optimized SVG structure for xml and for DataURL.
  • Supports adding an image (logo) to QR code (allows to use url, dataUrl, Image, Canvas). See example
  • Allows to specify relative/abcolute position/size of image on QR code.

• Canvas (see class QRCodeCanvas)

  • Draws QR code on provided canvas or returns new canvas element with QR code.
  • Allows to get PNG / JPG files with QR code like dataUrl.
  • Supports adding a image (logo) to QR code (allows to use url, dataUrl, Image, Canvas).
  • Has image loader for images for QR code via Promise.
  • It is possible to specify scale or canvas size.
  • Allows to specify relative/abcolute position/size of image on QR code.

• Text (see class QRCodeText)

  • It is possible to create QR code for consoles or text output.

Plans to do:

• To add possibility to use patterns, themes and flexible customisation of QR code.
• to add support of rgb & rgba format for canvas colors.

1. How to install

> npm install @cheprasov/qrcode

import { QRCodeRaw, QRCodeSVG, QRCodeCanvas, QRCodeText } from '@cheprasov/qrcode';

2. Quick examples

2.1. Create SVG QR Code

import { QRCodeSVG } from '@cheprasov/qrcode';

const qrSVG = new QRCodeSVG('some value for QR code');
const dataUrlWithSVGQRCode = qrSVG.toDataUrl();
const xmlWithQRCode = qrSVG.toString();

2.2. Create Image QR Code

import { QRCodeCanvas } from '@cheprasov/qrcode';

const qrCanvas = new QRCodeCanvas('some value for QR code');
const dataUrlWithQRCode = qrCanvas.toDataUrl();
const canvasWithQRCode = qrCanvas.getCanvas();

2.3. QR Code with Image

import { QRCodeSVG } from '@cheprasov/qrcode';

const divElement = document.getElementById('some-id');

const qrSVG = new QRCodeSVG('https://github.com/cheprasov/js-qrcode/', {
    level: 'Q',
    image: {
        source: 'GitHub-Mark-120px-plus.png',
        width: '20%',
        height: '20%',
        x: 'center',
        y: 'center',
    },
});
divElement.innerHTML = qrSVG.toString();

Result:

Note, padding & image.border = 1 by default.

3. Documentation

3.1. class QRCodeRaw

The class base class for all QR code generators, returns raw data with information about QR dots and padding.

import { QRCodeRaw } from '@cheprasov/qrcode';

Public methods:

constructor(value: string, config: object)

Create new instance of QRCodeRaw

Params:

• value (string) - new value for encoding to QR code
• config (object, optional) - parameters of configuration

  • level (string, optional, default = L) - error correction level. Note, the level affects QR Code data size. Allowed values:

    • L - Allows recovery of up to 7% data loss
    • M - Allows recovery of up to 15% data loss
    • Q - Allows recovery of up to 25% data loss
    • H - Allows recovery of up to 30% data loss

  • typeNumber (number, optional, default = 0) - data capacity type, see details in appendix 4.1. Type number (1 ~ 40), or 0 for auto detection.

  • invert (boolean, optional, default = false) - inverting data of QR code.

  • padding (number, optional, default = 1) - count of white spaces on sides QR code. 1 unit has size like 1 information dot.

  • errorsEnabled: (boolean, optional, default = false) - if it is enabled and QR code generator can not create a QR Code then an error will thrown. If it is disabled then methods will return null of fail.

setValue(value: string): void

Set new value for encoding to QR code

Params:

• value (string) - new value for encoding to QR code

getDataSize(): number

Get size of QR code width / height (width and height are equal) Method will return 0 if QR code can not be generated by some reasons.

getData(): boolean[][]

Get raw data of QR code. Method will return null if QR code can not be generated by some reasons.

Example:

import { QRCodeRaw } from '@cheprasov/qrcode';

const config = {
    level: 'H', // use high error correction level
    padding: 0, // do not use padding around qr code data
};

const qrRaw = new QRCodeRaw('some value', config);
const qrCodeRaw = qrRaw.getData();
if (qrCodeRaw) {
    console.log(qrCodeRaw);
    // [
    //   0: [true, true, true, true, ... true],
    //   1: [true, false, false, false, ... true],
    //   ...
    //   24: [true, true, true, ... true],
    // ]
}

3.2. class QRCodeCanvas

The QR code generator based on HTML5 Canvas. It can create a canvas with QR code, or PNG/JPG data url. The class extends QRCodeRaw, therefore please see there description about public method and configuration params.

import { QRCodeCanvas } from '@cheprasov/qrcode';

Public methods:

constructor(value: string, config: object)

Create new instance of QRCodeCanvas. Please see config description of QRCodeRaw.constructor.

Config has additional parameters:

• config (object, optional) - parameters of configuration
  • see config of QRCodeRaw.constructor
  • fgColor (string, optional, default = #000) - foreground color of the QR code, is it allowed to use the next formats:
    • RGB or #RGB, example: #ABC, will be converted to #AABBCC
    • RGBA or #RGBA, example: #ABCD, will be converted to #AABBCCDD
    • RRGGBB or #RRGGBB, example: #AABBCC
    • RRGGBBAA or #RRGGBBAA, example: #AABBCCDD
    • Other formats (like red, rgb(...), rgba(...)) are not supported and will be converted to #0000
  • bgColor (string, optional, default = #FFF) - background color of the QR code, see description of fgColor.
  • scale (number, optional, default = 10) - scale size of QR code. For example, when scale is 5 then QR generator will use 5 pixel for draw 1 data dot.
  • size (number, optional, default = null) - size (width & height) of canvas in pixels. If size is specified then scale param will be ignored. Note, that the original canvas with QR code will be stretched to the specified size. See image scheme
  • image (object, optional, default = null) - parameters on an image, that should be added to QR code, like logo.
    • source (string|Image|Canvas) - source of image for QR Code, allowed to use the next types:
      • string - url to resource or dataUrl of image.
      • Image - it is allowed to use Image. The image's src should be loaded before use it.
      • Canvas - allowed to use HTML5 canvas element.
    • width (number|string) - width of the image in QR code dots (not a pixel), allowed formats:
      • <number> - defines the width of image, example: width: 30
      • <number>% - defines the width in percent of QR code without padding, example: width: '20%'
      • height (number|string) - height of the image in QR code dots, see width
    • x (number|string, optional, default = 0) - position of image on QR code by horizontal in QR code dots (not a pixel), allowed formats:
      • <number> - sets the left edge position from left to right, example: x: 10
      • <number>% - sets the left edge position in % of QR code without padding. Negative values are allowed. Example: x: '50%'
      • left - aligns the image to the left, example: x: 'left'
      • right - aligns the image to the right, example: x: 'right'
      • center - Centers the image in center of QR code, example: x: 'center'
      • left <number> - the same as <number>
      • left <number> % - the same as <number>%
      • right <number> - sets the right edge position from right to left, example: x: 'right 5'
      • right <number>% - sets the tight edge position in % of QR code without padding, example: x: 'right 10%'
    • y (number|string, optional, default = 0) - position of image on QR code by vertical in QR code dots (not a pixel), allowed formats:
      • <number> - sets the top edge position from top to bottom, example: y: 10
      • <number>% - sets the top edge position in % of QR code without padding. Negative values are allowed. Example: y: '50%'
      • top - aligns the image to the top, example: y: 'top'
      • bottom - aligns the image to the bottom, example: y: 'bottom'
      • center - Centers the image in center of QR code, example: y: 'center'
      • top <number> - the same as <number>
      • top <number> % - the same as <number>%
      • bottom <number> - sets the bottom edge position from bottom to top, example: y: 'bottom 5'
      • bottom <number>% - sets the bottom edge position in % of QR code without padding, example: y: 'bottom 10%'
    • border (number|null, optional, default = 1) - white space length around the images in dots. Negative values are allowed.
      • use 0 - for white space only under the image
      • use null to remove any white spaces under image and leave QR data dots

draw(canvas: HTMLCanvasElement = null): null | HTMLCanvasElement| Promise

Draws QR code on a canvas element and return the canvas if the canvas is provided, or returns a new canvas element if canvas is not provided (see getCanvas()). If QR code can not be generated then null will be returned. If config.image is provided AND config.image.source is string (url or dataUrl) then a promise will be returned with a canvas as result.

getCanvas(): null | HTMLCanvasElement | Promise

Returns new canvas element with QR code. If QR code can not be generated then null will be returned. If config.image is provided AND config.image.source is string (url or dataUrl) then a promise will be returned with a canvas as result.

toDataUrl(type: string = 'image/png', encoderOptions: number = 0.92): null | string | Promise

Allowed alias: toDataURL(...) Returns dataUrl with QR code. If QR code can not be generated then null will be returned. If config.image is provided AND config.image.source is string (url or dataUrl) then a promise will be returned with a dataUrl as result. See params descriptions here: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL

Example

import { QRCodeCanvas } from '@cheprasov/qrcode';

const qrCanvas = new QRCodeCanvas('some value');
const dataUrl = qrCanvas.toDataUrl();
console.log(dataUrl); // data:image/png;base64,iVBORw0KGgoAAAA...g==

Example with promise

import { QRCodeCanvas } from '@cheprasov/qrcode';

// Example with promise
const config = {
    level: 'H', // use high error correction level
    padding: 0, // do not use padding around qr code data,
    image: {
        source: 'https://some-url.com/foo.png', // or data:image/jpeg;base64,...
        width: '10%',
        height: '10%',
        x: 'center',
        y: 'center',
    }
};

const qrCanvas = new QRCodeCanvas('some value', config);
const promise = qrCanvas.toDataUrl();
// promise is returned because image.source is a string
promise.then((dataUrl) => {
    console.log(dataUrl); // data:image/png;base64,iVBORw0KGgoAAAAN...
});

3.3. class QRCodeSVG

The class creates QR code as SVG in string or data url formats. The class extends QRCodeRaw, therefore please see there description about public method and configuration params.

import { QRCodeSVG } from '@cheprasov/qrcode';

Public methods:

constructor(value: string, config: object)

Create new instance of QRCodeSVG. Please see config description of QRCodeRaw.constructor.

Config has additional parameters:

• config (object, optional) - parameters of configuration
  • see config of QRCodeRaw.constructor
  • fgColor (string, optional, default = #000) - foreground color of the QR code in CSS format
  • bgColor (string, optional, default = #FFF) - background color of the QR code in CSS format
  • image (object, optional, default = null) - parameters on an image, that should be added to QR code, like logo. See image scheme
    • source (string|Image|Canvas) - source of image for QR Code, allowed to use the next types:
      • string - url to resource or dataUrl of image.
      • Image - it is allowed to use Image. It is not necessary to have loaded image.
      • Canvas - allowed to use HTML5 canvas element.
    • width (number|string) - width of the image in QR code dots (not a pixel), allowed formats:
      • <number> - defines the width of image, example: width: 30
      • <number>% - defines the width in percent of QR code without padding, example: width: '20%'
      • height (number|string) - height of the image in QR code dots, see width
    • x (number|string, optional, default = 0) - position of image on QR code by horizontal in QR code dots (not a pixel), allowed formats:
      • <number> - sets the left edge position from left to right, example: x: 10
      • <number>% - sets the left edge position in % of QR code without padding. Negative values are allowed. Example: x: '50%'
      • left - aligns the image to the left, example: x: 'left'
      • right - aligns the image to the right, example: x: 'right'
      • center - Centers the image in center of QR code, example: x: 'center'
      • left <number> - the same as <number>
      • left <number> % - the same as <number>%
      • right <number> - sets the right edge position from right to left, example: x: 'right 5'
      • right <number>% - sets the tight edge position in % of QR code without padding, example: x: 'right 10%'
    • y (number|string, optional, default = 0) - position of image on QR code by vertical in QR code dots (not a pixel), allowed formats:
      • <number> - sets the top edge position from top to bottom, example: y: 10
      • <number>% - sets the top edge position in % of QR code without padding. Negative values are allowed. Example: y: '50%'
      • top - aligns the image to the top, example: y: 'top'
      • bottom - aligns the image to the bottom, example: y: 'bottom'
      • center - Centers the image in center of QR code, example: y: 'center'
      • top <number> - the same as <number>
      • top <number> % - the same as <number>%
      • bottom <number> - sets the bottom edge position from bottom to top, example: y: 'bottom 5'
      • bottom <number>% - sets the bottom edge position in % of QR code without padding, example: y: 'bottom 10%'
    • border (number|null, optional, default = 1) - white space length around the images in dots. Negative values are allowed.
      • use 0 - for white space only under the image
      • use null to remove any white spaces under image and leave QR data dots

toString(): null | string

Returns SVG with QR code as string. If QR code can not be generated then null will be returned.

toDataUrl(): null | string

Allowed alias: toDataURL(...) Returns SVG with QR code as dataUrl (string). If QR code can not be generated then null will be returned.

Example

import { QRCodeSVG } from '@cheprasov/qrcode';

const qrSVG = new QRCodeSVG('some value');
const dataUrl = qrSVG.toDataUrl();
console.log(dataUrl); // data:image/png;base64,iVBORw0KGgoAAAA...g==

Example with image

import { QRCodeSVG } from '@cheprasov/qrcode';

const config = {
    level: 'M', // use high error correction level
    padding: 0, // do not use padding around qr code data,
    image: {
        source: 'https://some-url.com/foo.png', // or data:image/jpeg;base64,...
        width: '10%',
        height: '10%',
        x: 'center',
        y: 'center',
    }
};

const qrSVG = new QRCodeSVG('some value', config);
const svg = qrSVG.toString();
console.log(svg);
// output:
// <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" shape-rendering="crispEdges" viewBox="0 0 21 21">
// <rect x="0" y="0" height="21" width="21" fill="#FFF"/>
// <rect x="0" y="0" height="1" width="7" fill="#000"/>
// <rect x="9" y="0" height="1" width="2" fill="#000"/>
// ...
// <image xlink:href="https://some-url.com/foo.png" x="10" y="10" width="2" height="2"/>
// </svg>

3.4. class QRCodeText

The class creates QR code as text. It is possible to show QR code in terminal. The class extends QRCodeRaw, therefore please see there description about public method and configuration params.

import { QRCodeSVG } from '@cheprasov/qrcode';

Public methods:

constructor(value: string, config: object)

Create new instance of QRCodeSVG. Please see config description of QRCodeRaw.constructor.

Config has additional parameters:

• config (object, optional) - parameters of configuration
  • see config of QRCodeRaw.constructor
  • blackSymbol (string, optional, default = ▓▓) - symbol(s) for black QR code dot.
  • whiteSymbol (string, optional, default = ) - symbol(s) for white QR code dot.

toString(): null | string

Returns QR code as string. If QR code can not be generated then null will be returned.

Example

import { QRCodeText } from '@cheprasov/qrcode';

const qrText = new QRCodeText('some value', {
    blackSymbol: '@@',
    whiteSymbol: '..',
});
const qrCode = qrText.toString();
console.log(qrCode);

// ..............................................
// ..@@@@@@@@@@@@@@..@@@@@@@@@@..@@@@@@@@@@@@@@..
// ..@@..........@@..@@@@..@@@@..@@..........@@..
// ..@@..@@@@@@..@@....@@@@@@....@@..@@@@@@..@@..
// ..@@..@@@@@@..@@....@@..@@@@..@@..@@@@@@..@@..
// ..@@..@@@@@@..@@..@@......@@..@@..@@@@@@..@@..
// ..@@..........@@..@@..@@......@@..........@@..
// ..@@@@@@@@@@@@@@..@@..@@..@@..@@@@@@@@@@@@@@..
// ..................@@@@@@@@....................
// ..@@@@@@....@@@@..@@@@@@@@@@@@@@@@@@....@@@@..
// ..@@@@@@@@..@@..@@..........@@@@..@@@@@@..@@..
// ..@@......@@..@@@@..@@@@....@@@@..@@......@@..
// ......@@..@@@@..@@........@@@@..@@..@@..@@@@..
// ....@@..@@@@@@@@..@@............@@@@@@..@@@@..
// ..................@@@@@@@@..@@....@@@@@@@@@@..
// ..@@@@@@@@@@@@@@........@@@@..@@..@@..@@..@@..
// ..@@..........@@..@@@@@@@@..@@....@@@@....@@..
// ..@@..@@@@@@..@@....@@..@@@@@@....@@@@..@@....
// ..@@..@@@@@@..@@......@@....@@..@@@@@@........
// ..@@..@@@@@@..@@..@@..........@@..@@..@@@@@@..
// ..@@..........@@..@@......@@..................
// ..@@@@@@@@@@@@@@..@@@@......@@@@@@@@@@....@@..
// ..............................................

4. Appendix

4.1. Data capacity in bytes

Something does not work

Feel free to fork project, fix bugs, write tests and finally request for pull