Customization: Visuals
Relevant source files
The following files were used as context for generating this wiki page:
The QR-Tool provides a comprehensive suite of visual customization options, allowing users to tailor the appearance of their QR codes. These features are managed primarily within the App.jsx component and are split between a simplified "Quick" mode and a detailed "Pro" mode. Customizations include size, color, error correction level, logo integration, and output format, all designed to create professional and scannable QR codes.
User preferences for visual settings are persisted in the browser's local storage using the useLocalStorage custom hook. This ensures a consistent user experience across sessions, though this feature is disabled in "private mode".
Sources: src/App.jsx:244-260, README.md:21-30
Architecture and Data Flow
Visual customization follows a reactive data flow within the React component structure. User interactions with UI controls (e.g., sliders, color pickers, buttons) update the component's state. These state changes trigger a re-computation of the properties (qrProps) passed to the rendering components, resulting in a live preview of the QR code.
The diagram below illustrates the flow from user input to the final rendered QR code preview.
UI Modes
The application offers two distinct user interface modes for customization, controlled by the uiMode state variable.
- 🚀 Quick Mode (
quick): Provides a simplified interface with essential controls, primarily focusing on image size via presets and a slider. - ⚡ Pro Mode (
pro): Exposes all available visual customization options for advanced users, including detailed controls for ECC, colors, logo, and format.
Sources: src/App.jsx:324, src/App.jsx:814-829
Core Visual Properties
These properties are primarily configured in the "Pro" mode and directly influence the QR code's appearance and scannability.
Size
The output size of the QR code can be set in pixels. The UI provides several methods for size selection:
- Presets: A list of pre-configured sizes suitable for common use cases (e.g., web, small labels, A4 printing).
- Slider/Input: A range slider and a number input for fine-grained control. The size is capped at 8192px, but the UI warns about performance for sizes over 2048px.
- Size Suggestion: The system calculates and suggests an optimal minimum size based on the QR code's data length, ECC level, and logo size to ensure scannability. This is determined by the
estimateDimensionhelper function.
| Preset ID | Label | Pixels | Recommended Format |
|---|---|---|---|
web | 🌐 Web/App | 512 | canvas |
3cm | 📱 Tem nhỏ 3cm | 354 | canvas |
5cm | 🎫 Tem 5cm | 591 | canvas |
8cm | 📄 Tờ rơi 8cm | 945 | canvas |
a4 | 📃 In A4 | 2048 | canvas |
poster | 🖼️ Poster lớn | 4096 | svg |
Sources: src/App.jsx:311-317, src/App.jsx:832-881, src/utils/qr-helpers.js:292-300
Colors and Contrast
Users can specify the foreground (dots) and background colors of the QR code using hex color codes.
- Color Pickers: Native
<input type="color">elements are provided for visual selection. - Hex Input: Text inputs allow for manual entry of 3-digit or 6-digit hex codes. The
normalizeHexfunction converts 3-digit codes to 6-digit format. - Validation: The
isValidHexfunction validates the input to prevent invalid color codes. - Contrast Checker: The application calculates the WCAG contrast ratio between the foreground and background colors using
getContrastRatioandrelLum. A warning is displayed if the ratio falls below 4.5:1, as low contrast can impair scannability.
Sources: src/App.jsx:400-413, src/App.jsx:1012-1057, src/utils/qr-helpers.js:6-27, tests/qr-helpers.test.js:8-29
Error Correction Level (ECC)
The ECC level determines the QR code's ability to sustain damage or obstruction (e.g., by a logo) and still be readable. The application supports four standard levels and an automatic mode.
- Levels:
L(Low, ~7%),M(Medium, ~15%),Q(Quartile, ~25%),H(High, ~30%). - AUTO Mode: This is the default and recommended setting. The
pickECCfunction dynamically selects the best ECC level based on logo size and color contrast.
The logic for pickECC is as follows:
This diagram shows how the automatic ECC level is chosen.
Sources: src/App.jsx:883-918, src/utils/qr-helpers.js:283-290, tests/qr-helpers.test.js:81-98
Margin (Quiet Zone)
A "Quiet Zone" is a blank margin around the QR code that helps scanners distinguish it from its surroundings.
- The
includeMarginstate (default:true) controls whether theqrcode.reactlibrary should render this margin. - If a user disables the margin and exports the QR code, the
ExportPanelcomponent will automatically add a safe padding (8% of the image size) to ensure scannability, after confirming with the user.
Sources: src/App.jsx:328, src/App.jsx:1060-1069, src/components/ExportPanel.jsx:33-43
Export Format & Transparency
The application can render the QR code in two formats for export:
- Canvas (
PNG/JPG): A raster image format. This is handled by the<QRCodeCanvas>component. - SVG: A vector format, ideal for high-resolution printing. This is handled by the
<QRCodeSVG>component.
A "Transparent Background" option is available, which sets the bgColor property to rgba(0,0,0,0). This is only effective for PNG exports, as JPG does not support transparency.
Sources: src/App.jsx:332, src/App.jsx:544-545, src/App.jsx:1086-1103, src/components/QrPreview.jsx:13-14
Logo Integration
A key feature is the ability to embed a logo in the center of the QR code.
Logo Upload
- File Input: Users can select a local image file (
<input type="file">). - Drag and Drop: The
QrPreviewcomponent hasonDropandonDragOverhandlers to accept dropped files. - Security: The
onPickLogofunction enforces a 4MB file size limit and whitelistsimage/png,image/jpeg,image/webp, andimage/svg+xmlfile types to prevent malicious uploads. - URL Management: Uploaded files are converted to blob URLs using
URL.createObjectURL(), andURL.revokeObjectURL()is used for cleanup to prevent memory leaks.
Sources: src/App.jsx:570-597, src/components/QrPreview.jsx:34-35, SECURITY_AUDIT_REPORT.md:78-85
Logo Sizing and Safety
The size of the logo relative to the QR code is critical for scannability.
- Sizing Modes: Presets (
S,M,L),Auto, andCustom(with a slider) are available to control the logo's scale. - Safety Indicator: The UI displays a safety level ("✓ An toàn", "⚠ Cẩn trọng", "⚠ Rủi ro cao") based on the logo's scale (
scale). A scale under 0.25 is considered safe, while over 0.3 is risky. - ECC Interaction: A large logo automatically triggers a higher ECC level (
H) in "AUTO" mode to compensate for the obscured data. A notice is shown to the user when this happens.
The following sequence diagram shows the interaction when a user uploads a logo.
Summary
The visual customization system in QR-Tool is a powerful and flexible feature set built around a reactive React architecture. It provides users with extensive control over the QR code's appearance while implementing safeguards like contrast checking, automatic ECC adjustment, and size suggestions to maintain scannability. The separation into "Quick" and "Pro" modes makes the tool accessible to both novice and advanced users. The use of local storage for persisting settings further enhances the user experience.