qrcode vs qr-image
QR Codes Generator in Web Apps
qrcodeqr-imageSimilar Packages:
QR Codes Generator in Web Apps

qr-image and qrcode are both npm packages used to generate QR codes in JavaScript environments, but they differ significantly in architecture, output formats, and runtime compatibility. qr-image is a Node.js-focused library that generates QR codes as image streams (PNG, SVG, EPS, PDF) using server-side APIs like Streams and Buffers. qrcode, by contrast, is a universal library designed to work consistently across both browser and Node.js environments, supporting canvas, data URLs, terminal output, and UTF-8 text rendering without relying on Node-specific constructs.

Npm Package Weekly Downloads Trend
3 Years
Github Stars Ranking
Stat Detail
Package
Downloads
Stars
Size
Issues
Publish
License
qrcode4,947,9177,976135 kB113a year agoMIT
qr-image126,1071,065-159 years agoMIT

qr-image vs qrcode: Choosing the Right QR Code Generator for Your Stack

Both qr-image and qrcode solve the same basic problem — generating QR codes from strings — but their internal designs, supported environments, and output capabilities diverge sharply. Understanding these differences is crucial when building anything from a simple marketing site to a complex full-stack application.

🖼️ Output Formats and Rendering Targets

qr-image produces QR codes exclusively as image streams or buffers, targeting file-based outputs:

  • PNG (via png-js)
  • SVG
  • EPS
  • PDF

It uses Node.js Streams under the hood, so every render returns a ReadableStream or Buffer. This makes it ideal for writing QR codes directly to disk or piping into HTTP responses on the server.

// qr-image: Node.js-only stream output
const qr = require('qr-image');
const fs = require('fs');

const qrStream = qr.image('https://example.com', { type: 'png' });
qrStream.pipe(fs.createWriteStream('qrcode.png'));

qrcode supports multiple rendering strategies tailored to different environments:

  • <canvas> element (browser)
  • Data URL strings (browser or Node.js)
  • Terminal/ASCII output (CLI tools)
  • UTF-8 text blocks (lightweight fallback)
  • Raw byte arrays (for custom encoders)

This flexibility means you can embed a QR code directly in an HTML page without touching the filesystem.

// qrcode: Browser-friendly canvas rendering
import QRCode from 'qrcode';

QRCode.toCanvas(document.getElementById('qrcode'), 'https://example.com', (error) => {
  if (error) console.error(error);
});

🌐 Runtime Compatibility: Node.js vs Universal

qr-image depends heavily on Node.js built-ins like stream, buffer, and zlib. It will fail immediately in browser environments because these modules don’t exist outside Node.js. Even with bundlers like Webpack, polyfilling these dependencies adds unnecessary bloat and complexity.

// This breaks in the browser
import qr from 'qr-image'; // ❌ ReferenceError: stream is not defined

qrcode is written to be runtime-agnostic. It avoids Node-specific APIs entirely and detects available features at runtime (e.g., HTMLCanvasElement in browsers, process.stdout in terminals). This makes it safe to use in React, Vue, Svelte, Electron, Cloudflare Workers, or plain Node.js — all with the same API.

// Works everywhere
import QRCode from 'qrcode';

// In browser
QRCode.toDataURL('hello', (err, url) => {
  document.getElementById('img').src = url;
});

// In Node.js
QRCode.toString('hello', { type: 'terminal' }, (err, qrcode) => {
  console.log(qrcode);
});

⚙️ API Design and Error Handling

qr-image uses a synchronous/streaming model with minimal error handling. Invalid input usually throws an exception, and there’s no callback or Promise interface. You’re expected to manage streams manually.

// qr-image: No async support, just streams
try {
  const svg = qr.imageSync('data', { type: 'svg' }); // Returns Buffer
} catch (e) {
  // Handle error
}

qrcode provides consistent async/sync variants for every method (toCanvas, toString, toDataURL, etc.), with optional callback or Promise support. Errors are passed explicitly rather than thrown, making integration with modern async patterns straightforward.

