0
# JsBarcode
1

2
JsBarcode is a JavaScript barcode generator library that creates various types of 1D barcodes including CODE128, EAN, UPC, CODE39, ITF, MSI, and Pharmacode formats. The library is designed to work both in browsers and Node.js environments with canvas support, offering extensive customization options for barcode appearance including width, height, colors, fonts, and text positioning.
3

4
## Package Information
5

6
- **Package Name**: jsbarcode
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install jsbarcode`
10

11
## Core Imports
12

13
Browser (global):
14

15
```javascript
16
// Using the all-in-one minified build
17
<script src="JsBarcode.all.min.js"></script>
18
// JsBarcode is now available globally
19
```
20

21
Node.js (CommonJS):
22

23
```javascript
24
const JsBarcode = require("jsbarcode");
25
```
26

27
jQuery integration:
28

29
```javascript
30
// If jQuery is available, it extends with a plugin
31
$("#barcode").JsBarcode("Hello World!");
32

33
// jQuery plugin signature
34
$("#barcode").JsBarcode(content, options, validFunction);
35
```
36

37
## Basic Usage
38

39
```javascript
40
// Basic barcode generation on canvas element
41
JsBarcode("#barcode", "Hello World!");
42

43
// With specific format and options
44
JsBarcode("#barcode", "123456789012", {
45
  format: "EAN13",
46
  width: 2,
47
  height: 100,
48
  displayValue: true
49
});
50

51
// Using jQuery (if available)
52
$("#barcode").JsBarcode("CODE128", {
53
  fontSize: 24,
54
  textAlign: "center"
55
});
56

57
// Node.js usage with canvas
58
const Canvas = require("canvas");
59
const canvas = new Canvas();
60
JsBarcode(canvas, "Hello World!");
61
```
62

63
## Architecture
64

65
JsBarcode is built around several key components:
66

67
- **Core Engine**: Main `JsBarcode` function that handles rendering to canvas elements or images
68
- **Module System**: Pluggable barcode format encoders that register themselves with the core
69
- **Auto-Detection**: Automatic format selection based on input data characteristics
70
- **Caching System**: Built-in caching of encoded barcode data for performance optimization
71
- **Canvas Rendering**: Direct canvas manipulation for barcode drawing with customizable styling
72
- **CLI Tool**: Command-line interface for generating barcode images from the terminal
73

74
## Capabilities
75

76
### Core Generation Function
77

78
Main barcode generation function that works with HTML canvas elements, images, or DOM selectors.
79

80
```javascript { .api }
81
/**
82
 * Generate a barcode on the specified element
83
 * @param element - Canvas element, image element, or CSS selector string
84
 * @param content - The data to encode as a barcode
85
 * @param options - Configuration options for barcode appearance and format
86
 */
87
function JsBarcode(element, content, options);
88

89
/**
90
 * jQuery plugin for barcode generation
91
 * @param content - The data to encode as a barcode
92
 * @param options - Configuration options for barcode appearance and format
93
 * @param validFunction - Optional validation callback function
94
 * @returns jQuery object for chaining
95
 */
96
$.fn.JsBarcode(content, options, validFunction);
97
```
98

99
### CODE128 Barcodes
100

101
Comprehensive CODE128 barcode support with automatic mode switching and manual mode selection for optimal encoding density.
102

103
```javascript { .api }
104
// Auto mode selection
105
JsBarcode(canvas, "Hello123", { format: "CODE128" });
106

107
// Manual mode selection
108
JsBarcode(canvas, "HELLO", { format: "CODE128A" });
109
JsBarcode(canvas, "Hello123", { format: "CODE128B" });
110
JsBarcode(canvas, "1234567890", { format: "CODE128C" });
111
```
112

113
[CODE128 Barcodes](./code128.md)
114

115
### EAN and UPC Barcodes
116

117
Complete support for European Article Number (EAN) and Universal Product Code (UPC) formats with automatic checksum calculation.
118

119
```javascript { .api }
120
// EAN-13 (with automatic checksum)
121
JsBarcode(canvas, "123456789012", { format: "EAN13" });
122

123
// EAN-8 
124
JsBarcode(canvas, "1234567", { format: "EAN8" });
125

126
// UPC-A
127
JsBarcode(canvas, "12345678901", { format: "UPC" });
128

129
// EAN addon codes
130
JsBarcode(canvas, "12345", { format: "EAN5" });
131
JsBarcode(canvas, "12", { format: "EAN2" });
132
```
133

134
[EAN and UPC Barcodes](./ean-upc.md)
135

136
### Industrial and Specialized Formats
137

138
Support for CODE39, ITF (Interleaved 2 of 5), MSI, and Pharmacode formats commonly used in industrial and specialized applications.
139

140
```javascript { .api }
141
// CODE39 (alphanumeric)
142
JsBarcode(canvas, "HELLO123", { format: "CODE39" });
143

