Home
Relevant source files
The following files were used as context for generating this wiki page:QR Generator Pro is a professional, client-side QR code generation application built with React and Vite. It allows users to create highly customized QR codes for various data types, including URLs, Wi-Fi credentials, vCards, and more. The application provides extensive customization options for size, color, error correction, and logo embedding. All processing occurs in the browser, requiring no backend server.
The tool features two UI modes: a "Quick" mode for beginners and a "Pro" mode for advanced customization. It includes real-time validation, a live preview with an integrated QR scanner to test scannability, and options to export the final QR code as a PNG, JPG, or SVG file. User preferences are saved to Local Storage for a consistent experience across sessions.
Sources: README.md, src/App.jsx:266-267, 1145-1150
Core Technologies
The project is built on a modern JavaScript stack, leveraging React for the UI and Vite for the build tooling.
| Technology/Library | Version | Purpose |
|---|---|---|
| React | 19.2.0 | Core UI framework for building components. |
| Vite (Rolldown) | 7.2.2 | Development server and production build tool. |
| Tailwind CSS | 3.4.18 | A utility-first CSS framework for styling. |
| qrcode.react | 4.2.0 | Library for rendering QR codes as Canvas or SVG elements. |
| @zxing/browser | 0.1.5 | Library used for scanning the generated QR code in the preview. |
| Vitest | 4.0.8 | Testing framework for unit tests. |
| ESLint | 9.39.1 | Code linting to maintain code quality. |
Sources: package.json:15-33, README.md:104-114
Application Architecture
The application is a single-page application (SPA) with a component-based architecture. The main entry point is src/main.jsx, which renders the primary App component into the DOM.
Sources: index.html:22, README.md:81
Component Structure
The App component serves as the central hub, managing the application's state and orchestrating interactions between its child components.
This diagram illustrates the main component hierarchy.
App.jsx: The root component that contains all UI elements and logic. It manages state for QR type, data, and all customization options.QrPreview.jsx: A component responsible for displaying the generated QR code. It dynamically renders either a<QRCodeCanvas>or<QRCodeSVG>based on the selected format. It also handles the drag-and-drop functionality for uploading a logo.ExportPanel.jsx: Contains the UI and logic for downloading the QR code in PNG, JPG, or SVG formats. It coordinates with helper functions to process the final image.qr-helpers.js: A utility file containing pure functions for data validation, color manipulation, ECC level selection, and image export processing.
Sources: src/App.jsx, src/components/QrPreview.jsx, src/components/ExportPanel.jsx, src/utils/qr-helpers.js
State Management
The application uses React hooks for state management. Most of the user's configuration is persisted in localStorage via a custom useLocalStorage hook.
useState: Used for ephemeral state, such as validation errors and the QR data object (qrData).useLocalStorage: A custom hook that wrapsuseStateto automatically save and retrieve state from the browser'slocalStorage. This is used for all user preferences likeqrType,size,fgColor,bgColor,eccMode, etc.useDebounced: A custom hook to delay the update of the QR code content (qrContent), preventing re-renders on every keystroke and improving performance.
Sources: src/App.jsx:257-277, 283-288
The following diagram shows the flow of the useLocalStorage hook.
Sources: src/App.jsx:257-277
QR Code Generation
The core logic for generating the QR code's string content resides in the generateQRContent function. This function takes the selected qrType and the qrData state object as input and returns a formatted string that the qrcode.react library can encode.
Sources: src/App.jsx:56-136, src/App.test.js
Supported QR Types
The application supports a variety of QR code types, each with a specific data format.
| Type | Icon | Description | Data Format Example |
|---|---|---|---|
| URL | 🔗 | A web link. | https://example.com |
| Text | 📝 | Plain text. | Hello World |
| Wi-Fi | 📶 | Wi-Fi network credentials. | WIFI:T:WPA;S:MyWiFi;P:pass123;; |
| vCard | 👤 | Electronic business card. | BEGIN:VCARD\r\nVERSION:3.0\r\n...END:VCARD |
| 📧 | Pre-filled email. | mailto:a@b.com?subject=Hi&body=Test | |
| SMS | 💬 | Pre-filled text message. | sms:+12345?body=Message |
| Phone | ☎️ | A phone number to call. | tel:+12345 |
| Location | 📍 | GPS coordinates. | geo:0,0?q=21.02,105.85(Hanoi) |
Sources: src/App.jsx:32-48, 56-136, src/App.test.js
Generation Flow
The generation process is triggered whenever the user's input changes.
Sources: src/App.jsx:56-136, 350-367
Customization and Features
The application offers extensive customization through the "Pro" UI mode. These options are managed by state variables, most of which are persisted in localStorage.
Error Correction (ECC)
The ECC level determines the QR code's ability to withstand damage or obstruction (e.g., from a logo). The pickECC function can automatically select an appropriate level.
- Logic: If
eccModeis "AUTO",pickECCselects a level based on the logo size and color contrast. A larger logo or poor contrast results in a higher ECC level ('H'). - Manual Override: Users can manually select 'L', 'M', 'Q', or 'H'.
This diagram shows the logic of the pickECC function.
Input Validation
To ensure the generation of valid QR codes and enhance security, the application validates user inputs in real-time.
| Function | File | Purpose |
|---|---|---|
isValidURL() | qr-helpers.js | Checks if a string is a structurally valid URL. |
isSafeHttpUrl() | qr-helpers.js | Ensures a URL uses only http: or https: protocols. |
isValidEmail() | qr-helpers.js | Validates email address format. |
isValidPhone() | qr-helpers.js | Checks for valid phone number characters. |
isValidLatLng() | qr-helpers.js | Validates latitude and longitude ranges. |
isValidHex() | qr-helpers.js | Validates hex color code format. |
Sources: src/utils/qr-helpers.js:27-113, src/App.jsx:304-329, tests/qr-helpers.test.js:41-81
QR Code Scanning
The application includes a feature to automatically scan the generated QR code in the preview panel to verify its scannability and content. This is handled by the testQRScan utility, which uses the @zxing/browser library. The scan result (success, warning, or error) is displayed to the user.
Sources: src/App.jsx:548-562, README.md:41
Export Functionality
The ExportPanel component allows users to download the generated QR code. The export logic handles different formats, adds padding if the quiet zone is disabled, and manages background transparency.
Export Process
handleDownload: The primary function inExportPanel.jsxthat orchestrates the export.buildDataURL: A helper inqr-helpers.jsthat takes a source canvas, adds padding and a background if needed, and returns adata:URL for PNG or JPG.buildSVGBlob: A helper inqr-helpers.jsthat clones the source SVG, adds a background rectangle and padding, and returns aBlob.- Quiet Zone Handling: If the
includeMarginoption is disabled, the export functions automatically add an 8% padding to ensure the QR code remains scannable, after confirming with the user.
Sources: src/components/ExportPanel.jsx:16-90, src/utils/qr-helpers.js:119-224
Security
The application is designed with security in mind, operating entirely on the client side. Key security measures are documented in the project's security audit.
- Input Validation: All user inputs are validated to prevent malformed data. URLs are specifically checked for safe protocols (
http/https). - XSS Protection: The use of React's JSX syntax provides automatic escaping of content, mitigating the risk of Cross-Site Scripting (XSS). No
dangerouslySetInnerHTMLis used. - File Upload Security: Logo uploads are restricted by file type (
PNG,JPG,WebP,SVG) and size (4MB limit) to prevent the upload of malicious files. - Content Security Policy (CSP): A strict CSP is defined in
public/_headersto restrict resource loading and script execution, further hardening the application against injection attacks. - Local Storage: Only non-sensitive UI preferences are stored. No personal data or secrets are persisted.
Sources: SECURITY_AUDIT_REPORT.md, SECURITY.md, src/App.jsx:304-329, 568-586, README.md:118-125