0
# Configuration and Options
1
2
Comprehensive configuration system for QR code generation parameters and rendering customization. These options apply across all QRCode functions to control QR code structure, appearance, and output format.
3
4
## QR Code Generation Options
5
6
### Version Selection
7
8
Controls the size and data capacity of the QR code symbol.
9
10
```javascript { .api }
11
interface VersionOptions {
12
/** QR Code version (1-40), auto-selected if not specified */
13
version?: number;
14
}
15
```
16
17
**Details:**
18
19
- **Version 1**: 21×21 modules, up to 25 alphanumeric characters
20
- **Version 40**: 177×177 modules, up to 4,296 alphanumeric characters
21
- **Auto-selection**: Uses minimum version that fits the data (recommended)
22
23
**Examples:**
24
25
```javascript
26
// Auto version (recommended)
27
QRCode.create('Auto-sized text');
28
29
// Specific version
30
QRCode.create('Fixed size', { version: 5 });
31
32
// Version too small (throws error)
33
try {
34
QRCode.create('Very long text that exceeds capacity', { version: 1 });
35
} catch (err) {
36
console.log(err.message); // "The chosen QR Code version cannot contain..."
37
}
38
```
39
40
### Error Correction Level
41
42
Determines how much of the QR code can be damaged while remaining readable.
43
44
```javascript { .api }
45
interface ErrorCorrectionOptions {
46
/** Error correction level */
47
errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H' | 'low' | 'medium' | 'quartile' | 'high';
48
}
49
50
// Error correction levels with damage tolerance
51
const ErrorCorrectionLevels = {
52
L: '~7%', // Low
53
M: '~15%', // Medium (default)
54
Q: '~25%', // Quartile
55
H: '~30%' // High
56
};
57
```
58
59
**Examples:**
60
61
```javascript
62
// Default (Medium ~15% error correction)
63
QRCode.create('Standard text');
64
65
// High error correction for critical data
66
QRCode.create('Important data', { errorCorrectionLevel: 'H' });
67
68
// Low error correction for size optimization
69
QRCode.create('Large data', { errorCorrectionLevel: 'L' });
70
71
// String formats accepted
72
QRCode.create('text', { errorCorrectionLevel: 'high' }); // 'high'
73
QRCode.create('text', { errorCorrectionLevel: 'quartile' }); // 'quartile'
74
QRCode.create('text', { errorCorrectionLevel: 'Q' }); // 'Q'
75
```
76
77
### Mask Pattern Selection
78
79
Controls the pattern used to avoid problematic visual arrangements.
80
81
```javascript { .api }
82
interface MaskOptions {
83
/** Mask pattern (0-7), auto-selected if not specified */
84
maskPattern?: number;
85
}
86
```
87
88
**Examples:**
89
90
```javascript
91
// Auto mask selection (recommended)
92
QRCode.create('Auto mask');
93
94
// Specific mask pattern
95
QRCode.create('Fixed mask', { maskPattern: 3 });
96
97
// Invalid mask pattern (ignored, auto-selected)
98
QRCode.create('text', { maskPattern: 8 }); // Uses auto-selection
99
```
100
101
### Kanji Mode Configuration
102
103
Enables optimal encoding of Japanese Kanji characters.
104
105
```javascript { .api }
106
interface KanjiOptions {
107
/** Function to convert UTF-8 characters to Shift JIS values */
108
toSJISFunc?: (char: string) => number;
109
}
110
```
111
112
**Examples:**
113
114
```javascript
115
// Node.js Kanji support
116
const toSJIS = require('qrcode/helper/to-sjis');
117
118
QRCode.create('漢字テスト', {
119
toSJISFunc: toSJIS
120
});
121
122
// Browser Kanji support
123
// <script src="qrcode.js"></script>
124
// <script src="qrcode.tosjis.js"></script>
125
QRCode.create('漢字', {
126
toSJISFunc: QRCode.toSJIS
127
});
128
129
// Without Kanji support (uses Byte mode)
130
QRCode.create('漢字'); // Still works, but less optimal encoding
131
```
132
133
## Rendering Options
134
135
### Size and Scaling
136
137
Controls the physical dimensions of the QR code output.
138
139
```javascript { .api }
140
interface SizeOptions {
141
/** Force specific width in pixels (takes precedence over scale) */
142
width?: number;
143
144
/** Scale factor - 1 means 1px per module */
145
scale?: number; // Default: 4
146
147
/** Quiet zone margin size in modules */
148
margin?: number; // Default: 4
149
}
150
```
151
152
**Examples:**
153
154
```javascript
155
// Fixed width (overrides scale)
156
QRCode.toDataURL('Fixed width', { width: 300 });
157
158
// Scale factor
159
QRCode.toDataURL('Scaled', { scale: 8 }); // 8px per module
160
161
// No margin
162
QRCode.toDataURL('No margin', { margin: 0 });
163
164
// Large margin
165
QRCode.toDataURL('Large margin', { margin: 10 });
166
167
// Size calculation: final size = (modules + 2*margin) * scale
168
// Example: Version 1 (21 modules) + margin 4 + scale 4 = (21 + 8) * 4 = 116px
169
```
170
171
### Color Customization
172
173
Controls the appearance of QR code modules and background.
174
175
```javascript { .api }
176
interface ColorOptions {
177
color?: {
178
/** Dark module color in hex RGBA format */
179
dark?: string; // Default: '#000000ff'
180
181
/** Light module color in hex RGBA format */
182
light?: string; // Default: '#ffffffff'
183
};
184
}
185
```
186
187
**Examples:**
188
189
```javascript
190
// Custom colors
191
QRCode.toDataURL('Colored QR', {
192
color: {
193
dark: '#0066CC', // Blue modules
194
light: '#FFFFFF' // White background
195
}
196
});
197
198
// Transparent background
199
QRCode.toDataURL('Transparent', {
200
color: {
201
dark: '#000000',
202
light: '#00000000' // Transparent background
203
}
204
});
205
206
// High contrast
207
QRCode.toDataURL('High contrast', {
208
color: {
209
dark: '#000000FF', // Pure black
210
light: '#FFFFFFFF' // Pure white
211
}
212
});
213
214
// Brand colors
215
QRCode.toDataURL('Brand QR', {
216
color: {
217
dark: '#FF6B35FF', // Brand orange
218
light: '#F7F7F7FF' // Light gray
219
}
220
});
221
```
222
223
### Terminal-Specific Options
224
225
Options for terminal and console output.
226
227
```javascript { .api }
228
interface TerminalOptions {
229
/** Compact terminal output using smaller characters */
230
small?: boolean; // Default: false
231
232
/** Invert foreground and background colors */
233
inverse?: boolean; // Default: false
234
}
235
```
236
237
**Examples:**
238
239
```javascript
240
// Standard terminal output
241
QRCode.toString('Terminal', { type: 'terminal' });
242
243
// Compact output for small terminals
244
QRCode.toString('Compact', {
245
type: 'terminal',
246
small: true
247
});
248
249
// Inverted colors
250
QRCode.toString('Inverted', {
251
type: 'terminal',
252
inverse: true
253
});
254
255
// Combined terminal options
256
QRCode.toString('Custom terminal', {
257
type: 'terminal',
258
small: true,
259
inverse: true
260
});
261
```
262
263
## Format-Specific Options
264
265
### PNG Options
266
267
PNG-specific rendering configuration (Node.js only).
268
269
```javascript { .api }
270
interface PNGOptions {
271
type?: 'png';
272
273
/** PNG-specific renderer options */
274
rendererOpts?: {
275
/** Deflate compression level (0-9) */
276
deflateLevel?: number; // Default: 9
277
278
/** Deflate compression strategy (0-3) */
279
deflateStrategy?: number; // Default: 3
280
};
281
}
282
```
283
284
**Examples:**
285
286
```javascript
287
// Maximum compression (default)
288
QRCode.toFile('compressed.png', 'text', {
289
type: 'png',
290
rendererOpts: {
291
deflateLevel: 9, // Best compression
292
deflateStrategy: 3 // Default strategy
293
}
294
});
295
296
// Fast compression
297
QRCode.toFile('fast.png', 'text', {
298
type: 'png',
299
rendererOpts: {
300
deflateLevel: 1, // Fastest compression
301
deflateStrategy: 0 // Speed-optimized
302
}
303
});
304
305
// No compression
306
QRCode.toFile('uncompressed.png', 'text', {
307
type: 'png',
308
rendererOpts: {
309
deflateLevel: 0 // No compression
310
}
311
});
312
```
313
314
### Data URL Options
315
316
Options for browser data URL generation.
317
318
```javascript { .api }
319
interface DataURLOptions {
320
/** Image MIME type for data URLs */
321
type?: 'image/png' | 'image/jpeg' | 'image/webp'; // Default: 'image/png'
322
323
/** Format-specific options */
324
rendererOpts?: {
325
/** Image quality for JPEG/WebP (0.0 to 1.0) */
326
quality?: number; // Default: 0.92
327
};
328
}
329
```
330
331
**Examples:**
332
333
```javascript
334
// PNG data URL (default)
335
const pngURL = await QRCode.toDataURL('PNG QR');
336
337
// JPEG with quality
338
const jpegURL = await QRCode.toDataURL('JPEG QR', {
339
type: 'image/jpeg',
340
rendererOpts: { quality: 0.8 }
341
});
342
343
// WebP with high quality
344
const webpURL = await QRCode.toDataURL('WebP QR', {
345
type: 'image/webp',
346
rendererOpts: { quality: 0.95 }
347
});
348
349
// Low quality for smaller size
350
const lowQualityURL = await QRCode.toDataURL('Small QR', {
351
type: 'image/jpeg',
352
rendererOpts: { quality: 0.3 }
353
});
354
```
355
356
## Complete Configuration Examples
357
358
### High-Quality Print QR Code
359
360
```javascript
361
const printQR = await QRCode.toFile('print-qr.png', 'https://example.com', {
362
version: 3, // Fixed size for consistent layout
363
errorCorrectionLevel: 'H', // High error correction for durability
364
width: 500, // Large size for print clarity
365
margin: 6, // Extra margin for printing
366
color: {
367
dark: '#000000FF', // Pure black for maximum contrast
368
light: '#FFFFFFFF' // Pure white background
369
},
370
type: 'png',
371
rendererOpts: {
372
deflateLevel: 9 // Maximum compression for file size
373
}
374
});
375
```
376
377
### Web-Optimized QR Code
378
379
```javascript
380
const webQR = await QRCode.toDataURL('https://example.com', {
381
errorCorrectionLevel: 'M', // Balanced error correction
382
width: 200, // Web-appropriate size
383
margin: 2, // Minimal margin for space efficiency
384
color: {
385
dark: '#2C3E50', // Dark blue-gray
386
light: '#ECF0F1' // Light gray
387
},
388
type: 'image/png' // PNG for transparency support
389
});
390
```
391
392
### Mobile-Friendly QR Code
393
394
```javascript
395
const mobileQR = await QRCode.toCanvas(canvas, 'mobile://action', {
396
errorCorrectionLevel: 'Q', // Higher error correction for camera scanning
397
width: 300, // Large enough for mobile cameras
398
margin: 4, // Standard margin
399
color: {
400
dark: '#1ABC9C', // Vibrant teal
401
light: '#FFFFFF' // White background
402
}
403
});
404
```
405
406
### Terminal Display QR Code
407
408
```javascript
409
const terminalQR = await QRCode.toString('Terminal QR', {
410
type: 'terminal',
411
errorCorrectionLevel: 'L', // Lower error correction for size
412
small: process.stdout.columns < 80, // Adapt to terminal width
413
inverse: false // Standard colors
414
});
415
console.log(terminalQR);
416
```
417
418
### SVG for Scalable Graphics
419
420
```javascript
421
const svgQR = await QRCode.toString('https://example.com', {
422
type: 'svg',
423
width: 400, // SVG width attribute
424
margin: 3, // Moderate margin
425
color: {
426
dark: '#8E44AD', // Purple modules
427
light: '#F8F9FA' // Light background
428
}
429
});
430
```
431
432
## Option Validation and Defaults
433
434
### Default Values
435
436
```javascript { .api }
437
const DefaultOptions = {
438
// QR Code options
439
version: undefined, // Auto-select
440
errorCorrectionLevel: 'M', // Medium (~15% error correction)
441
maskPattern: undefined, // Auto-select
442
toSJISFunc: undefined, // No Kanji support
443
444
// Rendering options
445
margin: 4, // 4 modules quiet zone
446
scale: 4, // 4px per module
447
width: undefined, // Use scale instead
448
color: {
449
dark: '#000000ff', // Black modules
450
light: '#ffffffff' // White background
451
},
452
453
// Terminal options
454
small: false, // Full-size terminal output
455
inverse: false, // Normal colors
456
457
// Format options
458
type: 'png', // Default output type
459
rendererOpts: {
460
deflateLevel: 9, // Maximum PNG compression
461
deflateStrategy: 3, // Default PNG strategy
462
quality: 0.92 // JPEG/WebP quality
463
}
464
};
465
```
466
467
### Option Precedence
468
469
1. **Explicit options** - Options passed to function calls
470
2. **Format defaults** - Default values for specific output formats
471
3. **Global defaults** - Library-wide default values
472
473
### Validation Rules
474
475
```javascript
476
// Version validation (1-40)
477
if (options.version < 1 || options.version > 40) {
478
// Uses auto-selection
479
}
480
481
// Error correction level validation
482
const validECLevels = ['L', 'M', 'Q', 'H', 'low', 'medium', 'quartile', 'high'];
483
if (!validECLevels.includes(options.errorCorrectionLevel)) {
484
// Uses default 'M'
485
}
486
487
// Mask pattern validation (0-7)
488
if (options.maskPattern < 0 || options.maskPattern > 7) {
489
// Uses auto-selection
490
}
491
492
// Color format validation (hex RGBA)
493
if (!/^#[0-9A-Fa-f]{6,8}$/.test(options.color.dark)) {
494
// Uses default color
495
}
496
497
// Width/scale validation
498
if (options.width && options.width < minRequiredSize) {
499
// Ignores width, uses scale
500
}
501
```