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

> Learn how to add an icon to an EFQRCode easily with Swift examples. This guide shows you how to configure icon image, size, and mode for custom QR codes.

- Repository: [EFPrefix/efqrcode](https://github.com/efprefix/efqrcode)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/efprefix/efqrcode/blob/main/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:

```swift
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`](https://github.com/efprefix/efqrcode/blob/main/Source/Styles/EFQRCodeStyleBasic.swift):

```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:

```swift
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:

```swift
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`](https://github.com/efprefix/efqrcode/blob/main/Source/Styles/EFQRCodeStyle.swift) (lines 38‑71) and the iOS demo app example in [`Examples/iOS/Generator/BasicGeneratorController.swift`](https://github.com/efprefix/efqrcode/blob/main/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`](https://github.com/efprefix/efqrcode/blob/main/Source/Styles/EFQRCodeStyleResampleImage.swift):

```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:

```swift
// 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.