0
# QR Code React
1

2
QR Code React is a React component library for generating customizable QR codes. It provides two rendering options (SVG and Canvas) with comprehensive customization including colors, sizes, error correction levels, margins, and embedded image support.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { QRCodeSVG, QRCodeCanvas } from "qrcode.react";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { QRCodeSVG, QRCodeCanvas } = require("qrcode.react");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import React from "react";
27
import { QRCodeSVG, QRCodeCanvas } from "qrcode.react";
28

29
// Basic SVG QR code
30
function BasicSVGExample() {
31
  return <QRCodeSVG value="https://reactjs.org/" />;
32
}
33

34
// Basic Canvas QR code
35
function BasicCanvasExample() {
36
  return <QRCodeCanvas value="https://reactjs.org/" />;
37
}
38

39
// Customized QR code with image
40
function CustomizedExample() {
41
  return (
42
    <QRCodeSVG
43
      value="https://example.com"
44
      size={256}
45
      bgColor="#ffffff"
46
      fgColor="#000000"
47
      level="M"
48
      marginSize={4}
49
      imageSettings={{
50
        src: "https://example.com/logo.png",
51
        height: 32,
52
        width: 32,
53
        excavate: true
54
      }}
55
    />
56
  );
57
}
58
```
59

60
## Architecture
61

62
QR Code React is built around several key components:
63

64
- **Dual Rendering**: SVG and Canvas components for different use cases and performance needs
65
- **Props Interface**: Unified prop system with component-specific extensions for DOM attributes
66
- **QR Generation**: Integrated QR Code Generator library for efficient code generation
67
- **Image Embedding**: Support for logo/image overlay with excavation and positioning
68
- **Type Safety**: Full TypeScript support with comprehensive type definitions
69
- **React Integration**: Forward ref support and standard React patterns
70

71
## Capabilities
72

73
### SVG QR Code Rendering
74

75
SVG-based QR code component providing scalable vector rendering with full customization options.
76

77
```typescript { .api }
78
const QRCodeSVG: React.ForwardRefExoticComponent<
79
  QRPropsSVG & React.RefAttributes<SVGSVGElement>
80
>;
81
```
82

83
### Canvas QR Code Rendering
84

85
Canvas-based QR code component optimized for high-density displays with pixel-perfect rendering.
86

87
```typescript { .api }
88
const QRCodeCanvas: React.ForwardRefExoticComponent<
89
  QRPropsCanvas & React.RefAttributes<HTMLCanvasElement>
90
>;
91
```
92

93
### QR Code Properties
94

95
Base props interface shared by both QR code components.
96

97
```typescript { .api }
98
interface QRProps {
99
  /** The value to encode into the QR Code. Array of strings for optimized multi-segment encoding */
100
  value: string | string[];
101
  /** Size in pixels to render the QR Code (default: 128) */
102
  size?: number;
103
  /** Error correction level (default: 'L') */
104
  level?: ErrorCorrectionLevel;
105
  /** Background color for the QR Code (default: '#FFFFFF') */
106
  bgColor?: string;
107
  /** Foreground color for the QR Code (default: '#000000') */
108
  fgColor?: string;
109
  /** @deprecated Use marginSize instead. Whether to include 4-module margin (default: false) */
110
  includeMargin?: boolean;
111
  /** Number of modules for margin, overrides includeMargin (default: 0) */
112
  marginSize?: number;
113
  /** Title for accessibility */
114
  title?: string;
115
  /** Minimum QR version 1-40, higher = more complex (default: 1) */
116
  minVersion?: number;
117
  /** Allow higher error correction if possible without increasing version (default: true) */
118
  boostLevel?: boolean;
119
  /** Settings for embedded image/logo */
120
  imageSettings?: ImageSettings;
121
}
122
```
123

124
### Error Correction Levels
125

126
QR code error correction level options.
127

128
```typescript { .api }
129
type ErrorCorrectionLevel = 'L' | 'M' | 'Q' | 'H';
130
```
131

132
- `'L'` - Low (~7% error correction)
133
- `'M'` - Medium (~15% error correction)  
134
- `'Q'` - Quartile (~25% error correction)
135
- `'H'` - High (~30% error correction)
136

137
### Image Settings
138

139
Configuration for embedding images or logos in QR codes.
140

141
```typescript { .api }
142
interface ImageSettings {
143
  /** URI of the embedded image */
144
  src: string;
145
  /** Height of the image in pixels */
146
  height: number;
147
  /** Width of the image in pixels */
148
  width: number;
149
  /** Whether to excavate (clear) modules behind the image */
150
  excavate: boolean;
151
  /** Horizontal offset in pixels, centers if not specified */
152
  x?: number;
153
  /** Vertical offset in pixels, centers if not specified */
154
  y?: number;
155
  /** Image opacity 0-1 (default: 1) */
156
  opacity?: number;
157
  /** Cross-origin attribute for image loading */
158
  crossOrigin?: CrossOrigin;
159
}
160
```
161

162
### Cross-Origin Options
163

164
Cross-origin attribute values for image loading in QR codes.
165

166
```typescript { .api }
167
type CrossOrigin = 'anonymous' | 'use-credentials' | '' | undefined;
168
```
169

170
### Component-Specific Props
171

172
Props types for individual QR code components that extend base QRProps with DOM attributes.
173

174
```typescript { .api }
175
type QRPropsCanvas = QRProps & React.CanvasHTMLAttributes<HTMLCanvasElement>;
176

