How to Add an Icon to an EFQRCode: Complete Guide with Swift Examples

You can add an icon to an EFQRCode by creating an EFStyleParamIcon configuration object with your image, scaling mode, and size percentage, then passing it to a style parameter struct like EFStyleBasicParams before generating the code.

The EFQRCode library provides a flexible styling system that allows you to embed custom icons (or watermarks) at the center of QR codes. This functionality is implemented through the EFStyleParamIcon class defined in Source/Styles/EFQRCodeStyle.swift, which integrates with various style generators including Basic, Resample Image, Bubble, and 2.5D styles.

Understanding the EFStyleParamIcon Configuration

The EFStyleParamIcon struct acts as a container for all icon-related properties. When you instantiate this object, you define how your image will be rendered, scaled, and positioned within the final QR code output.

Key Parameters

• image: An EFStyleParamImage enum value containing your CGImage (use .static(image:) for standard images).
• mode: An EFImageMode value determining scaling behavior—options include .scaleAspectFill, .scaleAspectFit, and .scaleToFill.
• alpha: A CGFloat between 0 and 1 controlling icon opacity.
• borderColor: An optional CGColor for drawing a rectangular border around the icon.
• percentage: A CGFloat specifying the icon size as a fraction of the QR code dimension (internally clamped to a maximum of 0.33 to maintain scannability).

Step-by-Step Implementation

1. Prepare Your Icon Image

First, convert your source image to a CGImage. On iOS, this typically involves loading a UIImage and accessing its cgImage property. The library also provides helper extensions in Source/Extension/UIImage+EFQRCode.swift and Source/Extension/CGImage+EFQRCode.swift to facilitate these conversions.

2. Configure the Icon Parameters

Create the EFStyleParamIcon instance with your desired visual settings. The following example configures a 22% size icon with 90% opacity and a white border:

let icon = EFStyleParamIcon(
    image: .static(image: myCGImage),
    mode: .scaleAspectFill,
    alpha: 0.9,
    borderColor: UIColor.white.cgColor,
    percentage: 0.22
)

3. Integrate with Style Parameters

Insert the icon into a style-specific parameter struct. For the Basic style, use EFStyleBasicParams as defined in Source/Styles/EFQRCodeStyleBasic.swift:

let styleParams = EFStyleBasicParams(
    icon: icon,
    backdrop: EFStyleParamBackdrop(),
    position: EFStyleBasicParamsPosition(),
    data: EFStyleBasicParamsData(),
    align: EFStyleBasicParamsAlign(),
    timing: EFStyleBasicParamsTiming()
)

4. Generate the QR Code

Instantiate the generator with your content and style, then render the output:

let generator = try EFQRCode.Generator(
    "https://example.com",
    style: .basic(params: styleParams)
)

let qrImage = try generator.toImage(width: 300)

Complete Code Examples

Basic Style with Icon

This comprehensive example demonstrates loading an icon from the asset catalog, configuring it with a border and specific scaling, and generating a 300×300 QR code:

import EFQRCode
import UIKit

// Load icon image
let iconImage = UIImage(named: "logo")!.cgImage!

// Configure icon parameters
let icon = EFStyleParamIcon(
    image: .static(image: iconImage),
    mode: .scaleAspectFill,
    alpha: 0.9,
    borderColor: UIColor.white.cgColor,
    percentage: 0.22
)

// Create basic style with icon
let style = EFQRCodeStyle.basic(
    params: EFStyleBasicParams(
        icon: icon,
        backdrop: EFStyleParamBackdrop(),
        position: EFStyleBasicParamsPosition(),
        data: EFStyleBasicParamsData(),
        align: EFStyleBasicParamsAlign(),
        timing: EFStyleBasicParamsTiming()
    )
)

// Generate QR code
let generator = try EFQRCode.Generator("https://github.com/efprefix/efqrcode", style: style)
let image = try generator.toImage(width: 300)

Source: Implementation based on EFStyleParamIcon definition in Source/Styles/EFQRCodeStyle.swift (lines 38‑71) and the iOS demo app example in Examples/iOS/Generator/BasicGeneratorController.swift (lines 75‑84).

Resample Image Style with Background and Icon

