/qrcode

Generate QR codes as SVG, HTML5 Canvas, PNG and JPG files, even text for the terminal.

Primary LanguageTypeScriptMIT LicenseMIT

MIT license

@akamfoad/qrcode

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

Acknowledgment

This project initially has been forked from @cheprasov/js-qrcode.

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.

TypeDocs

https://akamfoad.github.io/qrcode/

1. How to install

> npm install @akamfoad/qrcode
import {
  QRCodeRaw,
  QRCodeSVG,
  QRCodeCanvas,
  QRCodeText,
} from '@akamfoad/qrcode';

2. Quick examples

2.1. Create SVG QR Code

import { QRCodeSVG } from '@akamfoad/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 '@akamfoad/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 '@akamfoad/qrcode';

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

const qrSVG = new QRCodeSVG('JohnDoe', {
  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.

test

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 '@akamfoad/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 '@akamfoad/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 '@akamfoad/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 '@akamfoad/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 '@akamfoad/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 '@akamfoad/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 '@akamfoad/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 '@akamfoad/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 '@akamfoad/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 '@akamfoad/qrcode';

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

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

4. Appendix

4.1. Data capacity in bytes

TypeNumber Numeric Alphanumeric Byte Kanji
LMQHLMQHLMQHLMQH
14134271725201610171411710874
27763483447382920322620142016128
31271017758776147355342322432262015
4187149111821149067507862463448382821
5255202144106154122876410684604465523727
632225517813919515410884134106745882654536
737029320715422417812593154122866495755339
846136525920227922115712219215210884118936652
9552432312235335262189143230180130981411118060
106525133642883953112211742712131511191671319374
1177260442733146836625920032125117713719815510985
1288369148937453541929622736728720315522617712596
131022796580427619483352259425331241177262204149109
141101871621468667528376283458362258194282223159120
151250991703530758600426321520412292220320254180136
1614081082775602854656470365586450322250361277198154
1715481212876674938734531408644504364280397310224173
18172513469487461046816574452718560394310442345243191
191903150010638131153909644493792624442338488384272208
202061160011599191249970702557858666482382528410297235
2122321708122496913521035742587929711509403572438314248
222409187213581056146011348236401003779565439618480348270
232620205914681108158812488906721091857611461672528376284
242812218815881228170413269637441171911661511721561407315
2530572395171812861853145110417791273997715535784614440330
26328325441804142519901542109486413671059751593842652462365
27351727011933150121321637117291014651125805625902692496385
28366928572085158122231732126395815281190868658940732534405
2939093035218116772369183913221016162812649086981002778559430
3041583289235817822520199414291080173213709827421066843604457
31441734862473189726772113149911501840145210307901132894634486
32468636932670202228402238161812261952153811128421201947684518
334965390928052157300923691700130720681628116889812731002719553
345253413429492301318325061787139421881722122895813471060756590
355529434330812361335126321867143123031809128398314171113790605
3658364588324425243537278019661530243119111351105114961176832647
3761534775341726253729289420711591256319891423109315771224876673
3864795039359927353927305421811658269920991499113916611292923701
3967435313379129274087322022981774280922131579121917291362972750
40708955963993305742963391242018522953233116631273181714351024784

Something does not work

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