// qrcode: Flexible async handling
const url = await QRCode.toDataURL('hello');
// or
QRCode.toDataURL('hello', (err, url) => { /*...*/ });

🧪 Maintenance and Future-Proofing

While neither package is officially deprecated, qr-image has seen minimal updates in recent years and lacks support for newer QR code standards (like Micro QR or structured append). Its reliance on outdated stream patterns also makes it feel increasingly out of step with modern Node.js practices.

qrcode, on the other hand, receives regular updates, supports UTF-8 mode for compact text rendering, and actively addresses edge cases (e.g., very long URLs, special characters). Its test suite covers both browser and Node environments thoroughly.

🔁 Real-World Usage Scenarios

Generating a Downloadable QR Code on the Server

If you’re building an Express route that serves QR code images:

  • With qr-image:

    app.get('/qr.png', (req, res) => {
      res.type('png');
      qr.image(req.query.text, { type: 'png' }).pipe(res);
    });
    
  • With qrcode:

    app.get('/qr.png', async (req, res) => {
      const buffer = await QRCode.toBuffer(req.query.text);
      res.type('png').send(buffer);
    });
    

Both work, but qrcode gives you a clean Buffer without stream plumbing.

Embedding a QR Code in a React Component

Only qrcode works here:

import { useEffect, useRef } from 'react';
import QRCode from 'qrcode';

function QrComponent({ value }) {
  const canvasRef = useRef();

  useEffect(() => {
    QRCode.toCanvas(canvasRef.current, value);
  }, [value]);

  return <canvas ref={canvasRef} />;
}

Trying this with qr-image would crash the app.

✅ When They Overlap

Despite their differences, both libraries:

  • Use the same underlying QR code algorithm (based on the ISO/IEC 18004 standard)
  • Support common error correction levels (L, M, Q, H)
  • Allow configuration of margin size and module size
  • Encode UTF-8 strings correctly (though qr-image may require manual encoding in some cases)
// Both support error correction
qr.image('text', { ec_level: 'H' });          // qr-image
QRCode.toDataURL('text', { errorCorrectionLevel: 'H' }); // qrcode

🆚 Summary: Key Differences

Featureqr-imageqrcode
Browser Support❌ No✅ Yes
Output Types🖼️ PNG/SVG/EPS/PDF (streams)🖼️ Canvas / Data URL / Terminal / UTF-8
Runtime🖥️ Node.js only🌍 Universal (browser + Node)
API Style📦 Stream-based, sync-only⏳ Async/sync, callback or Promise
Maintenance🕒 Low activity🔁 Actively maintained
Use Case Fit🖨️ Server file generation only🧩 Anywhere QR codes are needed

💡 Final Recommendation

For new projects, default to qrcode. Its universal compatibility, modern API, and active maintenance make it the clear choice for almost every scenario — whether you’re building a static site, a React SPA, a CLI tool, or a server-rendered app.

Reserve qr-image only for legacy Node.js systems where you’re already deeply invested in stream pipelines and have no browser requirements. Even then, consider migrating to qrcode for future-proofing.

In short: if your code might ever touch a browser — even indirectly — skip qr-image entirely.

How to Choose: qrcode vs qr-image
  • qrcode:

    Choose qrcode when you need reliable QR code generation across both frontend and backend contexts. It supports canvas rendering for web apps, data URLs for inline embedding, terminal output for CLI tools, and UTF-8 fallbacks for low-dependency environments. Its consistent API and lack of Node.js-specific dependencies make it the safer, more versatile choice for modern full-stack or client-side applications.

  • qr-image:

    Choose qr-image only if you're working in a pure Node.js backend environment and need to generate QR codes as downloadable image files (especially PNG or SVG) using Streams or Buffers. It’s a good fit for server-rendered reports or file exports where you don’t need browser compatibility. However, avoid it for any frontend or isomorphic use case—it won’t work in the browser and hasn’t seen active maintenance in recent years.

README for qrcode

node-qrcode

QR code/2d barcode generator.

Travis npm npm npm