For more complex designs combining a background image with a centered icon, use the Resample Image style implemented in Source/Styles/EFQRCodeStyleResampleImage.swift:

// Prepare background and icon images
let backgroundCGImage = UIImage(named: "background")!.cgImage!
let iconCGImage = UIImage(named: "icon")!.cgImage!

// Configure background
let background = EFStyleParamBackdropImage(
    image: backgroundCGImage,
    alpha: 0.8,
    mode: .scaleAspectFill
)

// Configure icon (reusing previous pattern)
let icon = EFStyleParamIcon(
    image: .static(image: iconCGImage),
    mode: .scaleAspectFill,
    alpha: 1.0,
    borderColor: UIColor.white.cgColor,
    percentage: 0.25
)

// Build resample image style
let style = EFQRCodeStyle.resampleImage(
    params: EFStyleResampleImageParams(
        icon: icon,
        backdrop: EFStyleParamBackdrop(
            cornerRadius: 10,
            color: UIColor.clear.cgColor,
            image: background,
            quietzone: nil
        ),
        image: nil,
        align: EFStyleResampleImageParamsAlign(),
        timing: EFStyleResampleImageParamsTiming(),
        position: EFStyleResampleImageParamsPosition()
    )
)

let generator = try EFQRCode.Generator("https://example.com", style: style)
let qrImage = try generator.toImage(width: 400)

Icon Size Constraints

The library enforces a maximum icon size to ensure the QR code remains scannable. In EFStyleParamIcon.write(qrcode:), the implementation explicitly clamps the percentage value:

// Internal implementation detail (EFStyleParamIcon.write)
let size = min(self.percentage, 0.33) * qrCodeDimension

This means even if you specify percentage: 0.50, the icon will be capped at 33% of the QR code's width/height. This safety mechanism prevents the icon from obscuring too many data modules, which could render the code unreadable by standard scanners.

Summary

• EFStyleParamIcon is the configuration object that defines how your icon appears in the center of a QR code, including image source, scaling mode, opacity, border color, and relative size.
• The icon workflow requires creating the EFStyleParamIcon, inserting it into a style-specific parameter struct (such as EFStyleBasicParams or EFStyleResampleImageParams), and passing that to EFQRCode.Generator.
• Icon size is automatically constrained to 33% of the QR code dimension to maintain scannability, implemented via min(self.percentage, 0.33) in the write(qrcode:) method.
• The pattern works across all EFQRCode styles including Basic, Resample Image, Bubble, 2.5D, Line, Image Fill, and Function styles.

Frequently Asked Questions

What image formats are supported for EFQRCode icons?

EFQRCode accepts any image that can be converted to a CGImage (Core Graphics image). On iOS, this typically means UIImage PNG or JPEG assets that you convert using .cgImage. The library provides helper extensions in Source/Extension/UIImage+EFQRCode.swift and Source/Extension/CGImage+EFQRCode.swift to streamline this conversion. For macOS, use NSImage and convert it to CGImage before wrapping it in EFStyleParamImage.static(image:).

Why is my icon size limited to 33% of the QR code?

The 33% size limit is a scannability safeguard hardcoded in EFStyleParamIcon.write(qrcode:) via min(self.percentage, 0.33). This prevents the icon from covering too many data modules, which would make the QR code unreadable by standard camera apps and scanners. If you specify a percentage larger than 0.33 (e.g., 0.50), the library automatically clamps it to 0.33 (33%) to ensure the generated code remains functional.

Can I use a transparent background icon?

Yes, EFQRCode supports icons with transparency. When you create the EFStyleParamIcon, set the alpha parameter to control overall opacity (0.0 to 1.0), and ensure your source CGImage has an alpha channel. The write(qrcode:) method handles masking and blending so that transparent areas of your icon reveal the underlying QR code modules. For best results, use PNG images with transparency rather than JPEGs.

How do I add a border around my icon?

You can add a rectangular border around your icon by specifying the borderColor parameter when initializing EFStyleParamIcon. Pass a CGColor (e.g., UIColor.white.cgColor or NSColor.white.cgColor) to create a solid border. The border is drawn as a rectangle behind the icon image during the write(qrcode:) rendering process. If you do not want a border, simply pass nil for the borderColor parameter.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}