Merge a Logo into Your Laravel QR Code

Embed a PNG, WebP, SVG, or EPS logo into the center of a QR code using the merge() method. Includes best practices for error correction and logo sizing.

The merge() method lets you embed a logo or image directly into the center of a QR code. This is a common branding technique — the QR code remains fully scannable as long as the logo does not cover too much of the data area.

How It Works

Call merge() before generate(), passing the image path and the proportion of the QR it should occupy.

merge(string $filepath, float $percentage = 0.2)

Parameter	Type	Description
$filepath	string	Path to the image file to embed. Relative paths are resolved from your project root; absolute paths are used as-is.
$percentage	float	Fraction of the QR width the image should occupy (e.g. 0.3 = 30 %). Default: 0.2

Supported Formats

Image merge works with all output formats: PNG, WebP, SVG, and EPS.

EPS merging requires the GD PHP extension. PNG and WebP merging requires either Imagick or GD. SVG merging has no additional PHP extension requirements.

Basic Examples

PNG with logo

use Linkxtr\QrCode\Facades\QrCode;

$qr = QrCode::format('png')
    ->size(400)
    ->merge(public_path('logo.png'), 0.3)
    ->generate('https://example.com');

SVG with logo

use Linkxtr\QrCode\Facades\QrCode;

$qr = QrCode::format('svg')
    ->size(400)
    ->merge(public_path('logo.svg'), 0.25)
    ->generate('https://example.com');

WebP with logo

use Linkxtr\QrCode\Facades\QrCode;

$qr = QrCode::format('webp')
    ->size(400)
    ->merge(public_path('logo.webp'), 0.2)
    ->generate('https://example.com');

Use High Error Correction

When you embed a logo you are physically covering part of the QR code’s data modules. QR codes compensate for this through built-in error correction. Set the level to H (30 % recovery) whenever you merge an image.

use Linkxtr\QrCode\Facades\QrCode;

QrCode::format('png')
    ->size(400)
    ->errorCorrection('H')
    ->merge(public_path('logo.png'), 0.3)
    ->generate('https://example.com');

Error correction level H allows up to 30 % of the QR data to be obscured or damaged while keeping the code scannable. Always use it when embedding a logo.

Save to a File

Pass a second argument to generate() to write the result directly to disk.

use Linkxtr\QrCode\Facades\QrCode;

QrCode::format('png')
    ->size(500)
    ->errorCorrection('H')
    ->merge(public_path('logo.png'), 0.25)
    ->generate('https://example.com', storage_path('app/qrcodes/branded.png'));

Merging an In-Memory Image String

If you already have the image content as a string (e.g. fetched from remote storage), use mergeString() instead of merge().

use Linkxtr\QrCode\Facades\QrCode;
use Illuminate\Support\Facades\Storage;

$logoContent = Storage::get('logos/company.png');

QrCode::format('png')
    ->size(400)
    ->errorCorrection('H')
    ->mergeString($logoContent, 0.3)
    ->generate('https://example.com');

Best Practices

1. Keep the logo under 30 % of the QR area

   A $percentage value above 0.3 risks making the code unreadable on lower-quality scanners. Stay at 0.3 or below for maximum compatibility.

2. Always use error correction level H

   Call ->errorCorrection('H') every time you use merge(). This maximises the redundancy available to compensate for the obscured modules.

3. Use a simple, high-contrast logo

   Complex logos with thin lines or subtle colour gradients are harder to distinguish at small sizes. A simple monochrome or flat-colour logo works best.

4. Test on a real device

   Always scan the final QR code with at least two different scanner apps before distributing it. Automated rendering tests do not catch all edge cases.

Complete Branded Example

use Linkxtr\QrCode\Facades\QrCode;

$qr = QrCode::format('png')
    ->size(500)
    ->margin(2)
    ->errorCorrection('H')
    ->style('dot')
    ->eye('circle')
    ->color(30, 64, 175)           // dark blue foreground
    ->backgroundColor(255, 255, 255)
    ->merge(public_path('logo.png'), 0.25)
    ->generate('https://example.com');

// Render in a Blade view
// {!! $qr !!}

Styling

Control module shape, eye style, size, margin, and format.

Colors

Apply RGB, CMYK, grayscale, gradients, and per-eye color overrides.