Highlights

  • Works on server and client (and react native with svg)
  • CLI utility
  • Save QR code as image
  • Support for Numeric, Alphanumeric, Kanji and Byte mode
  • Support for mixed modes
  • Support for chinese, cyrillic, greek and japanese characters
  • Support for multibyte characters (like emojis :smile:)
  • Auto generates optimized segments for best data compression and smallest QR Code size
  • App agnostic readability, QR Codes by definition are app agnostic

Installation

Inside your project folder do:

npm install --save qrcode

or, install it globally to use qrcode from the command line to save qrcode images or generate ones you can view in your terminal.

npm install -g qrcode

Usage

CLI

Usage: qrcode [options] <input string>

QR Code options:
  -v, --qversion  QR Code symbol version (1 - 40)                       [number]
  -e, --error     Error correction level           [choices: "L", "M", "Q", "H"]
  -m, --mask      Mask pattern (0 - 7)                                  [number]

Renderer options:
  -t, --type        Output type                  [choices: "png", "svg", "utf8"]
  -w, --width       Image width (px)                                    [number]
  -s, --scale       Scale factor                                        [number]
  -q, --qzone       Quiet zone size                                     [number]
  -l, --lightcolor  Light RGBA hex color
  -d, --darkcolor   Dark RGBA hex color
  --small  Output smaller QR code to terminal                          [boolean]

Options:
  -o, --output  Output file
  -h, --help    Show help                                              [boolean]
  --version     Show version number                                    [boolean]

Examples:
  qrcode "some text"                    Draw in terminal window
  qrcode -o out.png "some text"         Save as png image
  qrcode -d F00 -o out.png "some text"  Use red as foreground color

If not specified, output type is guessed from file extension.
Recognized extensions are png, svg and txt.

Browser

node-qrcode can be used in browser through module bundlers like Browserify and Webpack or by including the precompiled bundle present in build/ folder.

Module bundlers

<!-- index.html -->
<html>
  <body>
    <canvas id="canvas"></canvas>
    <script src="bundle.js"></script>
  </body>
</html>
// index.js -> bundle.js
var QRCode = require('qrcode')
var canvas = document.getElementById('canvas')

QRCode.toCanvas(canvas, 'sample text', function (error) {
  if (error) console.error(error)
  console.log('success!');
})

Precompiled bundle

<canvas id="canvas"></canvas>

<script src="/build/qrcode.js"></script>
<script>
  QRCode.toCanvas(document.getElementById('canvas'), 'sample text', function (error) {
    if (error) console.error(error)
    console.log('success!');
  })
</script>

If you install through npm, precompiled files will be available in node_modules/qrcode/build/ folder.

The precompiled bundle have support for Internet Explorer 10+, Safari 5.1+, and all evergreen browsers.

NodeJS

Require the module qrcode

var QRCode = require('qrcode')

QRCode.toDataURL('I am a pony!', function (err, url) {
  console.log(url)
})

render a qrcode for the terminal

var QRCode = require('qrcode')

QRCode.toString('I am a pony!',{type:'terminal'}, function (err, url) {
  console.log(url)
})

ES6/ES7

Promises and Async/Await can be used in place of callback function.

import QRCode from 'qrcode'

// With promises
QRCode.toDataURL('I am a pony!')
  .then(url => {
    console.log(url)
  })
  .catch(err => {
    console.error(err)
  })

// With async/await
const generateQR = async text => {
  try {
    console.log(await QRCode.toDataURL(text))
  } catch (err) {
    console.error(err)
  }
}

Error correction level

Error correction capability allows to successfully scan a QR Code even if the symbol is dirty or damaged. Four levels are available to choose according to the operating environment.

Higher levels offer a better error resistance but reduce the symbol's capacity.
If the chances that the QR Code symbol may be corrupted are low (for example if it is showed through a monitor) is possible to safely use a low error level such as Low or Medium.

Possible levels are shown below:

LevelError resistance
L (Low)~7%
M (Medium)~15%
Q (Quartile)~25%
H (High)~30%

The percentage indicates the maximum amount of damaged surface after which the symbol becomes unreadable.

