0
# qrcode.react
1

2
A React component library for generating QR codes with SVG or Canvas rendering. Supports comprehensive customization including colors, sizes, error correction levels, margins, and embedded image overlays.
3

4
## Package Information
5

6
- **Package Name**: qrcode.react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Version**: 3.2.0
10

11
## Installation
12

13
```bash
14
npm install qrcode.react
15
```
16

17
## Core Imports
18

19
```typescript
20
import { QRCodeSVG, QRCodeCanvas } from "qrcode.react";
21
```
22

23
```javascript
24
// CommonJS
25
const { QRCodeSVG, QRCodeCanvas } = require("qrcode.react");
26
```
27

28
```typescript
29
// Legacy default import (deprecated)
30
import QRCode from "qrcode.react";
31
```
32

33
## Basic Usage
34

35
```typescript
36
import React from "react";
37
import { QRCodeSVG } from "qrcode.react";
38

39
function App() {
40
  return (
41
    <div>
42
      <QRCodeSVG value="https://reactjs.org/" />
43
    </div>
44
  );
45
}
46
```
47

48
## Core Types
49

50
```typescript { .api }
51
/**
52
 * Core props interface for QR code generation
53
 */
54
interface QRProps {
55
  /** The text or URL to encode in the QR code */
56
  value: string;
57
  /** QR code size in pixels */
58
  size?: number;
59
  /** Error correction level: 'L' (Low), 'M' (Medium), 'Q' (Quartile), 'H' (High) */
60
  level?: string;
61
  /** Background color as CSS color string */
62
  bgColor?: string;
63
  /** Foreground color as CSS color string */
64
  fgColor?: string;
65
  /** CSS styles to apply to the component */
66
  style?: React.CSSProperties;
67
  /** Whether to include the standard 4-module margin */
68
  includeMargin?: boolean;
69
  /** Configuration for embedded image overlay */
70
  imageSettings?: ImageSettings;
71
}
72
```
73

74
```typescript { .api }
75
/**
76
 * Configuration for embedded images in QR codes
77
 */
78
interface ImageSettings {
79
  /** URL or path to the image */
80
  src: string;
81
  /** Image height in pixels */
82
  height: number;
83
  /** Image width in pixels */
84
  width: number;
85
  /** Whether to clear QR modules behind the image for better visibility */
86
  excavate: boolean;
87
  /** X position offset from center (optional) */
88
  x?: number;
89
  /** Y position offset from center (optional) */
90
  y?: number;
91
}
92
```
93

94
```typescript { .api }
95
/**
96
 * Props for SVG-rendered QR codes (matches source QRPropsSVG)
97
 */
98
type QRCodeSVGProps = QRProps & React.SVGProps<SVGSVGElement>;
99
```
100

101
```typescript { .api }
102
/**
103
 * Props for Canvas-rendered QR codes (matches source QRPropsCanvas)
104
 */
105
type QRCodeCanvasProps = QRProps & React.CanvasHTMLAttributes<HTMLCanvasElement>;
106
```
107

108
```typescript { .api }
109
/**
110
 * Props for legacy QRCode component with renderAs discriminated union
111
 */
112
type QRCodeLegacyProps = 
113
  | (QRCodeSVGProps & { renderAs: 'svg' })
114
  | (QRCodeCanvasProps & { renderAs?: 'canvas' });
115
```
116

117
## Capabilities
118

119
### SVG Rendering
120

121
Vector-based QR code rendering with infinite scalability and CSS styling support.
122

123
```typescript { .api }
124
/**
125
 * React component for SVG-based QR code rendering
126
 * @param props - QR code configuration and SVG element props
127
 * @returns SVG element containing the QR code
128
 */
129
function QRCodeSVG(props: QRCodeSVGProps): React.JSX.Element;
130
```
131

132
**Usage Example:**
133
```typescript
134
import { QRCodeSVG } from "qrcode.react";
135

136
<QRCodeSVG
137
  value="https://example.com"
138
  size={256}
139
  level="H"
140
  bgColor="#ffffff"
141
  fgColor="#000000"
142
  includeMargin={true}
143
  className="qr-code"
144
/>
145
```
146

147
### Canvas Rendering
148

149
Bitmap-based QR code rendering with high-DPI display support and automatic pixel ratio handling.
150

151
```typescript { .api }
152
/**
153
 * React component for Canvas-based QR code rendering
154
 * @param props - QR code configuration and canvas element props
155
 * @returns Canvas element containing the QR code
156
 */
157
function QRCodeCanvas(props: QRCodeCanvasProps): React.JSX.Element;
158
```
159

