0
# QRCode
1

2
QRCode is a comprehensive JavaScript library for generating QR codes that works seamlessly in both server-side Node.js environments and client-side browser applications. It offers multiple rendering options including canvas, SVG, PNG, and terminal output, supports all standard QR code encoding modes (Numeric, Alphanumeric, Kanji, and Byte), and provides advanced features like automatic mode optimization for minimal QR code size, mixed-mode encoding, error correction level selection, and multibyte character support including emojis.
3

4
## Package Information
5

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

11
## Core Imports
12

13
**Node.js (Server-side):**
14
```javascript
15
const QRCode = require('qrcode');
16
// Main entry point: ./lib/index.js -> ./lib/server.js
17
```
18

19
**ES6/TypeScript:**
20
```javascript
21
import QRCode from 'qrcode';
22
```
23

24
**Browser (Module bundlers like Webpack/Browserify):**
25
```javascript
26
const QRCode = require('qrcode');
27
// Browser entry point: ./lib/browser.js (configured in package.json)
28
```
29

30
**Browser (Precompiled bundle):**
31
```html
32
<script src="/node_modules/qrcode/build/qrcode.js"></script>
33
<!-- QRCode is now available globally -->
34
```
35

36
## Basic Usage
37

38
```javascript
39
const QRCode = require('qrcode');
40

41
// Generate QR code as Data URL (PNG)
42
QRCode.toDataURL('Hello World', function (err, url) {
43
  if (err) throw err;
44
  console.log(url); // data:image/png;base64,iVBORw0KGgoAAAA...
45
});
46

47
// Generate QR code as SVG string
48
QRCode.toString('Hello World', { type: 'svg' }, function (err, string) {
49
  if (err) throw err;
50
  console.log(string); // <svg xmlns="http://www.w3.org/2000/svg"...
51
});
52

53
// Using Promises (Node.js 8+)
54
try {
55
  const url = await QRCode.toDataURL('Hello World');
56
  const svg = await QRCode.toString('Hello World', { type: 'svg' });
57
} catch (err) {
58
  console.error(err);
59
}
60
```
61

62
## Architecture
63

64
QRCode is built around several key components:
65

66
- **Core Engine**: QR code symbol generation with automatic mode selection and error correction
67
- **Rendering System**: Multiple output renderers (PNG, SVG, Canvas, Terminal, UTF-8) with consistent options
68
- **Platform Adapters**: Separate entry points for Node.js and browser environments
69
- **Data Encoding**: Support for all QR code modes (Numeric, Alphanumeric, Byte, Kanji) with automatic optimization
70
- **Configuration System**: Comprehensive options for QR code generation and rendering customization
71

72
## Capabilities
73

74
### Core QR Generation
75

76
Creates QR code symbols with automatic optimization and supports all standard encoding modes and error correction levels.
77

78
```javascript { .api }
79
/**
80
 * Creates QR Code symbol and returns a qrcode object
81
 * @param {string|Array} text - Text to encode or array of segments
82
 * @param {Object} options - Optional configuration
83
 * @returns {Object} QRCode object with modules, version, errorCorrectionLevel, maskPattern, segments
84
 */
85
function create(text, options);
86
```
87

88
[Core Generation](./core-generation.md)
89

90
### Browser Canvas Rendering
91

92
Renders QR codes to HTML5 canvas elements and generates data URLs for browser applications.
93

94
```javascript { .api }
95
/**
96
 * Draws QR code to canvas or creates new canvas
97
 * Overloaded function with multiple signatures
98
 */
99
function toCanvas(canvasElement, text, options, callback);
100
function toCanvas(text, options, callback);
101

102
/**
103
 * Generates data URL containing QR code image
104
 * Overloaded function with multiple signatures  
105
 */ 
106
function toDataURL(text, options, callback);
107
function toDataURL(canvasElement, text, options, callback);
108
```
109

110
[Browser Rendering](./browser-rendering.md)
111

112
### Server-side File Operations
113

114
Server-only functions for saving QR codes to files, generating buffers, and streaming output.
115