Error level can be set through options.errorCorrectionLevel property.
If not specified, the default value is M.

QRCode.toDataURL('some text', { errorCorrectionLevel: 'H' }, function (err, url) {
  console.log(url)
})

QR Code capacity

Capacity depends on symbol version and error correction level. Also encoding modes may influence the amount of storable data.

The QR Code versions range from version 1 to version 40.
Each version has a different number of modules (black and white dots), which define the symbol's size. For version 1 they are 21x21, for version 2 25x25 e so on. Higher is the version, more are the storable data, and of course bigger will be the QR Code symbol.

The table below shows the maximum number of storable characters in each encoding mode and for each error correction level.

ModeLMQH
Numeric7089559639933057
Alphanumeric4296339124201852
Byte2953233116631273
Kanji181714351024784

Note: Maximum characters number can be different when using Mixed modes.

QR Code version can be set through options.version property.
If no version is specified, the more suitable value will be used. Unless a specific version is required, this option is not needed.

QRCode.toDataURL('some text', { version: 2 }, function (err, url) {
  console.log(url)
})

Encoding modes

Modes can be used to encode a string in a more efficient way.
A mode may be more suitable than others depending on the string content. A list of supported modes are shown in the table below:

ModeCharactersCompression
Numeric0, 1, 2, 3, 4, 5, 6, 7, 8, 93 characters are represented by 10 bits
Alphanumeric0–9, A–Z (upper-case only), space, $, %, *, +, -, ., /, :2 characters are represented by 11 bits
KanjiCharacters from the Shift JIS system based on JIS X 02082 kanji are represented by 13 bits
ByteCharacters from the ISO/IEC 8859-1 character setEach characters are represented by 8 bits

Choose the right mode may be tricky if the input text is unknown.
In these cases Byte mode is the best choice since all characters can be encoded with it. (See Multibyte characters)
However, if the QR Code reader supports mixed modes, using Auto mode may produce better results.

Mixed modes

Mixed modes are also possible. A QR code can be generated from a series of segments having different encoding modes to optimize the data compression.
However, switching from a mode to another has a cost which may lead to a worst result if it's not taken into account. See Manual mode for an example of how to specify segments with different encoding modes.

Auto mode

By default, automatic mode selection is used.
The input string is automatically splitted in various segments optimized to produce the shortest possible bitstream using mixed modes.
This is the preferred way to generate the QR Code.

For example, the string ABCDE12345678?A1A will be splitted in 3 segments with the following modes:

SegmentMode
ABCDEAlphanumeric
12345678Numeric
?A1AByte

Any other combinations of segments and modes will result in a longer bitstream.
If you need to keep the QR Code size small, this mode will produce the best results.

Manual mode

If auto mode doesn't work for you or you have specific needs, is also possible to manually specify each segment with the relative mode. In this way no segment optimizations will be applied under the hood.
Segments list can be passed as an array of object:

  var QRCode = require('qrcode')

  var segs = [
    { data: 'ABCDEFG', mode: 'alphanumeric' },
    { data: '0123456', mode: 'numeric' }
  ]

  QRCode.toDataURL(segs, function (err, url) {
    console.log(url)
  })

Kanji mode

With kanji mode is possible to encode characters from the Shift JIS system in an optimized way.
Unfortunately, there isn't a way to calculate a Shifted JIS values from, for example, a character encoded in UTF-8, for this reason a conversion table from the input characters to the SJIS values is needed.
This table is not included by default in the bundle to keep the size as small as possible.

If your application requires kanji support, you will need to pass a function that will take care of converting the input characters to appropriate values.

An helper method is provided by the lib through an optional file that you can include as shown in the example below.

Note: Support for Kanji mode is only needed if you want to benefit of the data compression, otherwise is still possible to encode kanji using Byte mode (See Multibyte characters).

  var QRCode = require('qrcode')
  var toSJIS = require('qrcode/helper/to-sjis')

  QRCode.toDataURL(kanjiString, { toSJISFunc: toSJIS }, function (err, url) {
    console.log(url)
  })

With precompiled bundle:

