0
# Core QR Generation
1

2
Core QR code symbol generation functionality that handles automatic mode selection, error correction, and optimization for minimal QR code size.
3

4
## Capabilities
5

6
### Create QR Symbol
7

8
Creates a QR code symbol object containing all the data needed for rendering.
9

10
```javascript { .api }
11
/**
12
 * Creates QR Code symbol and returns a qrcode object
13
 * @param {string|Array} text - Text to encode or array of segments
14
 * @param {Object} options - Optional configuration
15
 * @returns {Object} QRCode object with modules, version, errorCorrectionLevel, maskPattern, segments
16
 */
17
function create(text, options);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const QRCode = require('qrcode');
24

25
// Simple text encoding
26
const qrCode = QRCode.create('Hello World');
27
console.log(qrCode.version); // QR Code version (1-40)
28
console.log(qrCode.errorCorrectionLevel); // Error correction level
29
console.log(qrCode.modules); // BitMatrix with QR code data
30

31
// With options
32
const qrCode = QRCode.create('Hello World', {
33
  errorCorrectionLevel: 'H',
34
  version: 5,
35
  maskPattern: 3
36
});
37

38
// Manual segments
39
const segments = [
40
  { data: 'HELLO', mode: 'alphanumeric' },
41
  { data: '123', mode: 'numeric' }
42
];
43
const qrCode = QRCode.create(segments);
44
```
45

46
## Input Data Types
47

48
### String Input
49

50
Simple string input with automatic mode optimization:
51

52
```javascript
53
const qrCode = QRCode.create('Hello World 123');
54
// Automatically optimized into mixed segments for minimal size
55
```
56

57
### Segment Array Input
58

59
Manual segment specification for precise control:
60

61
```javascript
62
const segments = [
63
  { data: 'HELLO WORLD', mode: 'alphanumeric' },  // 0-9, A-Z, space, $%*+-./:
64
  { data: '12345678', mode: 'numeric' },           // 0-9 only
65
  { data: 'Hello 世界', mode: 'byte' },             // Any UTF-8 characters
66
  { data: '漢字', mode: 'kanji' }                   // Kanji characters (requires toSJISFunc)
67
];
68

69
const qrCode = QRCode.create(segments, {
70
  toSJISFunc: require('qrcode/helper/to-sjis') // For Kanji mode
71
});
72
```
73

74
### Binary Data Input
75

76
Binary data using typed arrays, buffers, or regular arrays:
77

78
```javascript
79
// Using Uint8ClampedArray
80
const binarySegments = [
81
  { data: new Uint8ClampedArray([253, 254, 255]), mode: 'byte' }
82
];
83

84
// Using Node.js Buffer
85
const bufferSegments = [
86
  { data: Buffer.from([253, 254, 255]), mode: 'byte' }
87
];
88

89
// Using regular array (values clamped to 0-255)
90
const arraySegments = [
91
  { data: [253, 254, 255], mode: 'byte' }
92
];
93
```
94

95
## Return Object Structure
96

97
The `create()` function returns a QR code object with the following structure:
98

99
```javascript { .api }
100
interface QRCodeObject {
101
  /** BitMatrix containing the QR code modules (black/white dots) */
102
  modules: BitMatrix;
103
  /** Calculated QR code version (1-40) */
104
  version: number;
105
  /** Error correction level used */
106
  errorCorrectionLevel: ErrorCorrectionLevel;
107
  /** Mask pattern applied to the symbol */
108
  maskPattern: number;
109
  /** Generated segments used for encoding */
110
  segments: Segment[];
111
}
112

113
interface BitMatrix {
114
  /** Size of the matrix (modules per side) */
115
  size: number;
116
  /** Get the value of a module at row, col */
117
  get(row: number, col: number): boolean;
118
  /** Set the value of a module at row, col */
119
  set(row: number, col: number, value: boolean, reserved?: boolean): void;
120
  /** Check if a module position is reserved for QR code structure */
121
  isReserved(row: number, col: number): boolean;
122
}
123

124
interface Segment {
125
  /** Encoding mode used for this segment */
126
  mode: Mode;
127
  /** Raw data for this segment */
128
  data: any;
129
  /** Get the length of data in this segment */
130
  getLength(): number;
131
  /** Write segment data to a bit buffer */
132
  write(buffer: BitBuffer): void;
133
}
134
```
135

