// Barcode Writer in Pure JavaScript
bwip-js is a translation to native JavaScript of the amazing code provided in Barcode Writer in Pure PostScript. The translated code can run on any modern browser or JavaScript-based server framework.
The software has encoding modules for over 100 different barcode types and standards.
All linear and two-dimensional barcodes in common use (and many uncommon
ones) are available. An exhaustive list of supported barcode types can be
found at the end of this document. Barcode images are generated as png (node-js) or to a canvas (browser)
or as SVG (all platforms).
Version 4 has been released. The primary enhancement is built-in support for generating barcodes in SVG. You can read about the changes here: https://github.com/metafloor/bwip-js/discussions/299
Status
- Current bwip-js version is 4.3.2 (2024-03-19)
- Current BWIPP version is 2024-01-03
- Node.js compatibility: 0.12+
- Browser compatibility: Edge, Firefox, Chrome
Supported Platforms
Links
Installation
You can download the latest npm module using:
npm install bwip-js
Or the latest code from github:
https://github.com/metafloor/bwip-js
(The bwip-js master branch and the npm version are kept sync'd.)
Online Barcode Generator
An online barcode generator
demonstrates all of the features of bwip-js. The app is also available
in the root bwip-js directory. See Demo HTML App.
Online Barcode API
A bwip-js barcode service is available online, ready to serve up barcode images
on demand.
You can generate barcodes from anywhere on the web. Embed the URLs in your
HTML documents or retrieve the barcode images directly from your non-JavaScript
server. (JavaScript-based servers should use the bwip-js code directly - it will
be a lot more performant.)
For details on how to use this service, see Online Barcode API.
Working With bwip-js Methods
Most of the public methods of the bwip-js export use an options object. Only two values are required:
bcid
: The name of the barcode type/symbol.text
: The text to encode.
All remaining options are optional, though you may find some quite useful.
The options values can be divided into two parts, bwip-js specific options and BWIPP options.
The bwip-js options are:
-
scaleX
: The x-axis scaling factor. Must be an integer > 0. Default is 2.
-
scaleY
: The y-axis scaling factor. Must be an integer > 0. Default is scaleX
.
-
scale
: Sets both the x-axis and y-axis scaling factors. Must be an integer > 0.
-
rotate
: Allows rotating the image to one of the four orthogonal orientations. A string value. Must be one of:
'N'
: Normal (not rotated). The default.'R'
: Clockwise (right) 90 degree rotation.'L'
: Counter-clockwise (left) 90 degree rotation.'I'
: Inverted 180 degree rotation.
-
binarytext
: The default behavior is to encode the text
string as UTF-8 binary bytes. If the text is already 8-bit encoded, you can disable this behavior by setting the flag to true
.
-
padding
: Shorthand for setting paddingtop
, paddingleft
, paddingright
, and paddingbottom
.
-
paddingwidth
: Shorthand for setting paddingleft
and paddingright
.
-
paddingheight
: Shorthand for setting paddingtop
and paddingbottom
.
-
paddingtop
: Sets the height of the padding area, in points, on the top of the barcode image. Rotates and scales with the image.
-
paddingleft
: Sets the width of the padding area, in points, on the left side of the barcode image. Rotates and scales with the image.
-
paddingright
: Sets the width of the padding area, in points, on the right side of the barcode image. Rotates and scales with the image.
-
paddingbottom
: Sets the height of the padding area, in points, on the bottom of the barcode image. Rotates and scales with the image.
-
backgroundcolor
: This is actually a BWIPP option but is better handled by the bwip-js drawing code. Expects either a hex RGB, RRGGBB or CCMMYYKK string value or CSS-style #RGB or #RRGGBB string value.
For the BWIPP specific options, you will need to consult the
BWIPP documentation
to determine what options are available for each barcode type.
All of the BWIPP color options (e.g. barcolor
, textcolor
, bordercolor
) can be specified using either RGB, RRGGBB or CCMMYYKK formats or the CSS-style #RGB and #RRGGBB formats.
Note that bwip-js normalizes the BWIPP width
and height
options to always be in millimeters.
The resulting images are rendered at 72 dpi. To convert to pixels, use a factor of 2.835 px/mm
(72 dpi / 25.4 mm/in). The bwip-js scale options multiply the width
, height
, and padding
.
An important note about the BWIPP width
and height
parameters.
Barcodes have the concept of module width (and height if a two-dimensional barcode). For
linear barcodes, the module width is the width of the narrowest bar, and all other bar widths are
a multiple of it. For 2D symbols, module width and height are the dimensions of the square
or rectangle that defines the symbol's layout grid.
For a barcode to be "in spec", the individual module dimensions must be consistent throughout the
symbol. With high resolution printing, you can add/subtract a dot to adjust the size of individual
modules so the overall image meets the requested width or height, while still keeping the module
size within spec. This is the intention behind BWIPP's width
and height
parameters.
bwip-js is designed for web usage, with a target display resolution of 72dpi. (All of BWIPP's
internals are calculated in points and bwip-js just maps 1pt to 1px.) At that low
resolution, it is not possible to add or subtract pixels without causing the symbol to go
out of spec. Imagine a fairly common module width of 2px. If you add or subtract a pixel,
you have changed the size by 50%. Typical barcode specs require module sizes to be within
5-10 pecent of nominal.
For this reason, bwip-js uses a constant module size so the resulting image is as
large as possible, without exceeding the requested width
or height
.
The design causes the rendered barcodes to grow in "quantums". An image will be
X-pixels wide with a module with of 2px, and Y-pixels wide with a module width of 3px,
and can not vary between those two sizes.
With bwip-js, the scale
parameters can be thought of as requesting a particular module
width. scale=1
maps to a 1px module. scale=2
is a 2px module. Etc.
When you specify width
, you are effectively changing the scale of the final image.
Internally, bwip-js calcuates the requested width x scale
, then divides
by the number of modules the symbol requires. The floor of that value is the
module width (scale) of the rendered barcode.
Browser Usage
To use within a browser, add the following to the head of your page:
<script type="text/javascript" src="file-or-url-path-to/bwip-js/dist/bwip-js-min.js"></script>
While developing your project, you may want to use dist/bwip-js.js
to get better stack
traces.
If you are using RequireJS
or a common-js bundling utility, the bwip-js scripts are
structured as UMDs and should work with your environment.
The scripts adds a single bwipjs
global object. To draw a barcode to a canvas:
try {
let canvas = bwipjs.toCanvas('mycanvas', {
bcid: 'code128',
text: '0123456789',
scale: 3,
height: 10,
includetext: true,
textxalign: 'center',
});
} catch (e) {
}
The bwipjs.toCanvas()
method takes two parameters:
- The canvas on which to render the barcode. This can by an
id
string or the actual
canvas element. The rendering will automatically resize the canvas to match the
barcode image. - A bwip-js/BWIPP options object.
On return from toCanvas()
, the barcode image will have been fully rendered to the canvas.
If you would prefer to display the barcode using an <img>
tag or with CSS background-image
,
pass in a detached or hidden canvas, and use the canvas method
HTMLCanvasElement.toDataURL
to get a data URL. For example:
let canvas = document.createElement('canvas');
try {
bwipjs.toCanvas(canvas, options);
document.getElementById('my-img').src = canvas.toDataURL('image/png');
} catch (e) {
}
Browser ES6 Module Usage
The ESM provides the same API as the standard browser module using:
import bwipjs from 'bwip-js';
The ESM also facilitates bundler tree shaking by providing the individual encoders as named exports.
Each exported encoder functions identically to bwipjs.toCanvas()
.
The exported names are the same as the bcid
names, with the caveat that dashes -
are replaced with
underscores _
. For example, to import the gs1-128
encoder, you would use:
import { gs1_128 } from 'bwip-js';
try {
gs1_128('my-canvas', options);
} catch (e) {
}
Node.js Request Handler
The online barcode API is implemented as a Node.js application.
See the Online Barcode API for details on how the URL query parameters must be structured.
A working, minimal example of how to use the request handler can be found in
server.js
:
const http = require('http');
const bwipjs = require('bwip-js');
http.createServer(function(req, res) {
if (req.url.indexOf('/?bcid=') != 0) {
res.writeHead(404, { 'Content-Type':'text/plain' });
res.end('BWIPJS: Unknown request format.', 'utf8');
} else {
bwipjs.request(req, res);
}
}).listen(3030);
If you run the above code on your local machine, you can test with the following URL:
http://localhost:3030/?bcid=isbn&text=978-1-56581-231-4+52250&includetext&guardwhitespace
The bwip-js request handler only operates on the URL query parameters and
ignores all path information. Your application is free to structure the URL
path as needed to implement the desired HTTP request routing.
Node.js Image Generator
You can use bwip-js to generate PNG images directly.
const bwipjs = require('bwip-js');
bwipjs.toBuffer({
bcid: 'code128',
text: '0123456789',
scale: 3,
height: 10,
includetext: true,
textxalign: 'center',
}, function (err, png) {
if (err) {
} else {
}
});
If you would prefer to work with Promises, omit the callback function and
toBuffer()
will return a Promise:
bwipjs.toBuffer({
bcid: 'code128',
text: '0123456789',
scale: 3,
height: 10,
includetext: true,
textxalign: 'center',
})
.then(png => {
})
.catch(err => {
});
Node.js ES6 Module Usage
The ESM provides the same API as require('bwip-js')
using:
import bwipjs from 'bwip-js';
The ESM also facilitates bundler tree-shaking by providing the individual encoders as named exports. Each exported encoder functions identically to bwipjs.toBuffer()
.
The exported names are the same as the bcid
names, with the caveat that dashes -
are replaced with underscores _
. For example, to import the gs1-128
encoder, you would use:
import { gs1_128 } from 'bwip-js';
try {
let buf = await gs1_128(options);
} catch (e) {
}
When named encoders are called, the bcid
value in the options object is ignored.
SVG (All Platforms)
The easiest way to generate an SVG barcode image is with the toSVG()
method. It takes
the same options object as the other rendering methods.
The method is synchronous.
let svg = bwipjs.toSVG({
bcid: 'code128',
text: '0123456789',
height: 12,
includetext: true,
textxalign: 'center',
textcolor: 'ff0000',
});
The return value from toSVG()
is a string containing a fully qualified SVG definition,
including a viewBox
attribute that defines the natural width and height of the image, in pixels.
<svg viewBox="0 0 242 200" xmlns="http://www.w3.org/2000/svg">
...
</svg>
The viewBox
will always have origin 0 0
.
To display in an HTML page, the following should provide a good start:
let [ , width, height ] = /viewBox="0 0 (\d+) (\d+)"/.exec(svg);
let span = document.createElement('span');
span.style.display = 'inline-block';
span.style.width = width + 'px';
span.style.height = height + 'px';
span.innerHTML = svg;
document.body.appendChild(span);
The toSVG()
method links to all BWIPP encoders, so it cannot be used with
tree-shaking. To reduce bundled size, you can import only the barcode types
you need, along with the built-in SVG drawing interface.
import { qrcode, drawingSVG } from 'bwip-js';
let svg = qrcode(options, drawingSVG());
React Usage
The following is a minimal example of bwip-js in a React app.
It is based on the default App.js
file generated by create-react-app
.
import React, { Component } from 'react';
import logo from './logo.svg';
import './App.css';
import bwipjs from 'bwip-js';
class App extends Component {
componentDidMount() {
try {
let canvas = bwipjs.toCanvas('mycanvas', {
bcid: 'code128',
text: '0123456789',
scale: 3,
height: 10,
includetext: true,
textxalign: 'center',
});
} catch (e) {
}
}
render() {
return (
<div className="App">
<div className="App-header">
<img src={logo} className="App-logo" alt="logo" />
<h2>Welcome to React</h2>
</div>
<canvas id="mycanvas"></canvas>
</div>
);
}
}
export default App;
See the Browser Usage section for details on the toCanvas()
method.
See the ES6 Browser Module Usage section for details on importing encoders directly.
React Native
Note: The react-native module requires an external dependency to polyfill
missing nodejs built-ins zlib
and Buffer
.
You must manually add it to your project. The dependency will not
be included in bwip-js as it is only needed for react-native. To install:
npm install react-zlib-js --save
The react-native module provides a specialized version of the toBuffer()
method,
called toDataURL()
. The return value is an object with the following properties:
height
: The height of the image, in pixels.width
: The width of the image, in pixels.uri
: A string containing the data URL for the image.
The returned object is designed to be used with the <Image>
component:
import React from 'react';
import 'react-zlib-js';
import bwipjs from 'bwip-js';
const BarCode = (options) => {
let img = null;
try {
img = await bwipjs.toDataURL(options);
} catch (e) {
}
return (
<Image
style={{ height:img.height, width:img.width }}
source={{ uri:img.uri }}
/>
);
};
The bwip-js exports also facilitate bundler tree-shaking by providing the individual encoders as named exports. Each exported encoder functions identically to bwipjs.toDataURL()
.
The exported names are the same as the bcid
names, with the caveat that dashes -
are replaced with underscores _
. For example, to import the gs1-128
encoder, you would use:
import { gs1_128 } from 'bwip-js';
try {
let buf = await gs1_128(options);
} catch (e) {
}
When named encoders are called, the bcid
value in the options object is ignored.
Electron Example
There have been some changes to the Electron bundler, and it may pull in either the
nodejs or browser module, depending on your version of Electron. The example below
assumes the nodejs module.
If you try this example and get the error bwipjs.toBuffer is not a function
, the
Electron bundler grabbed the browser module. See the Browser Usage
section above and draw to a canvas instead.
This is an example index.html
file for a basic, single window app:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Hello World!</title>
</head>
<body>
Node.js <script>document.write(process.versions.node)</script>,
Chromium <script>document.write(process.versions.chrome)</script>,
Electron <script>document.write(process.versions.electron)</script>,
bwip-js <script>document.write(bwipjs.BWIPJS_VERSION)</script>,
and BWIPP <script>document.write(bwipjs.BWIPP_VERSION)</script>.
<br><br><img id="myimg">
<pre id="output"></pre>
</body>
<script>
var bwipjs = require('bwip-js');
bwipjs.toBuffer({ bcid:'qrcode', text:'0123456789' }, function (err, png) {
if (err) {
document.getElementById('output').textContent = err;
} else {
document.getElementById('myimg').src = 'data:image/png;base64,' +
png.toString('base64');
}
});
</script>
</html>
Command Line Interface
bwip-js can be used as a command line tool when installed globally:
$ npm install -g bwip-js
$ bwip-js
Usage: bwip-js symbol-name text [options...] file-name
bwip-js --bcid=symbol-name --text=text [options...] file-name
Example:
bwip-js code128 012345678 includetext textcolor=ff0000 my-code128.png
file-name must be type: .png or .svg
Try 'bwip-js --help' for more information.
Try 'bwip-js --symbols' for a list of supported barcode symbols.
To use a custom font with the command line utility, use the --loadfont
option. It
takes one of three formats:
--loadfont=
font-name,
y-mult,
x-mult,
path-to-font-file
--loadfont=
font-name,
size-mult,
path-to-font-file
--loadfont=
font-name,
path-to-font-file
For example:
$ bwip-js code128 12345678 includetext textfont=CONS textxalign=center \
loadfont=CONS,250,100,../fonts/Inconsolata.otf /tmp/code128.png
The above demonstrates how to maniplulate the font metrics so the characters appear
tall and narrow.
Demo HTML App
demo.html
located in the root bwip-js directory is a full featured demonstation
of bwip-js barcode rendering. It uses bwip-js' built-in graphics to draw to a canvas.
The images produced will match pixel-for-pixel with the images produced by the same
nodejs usage.
Examples
There are example html and node apps provided with the project including
how to write your own drawing interface, generating SVG barcode images,
and adding scalable barcodes to a pdfkit document.
See the examples README
for more details.
Supported Barcode Types
- auspost โข AusPost 4 State Customer Code
- azteccode โข Aztec Code
- azteccodecompact โข Compact Aztec Code
- aztecrune โข Aztec Runes
- bc412 โข BC412
- channelcode โข Channel Code
- codablockf โข Codablock F
- code11 โข Code 11
- code128 โข Code 128
- code16k โข Code 16K
- code2of5 โข Code 25
- code32 โข Italian Pharmacode
- code39 โข Code 39
- code39ext โข Code 39 Extended
- code49 โข Code 49
- code93 โข Code 93
- code93ext โข Code 93 Extended
- codeone โข Code One
- coop2of5 โข COOP 2 of 5
- daft โข Custom 4 state symbology
- databarexpanded โข GS1 DataBar Expanded
- databarexpandedcomposite โข GS1 DataBar Expanded Composite
- databarexpandedstacked โข GS1 DataBar Expanded Stacked
- databarexpandedstackedcomposite โข GS1 DataBar Expanded Stacked Composite
- databarlimited โข GS1 DataBar Limited
- databarlimitedcomposite โข GS1 DataBar Limited Composite
- databaromni โข GS1 DataBar Omnidirectional
- databaromnicomposite โข GS1 DataBar Omnidirectional Composite
- databarstacked โข GS1 DataBar Stacked
- databarstackedcomposite โข GS1 DataBar Stacked Composite
- databarstackedomni โข GS1 DataBar Stacked Omnidirectional
- databarstackedomnicomposite โข GS1 DataBar Stacked Omnidirectional Composite
- databartruncated โข GS1 DataBar Truncated
- databartruncatedcomposite โข GS1 DataBar Truncated Composite
- datalogic2of5 โข Datalogic 2 of 5
- datamatrix โข Data Matrix
- datamatrixrectangular โข Data Matrix Rectangular
- datamatrixrectangularextension โข Data Matrix Rectangular Extension
- dotcode โข DotCode
- ean13 โข EAN-13
- ean13composite โข EAN-13 Composite
- ean14 โข GS1-14
- ean2 โข EAN-2 (2 digit addon)
- ean5 โข EAN-5 (5 digit addon)
- ean8 โข EAN-8
- ean8composite โข EAN-8 Composite
- flattermarken โข Flattermarken
- gs1-128 โข GS1-128
- gs1-128composite โข GS1-128 Composite
- gs1-cc โข GS1 Composite 2D Component
- gs1datamatrix โข GS1 Data Matrix
- gs1datamatrixrectangular โข GS1 Data Matrix Rectangular
- gs1dldatamatrix โข GS1 Digital Link Data Matrix
- gs1dlqrcode โข GS1 Digital Link QR Code
- gs1dotcode โข GS1 DotCode
- gs1northamericancoupon โข GS1 North American Coupon
- gs1qrcode โข GS1 QR Code
- hanxin โข Han Xin Code
- hibcazteccode โข HIBC Aztec Code
- hibccodablockf โข HIBC Codablock F
- hibccode128 โข HIBC Code 128
- hibccode39 โข HIBC Code 39
- hibcdatamatrix โข HIBC Data Matrix
- hibcdatamatrixrectangular โข HIBC Data Matrix Rectangular
- hibcmicropdf417 โข HIBC MicroPDF417
- hibcpdf417 โข HIBC PDF417
- hibcqrcode โข HIBC QR Code
- iata2of5 โข IATA 2 of 5
- identcode โข Deutsche Post Identcode
- industrial2of5 โข Industrial 2 of 5
- interleaved2of5 โข Interleaved 2 of 5 (ITF)
- isbn โข ISBN
- ismn โข ISMN
- issn โข ISSN
- itf14 โข ITF-14
- japanpost โข Japan Post 4 State Customer Code
- kix โข Royal Dutch TPG Post KIX
- leitcode โข Deutsche Post Leitcode
- mailmark โข Royal Mail Mailmark
- mands โข Marks & Spencer
- matrix2of5 โข Matrix 2 of 5
- maxicode โข MaxiCode
- micropdf417 โข MicroPDF417
- microqrcode โข Micro QR Code
- msi โข MSI Modified Plessey
- onecode โข USPS Intelligent Mail
- pdf417 โข PDF417
- pdf417compact โข Compact PDF417
- pharmacode โข Pharmaceutical Binary Code
- pharmacode2 โข Two-track Pharmacode
- planet โข USPS PLANET
- plessey โข Plessey UK
- posicode โข PosiCode
- postnet โข USPS POSTNET
- pzn โข Pharmazentralnummer (PZN)
- qrcode โข QR Code
- rationalizedCodabar โข Codabar
- raw โข Custom 1D symbology
- rectangularmicroqrcode โข Rectangular Micro QR Code
- royalmail โข Royal Mail 4 State Customer Code
- sscc18 โข SSCC-18
- swissqrcode โข Swiss QR Code
- symbol โข Miscellaneous symbols
- telepen โข Telepen
- telepennumeric โข Telepen Numeric
- ultracode โข Ultracode
- upca โข UPC-A
- upcacomposite โข UPC-A Composite
- upce โข UPC-E
- upcecomposite โข UPC-E Composite