Custom Styling Guide

Create beautiful, branded QR codes that match your design system.

Basic Customization

Colors

Use the color and background parameters to customize colors:

curl "https://www.qrcodeapi.io/api/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  --data-urlencode "data=https://example.com" \
  --data "color=22c55e" \
  --data "background=f0fdf4" \
  -o green-qr.png

Color Format: 6-character hex without the # symbol.

Size

Control the output size (50-2000 pixels):

# Small (icon)
curl "...&size=100" -o small.png

# Medium (default)
curl "...&size=300" -o medium.png

# Large (print)
curl "...&size=1000" -o large.png

# Maximum
curl "...&size=2000" -o max.png

Output Format

Choose between PNG and SVG:

# PNG (raster, default)
curl "...&format=png" -o qr.png

# SVG (vector, scalable)
curl "...&format=svg" -o qr.svg

When to Use SVG

Use SVG when you need:

• Infinite scalability (print at any size)
• Smaller file sizes
• CSS styling capabilities
• Crisp display on retina screens

Error Correction

Error correction determines how much of the QR code can be damaged while remaining scannable:

Level	Recovery	Best For
L	~7%	Maximum data density
M	~15%	Standard use (default)
Q	~25%	Moderate damage expected
H	~30%	Logo overlay, harsh conditions

# High error correction for logo overlay
curl "...&errorCorrection=H" -o high-ec.png

Margin (Quiet Zone)

The margin is the white border around the QR code (measured in modules):

# No margin
curl "...&margin=0" -o no-margin.png

# Small margin
curl "...&margin=2" -o small-margin.png

# Default margin
curl "...&margin=4" -o default-margin.png

# Large margin
curl "...&margin=10" -o large-margin.png

Scanning Issues

A margin of at least 2-4 modules is recommended for reliable scanning. Some scanners may fail with margin=0.

Logo Overlay

Add your brand logo to the center of QR codes (Pro plan):

curl "https://www.qrcodeapi.io/api/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  --data-urlencode "data=https://example.com" \
  --data-urlencode "logo=https://example.com/logo.png" \
  --data "logoSize=25" \
  --data "errorCorrection=H" \
  -o branded-qr.png

Logo Parameters

Parameter	Default	Description
logo	-	URL to logo image (PNG, JPG, SVG)
logoSize	20	Logo size as % of QR code (10-40)

Logo Best Practices

1. Use high error correction: Always set errorCorrection=H when using logos
2. Keep logos simple: High-contrast, simple shapes work best
3. Size appropriately: 20-25% is usually optimal
4. Use transparent backgrounds: PNG with transparency works well
5. Test scanning: Always verify the QR code scans reliably

# Optimal logo settings
curl "..." \
  --data "logo=https://example.com/logo.png" \
  --data "logoSize=20" \
  --data "errorCorrection=H" \
  --data "size=500" \
  -o perfect-branded-qr.png

Design Examples

Corporate Blue

curl "https://www.qrcodeapi.io/api/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  --data-urlencode "data=https://company.com" \
  --data "color=1e40af" \
  --data "background=eff6ff" \
  --data "size=400" \
  -o corporate.png

Dark Mode

curl "..." \
  --data "color=ffffff" \
  --data "background=0a0a0a" \
  -o dark-mode.png

Gradient Background (SVG)

Generate as SVG, then add gradient with CSS:

<style>
  .qr-gradient {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    padding: 20px;
    border-radius: 12px;
  }
  .qr-gradient img {
    display: block;
  }
</style>

<div class="qr-gradient">
  <img src="/api/generate?data=hello&format=svg&background=00000000" alt="QR">
</div>

Rounded Corners

Use SVG with CSS border-radius:

<style>
  .rounded-qr {
    border-radius: 24px;
    overflow: hidden;
  }
</style>

<div class="rounded-qr">
  <img src="/api/generate?data=hello&size=300" alt="QR">
</div>

Color Contrast Guidelines

For reliable scanning, maintain good contrast between color and background:

Combination	Contrast Ratio	Scannability
Black on White	21:1	✅ Excellent
Dark Blue on Light Blue	8:1	✅ Good
Green on Light Green	4:1	⚠️ Acceptable
Light Gray on White	1.5:1	❌ Poor

Minimum recommended contrast ratio: 4:1

Testing Contrast

Use this formula to calculate contrast ratio:

(L1 + 0.05) / (L2 + 0.05)

Where L1 and L2 are the relative luminance values.

Or use online tools like WebAIM Contrast Checker.

Print Considerations

Resolution

Use Case	Recommended Size
Web/Screen	200-400px
Business Cards	300-500px
Posters	800-1500px
Billboards	2000px (max)

File Format

• SVG: Best for print (infinite scalability)
• PNG: Good for most uses
• High DPI: Use larger sizes, scale down in print software

Minimum Print Size

QR codes should be at least 2cm × 2cm (0.8" × 0.8") for reliable scanning at arm's length. For scanning from further away:

Distance	Minimum Size
< 1 ft	1" × 1"
1-3 ft	2" × 2"
3-6 ft	4" × 4"
6-10 ft	6" × 6"

JavaScript Styling Example

async function generateStyledQR(data, style = {}) {
  const {
    size = 300,
    color = '000000',
    background = 'ffffff',
    errorCorrection = 'M',
    margin = 4,
    format = 'png',
    logo = null,
    logoSize = 20
  } = style;

  const params = new URLSearchParams({
    data,
    size: size.toString(),
    color,
    background,
    errorCorrection: logo ? 'H' : errorCorrection, // Auto-upgrade for logos
    margin: margin.toString(),
    format
  });

  if (logo) {
    params.append('logo', logo);
    params.append('logoSize', logoSize.toString());
  }

  const response = await fetch(
    `https://www.qrcodeapi.io/api/generate?${params}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );

  return response.blob();
}

// Usage
const qr = await generateStyledQR('https://example.com', {
  size: 500,
  color: '4f46e5',
  background: 'f5f3ff',
  logo: 'https://example.com/logo.png',
  logoSize: 25
});

Related

• Generate API - Full parameter reference
• Logo Overlay Guide - Detailed logo guide
• Examples - More styling examples