<canvas id="canvas"></canvas>

<script src="/build/qrcode.min.js"></script>
<script src="/build/qrcode.tosjis.min.js"></script>
<script>
  QRCode.toCanvas(document.getElementById('canvas'),
    'sample text', { toSJISFunc: QRCode.toSJIS }, function (error) {
    if (error) console.error(error)
    console.log('success!')
  })
</script>

Binary data

QR Codes can hold arbitrary byte-based binary data. If you attempt to create a binary QR Code by first converting the data to a JavaScript string, it will fail to encode propery because string encoding adds additional bytes. Instead, you must pass a Uint8ClampedArray or compatible array, or a Node Buffer, as follows:

// Regular array example
// WARNING: Element values will be clamped to 0-255 even if your data contains higher values.
const QRCode = require('qrcode')
QRCode.toFile(
  'foo.png',
  [{ data: [253,254,255], mode: 'byte' }],
  ...options...,
  ...callback...
)
// Uint8ClampedArray example
const QRCode = require('qrcode')

QRCode.toFile(
  'foo.png',
  [{ data: new Uint8ClampedArray([253,254,255]), mode: 'byte' }],
  ...options...,
  ...callback...
)
// Node Buffer example
// WARNING: Element values will be clamped to 0-255 even if your data contains higher values.
const QRCode = require('qrcode')

QRCode.toFile(
  'foo.png',
  [{ data: Buffer.from([253,254,255]), mode: 'byte' }],
  ...options...,
  ...callback...
)

TypeScript users: if you are using @types/qrcode, you will need to add a // @ts-ignore above the data segment because it expects data: string.

Multibyte characters

Support for multibyte characters isn't present in the initial QR Code standard, but is possible to encode UTF-8 characters in Byte mode.

QR Codes provide a way to specify a different type of character set through ECI (Extended Channel Interpretation), but it's not fully implemented in this lib yet.

Most QR Code readers, however, are able to recognize multibyte characters even without ECI.

Note that a single Kanji/Kana or Emoji can take up to 4 bytes.

API

Browser:

Server:

Browser API

create(text, [options])

Creates QR Code symbol and returns a qrcode object.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options

See QR Code options.

returns

Type: Object

// QRCode object
{
  modules,              // Bitmatrix class with modules data
  version,              // Calculated QR Code version
  errorCorrectionLevel, // Error Correction Level
  maskPattern,          // Calculated Mask pattern
  segments              // Generated segments
}

toCanvas(canvasElement, text, [options], [cb(error)])

toCanvas(text, [options], [cb(error, canvas)])

Draws qr code symbol to canvas.
If canvasElement is omitted a new canvas is returned.

canvasElement

Type: DOMElement

Canvas where to draw QR Code.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options

See Options.

cb

Type: Function

Callback function called on finish.

Example
QRCode.toCanvas('text', { errorCorrectionLevel: 'H' }, function (err, canvas) {
  if (err) throw err

  var container = document.getElementById('container')
  container.appendChild(canvas)
})

toDataURL(text, [options], [cb(error, url)])

toDataURL(canvasElement, text, [options], [cb(error, url)])

Returns a Data URI containing a representation of the QR Code image.
If provided, canvasElement will be used as canvas to generate the data URI.

canvasElement

Type: DOMElement

Canvas where to draw QR Code.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options
  • type

    Type: String
    Default: image/png

    Data URI format.
    Possible values are: image/png, image/jpeg, image/webp.

  • rendererOpts.quality

    Type: Number
    Default: 0.92

    A Number between 0 and 1 indicating image quality if the requested type is image/jpeg or image/webp.

See Options for other settings.

cb

Type: Function

Callback function called on finish.

Example
var opts = {
  errorCorrectionLevel: 'H',
  type: 'image/jpeg',
  quality: 0.3,
  margin: 1,
  color: {
    dark:"#010599FF",
    light:"#FFBF60FF"
  }
}

QRCode.toDataURL('text', opts, function (err, url) {
  if (err) throw err

  var img = document.getElementById('image')
  img.src = url
})