160
**Usage Example:**
161
```typescript
162
import { QRCodeCanvas } from "qrcode.react";
163

164
<QRCodeCanvas
165
  value="https://example.com"
166
  size={256}
167
  level="M"
168
  bgColor="#f0f0f0"
169
  fgColor="#333333"
170
  style={{ border: "1px solid #ccc" }}
171
/>
172
```
173

174
### Image Overlay
175

176
Embed images (logos, icons) within QR codes with optional module excavation for improved scanning.
177

178
**Usage Example:**
179
```typescript
180
import { QRCodeSVG } from "qrcode.react";
181

182
<QRCodeSVG
183
  value="https://example.com"
184
  size={300}
185
  imageSettings={{
186
    src: "https://example.com/logo.png",
187
    height: 60,
188
    width: 60,
189
    excavate: true
190
  }}
191
/>
192
```
193

194
**Image Settings Properties:**
195
- `src`: Image URL or path
196
- `height`, `width`: Image dimensions in pixels
197
- `excavate`: Clear QR modules behind image (recommended: `true`)
198
- `x`, `y`: Optional positioning offsets from center
199

200
### Error Correction Levels
201

202
QR codes support four error correction levels determining how much damage the code can sustain while remaining readable:
203

204
- **'L' (Low)**: ~7% error correction - smaller QR codes, less damage tolerance
205
- **'M' (Medium)**: ~15% error correction - balanced size and reliability  
206
- **'Q' (Quartile)**: ~25% error correction - good for environments with potential damage
207
- **'H' (High)**: ~30% error correction - maximum damage tolerance, larger codes
208

209
**Usage Example:**
210
```typescript
211
// High error correction for better scanning reliability
212
<QRCodeSVG value="important-data" level="H" />
213
```
214

215
### Responsive Design
216

217
Both components accept standard React props allowing responsive layouts and custom styling.
218

219
**Usage Example:**
220
```typescript
221
<QRCodeSVG
222
  value="https://example.com"
223
  size={200}
224
  style={{
225
    height: "auto",
226
    maxWidth: "100%",
227
    width: "100%"
228
  }}
229
  className="responsive-qr"
230
/>
231
```
232

233
### Legacy Component (Deprecated)
234

235
```typescript { .api }
236
/**
237
 * Legacy QR code component with renderAs prop
238
 * @deprecated Use QRCodeSVG or QRCodeCanvas directly instead
239
 */
240
const QRCode: (props: QRCodeLegacyProps) => React.JSX.Element;
241
```
242

243
**Migration Path:**
244
```typescript
245
// Old (deprecated)
246
import QRCode from "qrcode.react";
247
<QRCode value="data" renderAs="svg" />
248

249
// New (recommended)
250
import { QRCodeSVG } from "qrcode.react";
251
<QRCodeSVG value="data" />
252
```
253

254
## Default Values
255

256
```typescript { .api }
257
/**
258
 * Default configuration values
259
 */
260
const DEFAULTS = {
261
  size: 128,
262
  level: 'L',
263
  bgColor: '#FFFFFF',
264
  fgColor: '#000000',
265
  includeMargin: false
266
} as const;
267
```
268

269
## Advanced Features
270

271
### Encoding Optimization
272

273
The library automatically detects and optimizes encoding modes:
274
- **Numeric**: Numbers only (most efficient)
275
- **Alphanumeric**: Letters, numbers, and limited symbols
276
- **Byte**: All characters including Unicode/multi-byte (general purpose)
277

278
### Browser Compatibility
279

280
- **Canvas rendering**: Supports Path2D optimization when available, falls back to module-by-module rendering
281
- **High-DPI displays**: Automatic pixel ratio scaling for crisp rendering
282
- **React versions**: Compatible with React 16.8+ (hooks), 17.x, and 18.x
283

284
### Performance Considerations
285

286
- **SVG**: Better for scaling, CSS manipulation, and vector graphics workflows
287
- **Canvas**: Better for pixel-perfect control and integration with canvas-based applications
288
- **Re-rendering**: Components automatically update when props change; image loading triggers re-renders when embedded images complete loading
289

290
## Exports
291

292
```typescript { .api }
293
/**
294
 * Complete export signature
295
 */
296
export { QRCode as default, QRCodeCanvas, QRCodeSVG };
297
```
298

299
**Import Patterns:**
300
```typescript
301
// Named imports (recommended)
302
import { QRCodeSVG, QRCodeCanvas } from "qrcode.react";
303

304
// Default import (legacy, deprecated)
305
import QRCode from "qrcode.react";
306

307
// Mixed import
308
import QRCode, { QRCodeSVG, QRCodeCanvas } from "qrcode.react";
309
```