Substantive.Blazor.QRCode

Reusable Blazor components and helpers for generating and decoding QR codes across WebAssembly and Server workloads. The library ships with UI components (QrCodeImage, QrCodeVector) plus the QRCodeUtils encoder/decoder utilities and the configurable QRCodeConfig record for fine-grained control.

Features

• Image and SVG components: Drop-in Razor components that render PNG (Base64) or SVG QR codes with customizable colors, sizing, and optional logos.
• Encoder helpers: Static helpers for producing Base64 strings, SVG markup, or PNG byte arrays for storage/streaming scenarios.
• Decoder helpers: Stream, byte-array, and file-path helpers powered by ZXing for reading QR payloads from various image formats.
• Configurable pipeline: Central QRCodeConfig record validates colors, pixels-per-module, quiet zones, and error-correction levels so QR codes remain scannable.

Getting Started

1. Reference the project/package from your application.
2. Import the namespace in _Imports.razor or the relevant Razor file:

   @using Substantive.Blazor.QRCode
   

3. Add the component that fits your scenario:

   <QrCodeImage PayloadString="https://contoso.example" PixelsPerModule="16" DarkColor="#111" LightColor="#fafafa" />
   
   <QrCodeVector PayloadString="https://contoso.example" SvgLogo="@MySvgMarkup" />
   

4. (Optional) Use QRCodeUtils directly when you need raw PNG bytes, SVG markup, or Base64 data URIs outside of component rendering.

Components

QrCodeImage

• Renders a PNG-based QR code (data:image/png;base64,...).
• Parameters: PayloadString, PixelsPerModule, DarkColor, LightColor, DrawQuietZone.
• Adds the CSS class qr-code-container for custom styling; see the component-specific .razor.css for defaults.

QrCodeVector

• Produces an SVG data URI, ideal for responsive layouts or printing scenarios.
• Parameters mirror QrCodeImage with the addition of SvgLogo for inserting raw SVG content in the center of the code.
• Uses QRCodeUtils.GenerateQRCodeAsSVG under the hood.

Utilities

Encoding (QRCodeUtils.Encoder)

• GenerateQRCodeAsBase64(...): Returns a Base64 PNG string for inline <img> or CSS usage.
• GenerateQRCodeAsSVG(...): Produces raw SVG markup; supports sizing modes and optional SVG logo overlays.
• GenerateQRCodeAsPng(...): Returns PNG bytes suitable for persistence or streaming.
• GenerateQRCodeAsByteArray(...): Core method invoked by the helpers above; validates QRCodeConfig via data annotations before generation.

QRCodeConfig highlights:

Decoding (QRCodeUtils.Decoder)

• ReadQRCode(Stream) / ReadQRCode(byte[]): Decode payloads from in-memory content.
• ReadQRCode(Stream, mediaType): Enforces a specific MIME type (image/png, image/jpeg, etc.).
• ReadQRCode(string filePath): Automatically infers the image type from the file extension.

All decoding paths validate arguments, ensure readable streams, and throw precise exceptions when a QR code cannot be decoded.

Guidance & Best Practices

• Prefer SVG output for responsive UIs; PNG/Base64 is great for quick inline rendering.
• Keep DrawQuietZones enabled unless you control the background color tightly.
• Use higher ErrorCorrectionLevel when overlaying logos or expecting wear/tear.
• When decoding user-uploaded files, validate the stream (as done in QRCodeUtils) before attempting to decode.
• If you contribute new public APIs, accompany them with xUnit tests and update this README when needed.

Support

File issues or feature requests in the Foundation Frontends repository. For security-sensitive concerns, follow the organization’s responsible disclosure guidelines.