177
type QRPropsSVG = QRProps & React.SVGAttributes<SVGSVGElement>;
178
```
179

180
## Usage Examples
181

182
### Multi-Segment Encoding
183

184
Optimize QR code size by using multiple segments:
185

186
```typescript
187
import { QRCodeSVG } from "qrcode.react";
188

189
function MultiSegmentExample() {
190
  return (
191
    <QRCodeSVG
192
      value={["WIFI:", "S:MyNetwork;", "T:WPA;", "P:password123;", ";"]}
193
      size={200}
194
      level="M"
195
    />
196
  );
197
}
198
```
199

200
### Custom Styling with CSS
201

202
Apply custom styles using className and style props:
203

204
```typescript
205
import { QRCodeSVG } from "qrcode.react";
206

207
function StyledExample() {
208
  return (
209
    <QRCodeSVG
210
      value="https://example.com"
211
      size={150}
212
      className="qr-code"
213
      style={{
214
        border: "2px solid #333",
215
        borderRadius: "8px",
216
        padding: "16px"
217
      }}
218
    />
219
  );
220
}
221
```
222

223
### High Error Correction with Logo
224

225
Use higher error correction when embedding logos:
226

227
```typescript
228
import { QRCodeCanvas } from "qrcode.react";
229

230
function LogoExample() {
231
  return (
232
    <QRCodeCanvas
233
      value="https://company.com"
234
      size={300}
235
      level="H" // High error correction for logo overlay
236
      bgColor="#f8f9fa"
237
      fgColor="#212529"
238
      marginSize={4}
239
      imageSettings={{
240
        src: "/company-logo.png",
241
        height: 60,
242
        width: 60,
243
        excavate: true,
244
        opacity: 0.9,
245
        crossOrigin: "anonymous"
246
      }}
247
    />
248
  );
249
}
250
```
251

252
### Canvas with Forward Ref
253

254
Access canvas element for data extraction:
255

256
```typescript
257
import React, { useRef, useCallback } from "react";
258
import { QRCodeCanvas } from "qrcode.react";
259

260
function CanvasRefExample() {
261
  const canvasRef = useRef<HTMLCanvasElement>(null);
262

263
  const downloadQRCode = useCallback(() => {
264
    if (canvasRef.current) {
265
      const url = canvasRef.current.toDataURL();
266
      const link = document.createElement('a');
267
      link.download = 'qrcode.png';
268
      link.href = url;
269
      link.click();
270
    }
271
  }, []);
272

273
  return (
274
    <div>
275
      <QRCodeCanvas
276
        ref={canvasRef}
277
        value="https://example.com"
278
        size={256}
279
      />
280
      <button onClick={downloadQRCode}>Download QR Code</button>
281
    </div>
282
  );
283
}
284
```
285

286
### Responsive QR Code
287

288
Create responsive QR codes that scale with container:
289

290
```typescript
291
import React, { useState, useEffect } from "react";
292
import { QRCodeSVG } from "qrcode.react";
293

294
function ResponsiveExample() {
295
  const [size, setSize] = useState(200);
296

297
  useEffect(() => {
298
    const handleResize = () => {
299
      const container = document.getElementById('qr-container');
300
      if (container) {
301
        const containerWidth = container.offsetWidth;
302
        setSize(Math.min(containerWidth - 32, 400)); // Max 400px with 16px padding
303
      }
304
    };
305

306
    window.addEventListener('resize', handleResize);
307
    handleResize(); // Initial size
308

309
    return () => window.removeEventListener('resize', handleResize);
310
  }, []);
311

312
  return (
313
    <div id="qr-container" style={{ width: '100%', padding: '16px' }}>
314
      <QRCodeSVG
315
        value="https://example.com"
316
        size={size}
317
        style={{ maxWidth: '100%', height: 'auto' }}
318
      />
319
    </div>
320
  );
321
}
322
```