136
## Encoding Modes
137

138
### Automatic Mode Selection
139

140
By default, QRCode automatically analyzes input text and creates optimized segments:
141

142
```javascript
143
// This text will be automatically split into optimal segments
144
const text = 'HELLO123world!@#';
145
// Result: 
146
// - 'HELLO' -> alphanumeric mode
147
// - '123' -> numeric mode  
148
// - 'world!@#' -> byte mode
149
```
150

151
### Mode Constants
152

153
Available encoding modes for manual segment specification:
154

155
```javascript { .api }
156
const Mode = {
157
  NUMERIC: { id: 'Numeric', bit: 1 },      // 0-9 (3 chars = 10 bits)
158
  ALPHANUMERIC: { id: 'Alphanumeric', bit: 2 }, // 0-9,A-Z,space,$%*+-./:  (2 chars = 11 bits)
159
  BYTE: { id: 'Byte', bit: 4 },            // ISO/IEC 8859-1 (1 char = 8 bits)
160
  KANJI: { id: 'Kanji', bit: 8 }           // Shift JIS (1 kanji = 13 bits)
161
};
162
```
163

164
## Error Correction Levels
165

166
Error correction allows QR codes to be readable even when partially damaged:
167

168
```javascript { .api }
169
const ErrorCorrectionLevel = {
170
  L: { bit: 1 }, // Low - ~7% error resistance
171
  M: { bit: 0 }, // Medium - ~15% error resistance (default)
172
  Q: { bit: 3 }, // Quartile - ~25% error resistance  
173
  H: { bit: 2 }  // High - ~30% error resistance
174
};
175
```
176

177
**Usage:**
178

179
```javascript
180
const qrCode = QRCode.create('Important Data', {
181
  errorCorrectionLevel: 'H' // High error correction for critical data
182
});
183
```
184

185
## Version Selection
186

187
QR code versions (1-40) determine the size and data capacity:
188

189
```javascript
190
// Automatic version selection (recommended)
191
const qrCode = QRCode.create('Some text'); // Uses minimum required version
192

193
// Manual version specification
194
const qrCode = QRCode.create('Some text', { version: 10 });
195

196
// Version validation - will throw error if text doesn't fit
197
try {
198
  const qrCode = QRCode.create('Very long text...', { version: 1 });
199
} catch (err) {
200
  console.log('Text too long for version 1');
201
}
202
```
203

204
## Advanced Options
205

206
### Mask Pattern Selection
207

208
QR codes use mask patterns to avoid problematic visual patterns:
209

210
```javascript
211
// Automatic mask selection (recommended)
212
const qrCode = QRCode.create('text');
213

214
// Manual mask pattern (0-7)
215
const qrCode = QRCode.create('text', { maskPattern: 3 });
216
```
217

218
### Kanji Mode Configuration
219

220
For Kanji mode support, provide a conversion function:
221

222
```javascript
223
const toSJIS = require('qrcode/helper/to-sjis');
224

225
const qrCode = QRCode.create('漢字テスト', {
226
  toSJISFunc: toSJIS
227
});
228
```
229

230
**Browser usage:**
231

232
```html
233
<script src="/build/qrcode.js"></script>
234
<script src="/build/qrcode.tosjis.js"></script>
235
<script>
236
const qrCode = QRCode.create('漢字', { toSJISFunc: QRCode.toSJIS });
237
</script>
238
```
239

240
## Error Handling
241

242
The `create()` function throws errors for:
243

244
```javascript
245
// Empty or undefined input  
246
try {
247
  QRCode.create('');
248
} catch (err) {
249
  console.log(err.message); // "No input text"
250
}
251

252
// Data too large for QR code
253
try {
254
  QRCode.create('x'.repeat(8000), { errorCorrectionLevel: 'H' });
255
} catch (err) {
256
  console.log(err.message); // "The amount of data is too big..."
257
}
258

259
// Version too small for data
260
try {
261
  QRCode.create('Long text', { version: 1 });
262
} catch (err) {
263
  console.log(err.message); // "The chosen QR Code version cannot contain..."
264
}
265

266
// Invalid segment data
267
try {
268
  QRCode.create([{ data: 123, mode: 'invalid' }]);
269
} catch (err) {
270
  console.log(err.message); // "Invalid data"
271
}
272
```