144
// ITF (even-length numeric)
145
JsBarcode(canvas, "1234567890", { format: "ITF" });
146

147
// ITF-14 (GTIN-14)
148
JsBarcode(canvas, "1234567890123", { format: "ITF14" });
149

150
// MSI with various checksum options
151
JsBarcode(canvas, "123456", { format: "MSI" });
152
JsBarcode(canvas, "123456", { format: "MSI10" });
153

154
// Pharmacode
155
JsBarcode(canvas, "12345", { format: "pharmacode" });
156
```
157

158
[Industrial and Specialized Formats](./industrial-formats.md)
159

160
### Configuration and Customization
161

162
Extensive customization options for barcode appearance, sizing, colors, fonts, and text positioning.
163

164
```javascript { .api }
165
const defaultOptions = {
166
  width: 2,              // Width of a single bar
167
  height: 100,           // Height of the barcode
168
  format: "auto",        // Barcode format or "auto" for detection
169
  displayValue: true,    // Show text below barcode
170
  fontOptions: "",       // Font style (e.g., "bold", "italic")
171
  font: "monospace",     // Font family
172
  textAlign: "center",   // Text alignment: "left", "center", "right"
173
  textPosition: "bottom", // Text position: "top", "bottom"
174
  textMargin: 2,         // Space between barcode and text
175
  fontSize: 20,          // Font size in pixels
176
  background: "#ffffff", // Background color
177
  lineColor: "#000000",  // Barcode line color
178
  margin: 10,            // All margins
179
  marginTop: undefined,  // Individual margin overrides
180
  marginBottom: undefined,
181
  marginLeft: undefined,
182
  marginRight: undefined,
183
  valid: function(valid) {} // Validation callback
184
};
185
```
186

187
[Configuration and Options](./configuration.md)
188

189
### Command Line Interface
190

191
Node.js command-line tool for generating barcode images with extensive format and styling options.
192

193
```bash { .api }
194
# Basic usage
195
JsBarcode "Hello World!" -o barcode.png
196

197
# With format and styling
198
JsBarcode "123456789012" -f EAN13 -W 3 -H 150 -d --background white --lineColor black
199

200
# Output to stdout
201
JsBarcode "CODE39" -f CODE39 -s | cat > barcode.png
202
```
203

204
[Command Line Interface](./cli.md)
205

206
## Module System and Extensions
207

208
### Format Registration
209

210
```javascript { .api }
211
/**
212
 * Register a new barcode format module
213
 * @param module - Constructor function for the barcode encoder
214
 * @param regex - Regular expression pattern to match the format name
215
 * @param priority - Priority for auto-selection (higher = preferred)
216
 */
217
JsBarcode.register(module, regex, priority);
218

219
/**
220
 * Get a registered barcode module by format name
221
 * @param name - Format name to lookup
222
 * @returns Constructor for the barcode encoder
223
 */
224
JsBarcode.getModule(name);
225

226
/**
227
 * Automatically select the best encoder for the given content
228
 * @param content - Data to encode
229
 * @returns Constructor for the most suitable barcode encoder
230
 */
231
JsBarcode.autoSelectEncoder(content);
232
```
233

234
### Performance and Caching
235

236
```javascript { .api }
237
/**
238
 * Cache encoded barcode data for reuse
239
 * @param format - Barcode format name
240
 * @param input - Input data
241
 * @param output - Encoded binary data
242
 */
243
JsBarcode.cache(format, input, output);
244

245
/**
246
 * Retrieve cached barcode data
247
 * @param format - Barcode format name
248
 * @param input - Input data
249
 * @returns Cached binary data or empty string if not found
250
 */
251
JsBarcode.getCache(format, input);
252
```
253

254
## Error Handling
255

256
JsBarcode throws descriptive errors for common issues:
257

258
```javascript
259
try {
260
  JsBarcode(canvas, "invalid", { format: "EAN13" });
261
} catch (error) {
262
  // "The data is not valid for the type of barcode."
263
}
264

265
try {
266
  JsBarcode(canvas, "test", { format: "NONEXISTENT" });
267
} catch (error) {
268
  // "Module NONEXISTENT does not exist or is not loaded."
269
}
270

271
try {
272
  JsBarcode("invalid-selector", "test");
273
} catch (error) {
274
  // "Not supported type to draw on."
275
}
276
```
277

278
Use the `valid` callback option for custom error handling:
279

280
```javascript
281
JsBarcode(canvas, "potentially-invalid", {
282
  format: "EAN13",
283
  valid: function(isValid) {
284
    if (!isValid) {
285
      console.log("Barcode generation failed");
286
      // Handle invalid data gracefully
287
    }
288
  }
289
});
290
```