toString(text, [options], [cb(error, string)])

Returns a string representation of the QR Code.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options
  • type

    Type: String
    Default: utf8

    Output format.
    Possible values are: terminal,utf8, and svg.

See Options for other settings.

cb

Type: Function

Callback function called on finish.

Example
QRCode.toString('http://www.google.com', function (err, string) {
  if (err) throw err
  console.log(string)
})

Server API

create(text, [options])

See create.


toCanvas(canvas, text, [options], [cb(error)])

Draws qr code symbol to node canvas.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options

See Options.

cb

Type: Function

Callback function called on finish.


toDataURL(text, [options], [cb(error, url)])

Returns a Data URI containing a representation of the QR Code image.
Only works with image/png type for now.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options

See Options for other settings.

cb

Type: Function

Callback function called on finish.


toString(text, [options], [cb(error, string)])

Returns a string representation of the QR Code.
If choosen output format is svg it will returns a string containing xml code.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options
  • type

    Type: String
    Default: utf8

    Output format.
    Possible values are: utf8, svg, terminal.

See Options for other settings.

cb

Type: Function

Callback function called on finish.

Example
QRCode.toString('http://www.google.com', function (err, string) {
  if (err) throw err
  console.log(string)
})

toFile(path, text, [options], [cb(error)])

Saves QR Code to image file.
If options.type is not specified, the format will be guessed from file extension.
Recognized extensions are png, svg, txt.

path

Type: String

Path where to save the file.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options
  • type

    Type: String
    Default: png

    Output format.
    Possible values are: png, svg, utf8.

  • rendererOpts.deflateLevel (png only)

    Type: Number
    Default: 9

    Compression level for deflate.

  • rendererOpts.deflateStrategy (png only)

    Type: Number
    Default: 3

    Compression strategy for deflate.

See Options for other settings.

cb

Type: Function

Callback function called on finish.

Example
QRCode.toFile('path/to/filename.png', 'Some text', {
  color: {
    dark: '#00F',  // Blue dots
    light: '#0000' // Transparent background
  }
}, function (err) {
  if (err) throw err
  console.log('done')
})

toFileStream(stream, text, [options])

Writes QR Code image to stream. Only works with png format for now.

stream

Type: stream.Writable

Node stream.

text

Type: String|Array

Text to encode or a list of objects describing segments.

options

See Options.


Options

QR Code options

version

Type: Number

QR Code version. If not specified the more suitable value will be calculated.

errorCorrectionLevel

Type: String
Default: M

Error correction level.
Possible values are low, medium, quartile, high or L, M, Q, H.

maskPattern

Type: Number

Mask pattern used to mask the symbol.
Possible values are 0, 1, 2, 3, 4, 5, 6, 7.
If not specified the more suitable value will be calculated.

toSJISFunc

Type: Function

Helper function used internally to convert a kanji to its Shift JIS value.
Provide this function if you need support for Kanji mode.

Renderers options

margin

Type: Number
Default: 4

Define how much wide the quiet zone should be.

scale

Type: Number
Default: 4

Scale factor. A value of 1 means 1px per modules (black dots).

small

Type: Boolean
Default: false

Relevant only for terminal renderer. Outputs smaller QR code.

width

Type: Number

Forces a specific width for the output image.
If width is too small to contain the qr symbol, this option will be ignored.
Takes precedence over scale.

color.dark

Type: String
Default: #000000ff

Color of dark module. Value must be in hex format (RGBA).
Note: dark color should always be darker than color.light.

color.light

Type: String
Default: #ffffffff

Color of light module. Value must be in hex format (RGBA).


GS1 QR Codes

There was a real good discussion here about them. but in short any qrcode generator will make gs1 compatible qrcodes, but what defines a gs1 qrcode is a header with metadata that describes your gs1 information.

https://github.com/soldair/node-qrcode/issues/45

Credits

This lib is based on "QRCode for JavaScript" which Kazuhiko Arase thankfully MIT licensed.

License

MIT

The word "QR Code" is registered trademark of:
DENSO WAVE INCORPORATED