116
```javascript { .api }
117
/**
118
 * Saves QR Code to image file with automatic format detection
119
 */
120
function toFile(path, text, options, callback);
121

122
/**
123
 * Generates QR code as Node.js Buffer
124
 */
125
function toBuffer(text, options, callback); 
126

127
/**
128
 * Writes QR Code to a writable stream (PNG only)
129
 */
130
function toFileStream(stream, text, options);
131
```
132

133
[Server Operations](./server-operations.md)
134

135
### String Output Rendering
136

137
Generates string representations of QR codes in multiple formats including UTF-8, SVG, and terminal output.
138

139
```javascript { .api }
140
/**
141
 * Returns a string representation of the QR Code
142
 * @param {string|Array} text - Text to encode or segments  
143
 * @param {Object} options - String rendering options
144
 * @param {Function} callback - Callback with (error, string)
145
 * @returns {Promise<string>} String when using promises
146
 */
147
function toString(text, options, callback);
148
```
149

150
[String Rendering](./string-rendering.md)
151

152
### Configuration and Options
153

154
Comprehensive configuration system for QR code generation parameters and rendering customization.
155

156
[Configuration](./configuration.md)
157

158
## Advanced Features
159

160
### Manual Segment Mode
161

162
For advanced users who need precise control over QR code encoding:
163

164
```javascript
165
const segments = [
166
  { data: 'HELLO', mode: 'alphanumeric' },
167
  { data: '123456', mode: 'numeric' }
168
];
169

170
QRCode.toDataURL(segments, function (err, url) {
171
  console.log(url);
172
});
173
```
174

175
### Binary Data Support
176

177
Encode binary data using Uint8ClampedArray or Buffer:
178

179
```javascript
180
const binaryData = [{ data: new Uint8ClampedArray([253, 254, 255]), mode: 'byte' }];
181
QRCode.toFile('binary.png', binaryData);
182
```
183

184
### Kanji Mode Support
185

186
Include optional SJIS conversion for Kanji mode:
187

188
```javascript
189
const toSJIS = require('qrcode/helper/to-sjis');
190

191
QRCode.toDataURL('漢字', { toSJISFunc: toSJIS }, function (err, url) {
192
  console.log(url);
193
});
194
```
195

196
## Error Handling
197

198
All functions support both callback and Promise patterns. Errors are thrown for:
199

200
- Invalid input data
201
- Data too large for specified QR code version
202
- Invalid configuration options
203
- File system errors (server-side functions)
204

205
## CLI Interface
206

207
The package includes a comprehensive command-line interface accessible after global installation:
208

209
```bash
210
npm install -g qrcode
211

212
# Generate QR code in terminal (UTF-8 output)
213
qrcode "Hello World"
214

215
# Save as PNG file with auto format detection  
216
qrcode -o hello.png "Hello World"
217

218
# Save as SVG file
219
qrcode -o hello.svg "Hello World"
220

221
# Customize colors and options
222
qrcode -d FF0000 -l FFFFFF -o red.png "Hello World"
223

224
# Advanced options
225
qrcode -v 5 -e H -w 300 -o large.png "Important Data"
226

227
# Terminal output with custom options
228
qrcode --small --inverse "Compact Display"
229

230
# Read from stdin
231
echo "Dynamic Content" | qrcode -o dynamic.png
232
```
233

234
**Available CLI Options:**
235
- `-v, --qversion`: QR Code version (1-40)
236
- `-e, --error`: Error correction level (L, M, Q, H)
237
- `-m, --mask`: Mask pattern (0-7)  
238
- `-t, --type`: Output type (png, svg, utf8)
239
- `-w, --width`: Image width in pixels
240
- `-s, --scale`: Scale factor
241
- `-q, --qzone`: Quiet zone size
242
- `-l, --lightcolor`: Light RGBA hex color
243
- `-d, --darkcolor`: Dark RGBA hex color
244
- `--small`: Compact terminal output
245
- `-i, --inverse`: Invert colors
246
- `-o, --output`: Output file path