Icons

Deprecated: The command pwa:create:icons is deprecated and has been removed. Use modern icon generation tools and configure icons directly in your manifest.

Overview

PWA icons are configured in your manifest file and served through AssetMapper or absolute paths. The bundle no longer provides icon generation commands - instead, use dedicated tools or services.

Icon Configuration

Icons are defined in your manifest configuration. See the complete Icons documentation for detailed configuration options.

Basic Configuration

/config/packages/pwa.yaml

pwa:
    manifest:
        icons:
            - src: "icons/icon-192.png"
              sizes: [192]
            - src: "icons/icon-512.png"
              sizes: [512]
            - src: "icons/maskable-icon-512.png"
              sizes: [512]
              purpose: "maskable"

Recommended Icon Generation Tools

Online Tools

1. PWA Asset Generator

https://www.pwabuilder.com/imageGenerator
Generates all required icon sizes
Creates maskable icons automatically
Free and easy to use

2. RealFaviconGenerator

https://realfavicongenerator.net/
Comprehensive favicon and icon generation
Tests icons on multiple platforms
Generates HTML meta tags

3. Maskable.app

https://maskable.app/
Specialized for maskable icon creation
Visual safe zone editor
Preview on different devices

4. Favicon.io

https://favicon.io/
Simple and fast
Generates from text, image, or emoji
Free to use

Command-Line Tools

1. PWA Asset Generator (CLI)

npx pwa-asset-generator source-icon.png public/icons \
    --background "#2196F3" \
    --icon-only \
    --maskable

2. Sharp (Node.js)

const sharp = require('sharp');

// Generate icon sizes
const sizes = [48, 72, 96, 144, 192, 256, 512];

sizes.forEach(size => {
    sharp('source-icon.png')
        .resize(size, size)
        .toFile(`public/icons/icon-${size}.png`);
});

3. ImageMagick

# Generate multiple sizes
for size in 48 72 96 144 192 256 512; do
    convert source-icon.png -resize ${size}x${size} icons/icon-${size}.png
done

Icon Requirements

Required Sizes

At minimum, provide these sizes:

icons:
    - src: "icons/icon-192.png"
      sizes: [192]              # Android Chrome
    - src: "icons/icon-512.png"
      sizes: [512]              # Android Chrome, install prompt

Recommended Sizes

For comprehensive support:

icons:
    - src: "icons/icon-48.png"
      sizes: [48]               # Windows taskbar
    - src: "icons/icon-72.png"
      sizes: [72]               # iOS, iPad
    - src: "icons/icon-96.png"
      sizes: [96]               # Android launcher
    - src: "icons/icon-144.png"
      sizes: [144]              # Windows desktop
    - src: "icons/icon-192.png"
      sizes: [192]              # Android Chrome
    - src: "icons/icon-256.png"
      sizes: [256]              # Windows Store
    - src: "icons/icon-512.png"
      sizes: [512]              # High-res displays

Maskable Icons

Always include maskable icons for better Android integration:

icons:
    - src: "icons/maskable-icon-192.png"
      sizes: [192]
      purpose: "maskable"
    - src: "icons/maskable-icon-512.png"
      sizes: [512]
      purpose: "maskable"

Icon Design Guidelines

Standard Icons

Format: PNG (preferred) or JPEG
Background: Solid color or transparent
Content: Icon centered, using ~80% of canvas
Design: Simple, recognizable at small sizes

Maskable Icons

Safe zone: Keep important content in center 80%
Background: Must fill entire canvas (no transparency)
Bleeding: Design can extend to edges
Testing: Use https://maskable.app/ to verify

Design Tips

Simplicity: Icons should be recognizable at 48x48
Contrast: Ensure good contrast with background
Consistency: Match your brand colors
Scalability: Design should work at all sizes
Testing: Test on actual devices

File Organization

Recommended Structure

assets/
└── icons/
    ├── icon-48.png
    ├── icon-72.png
    ├── icon-96.png
    ├── icon-144.png
    ├── icon-192.png
    ├── icon-256.png
    ├── icon-512.png
    ├── maskable-icon-192.png
    ├── maskable-icon-512.png
    └── icon.svg (optional, for 'any' size)

Configuration Example

pwa:
    manifest:
        icons:
            # Standard icons
            - src: "icons/icon-48.png"
              sizes: [48]
            - src: "icons/icon-72.png"
              sizes: [72]
            - src: "icons/icon-96.png"
              sizes: [96]
            - src: "icons/icon-144.png"
              sizes: [144]
            - src: "icons/icon-192.png"
              sizes: [192]
            - src: "icons/icon-256.png"
              sizes: [256]
            - src: "icons/icon-512.png"
              sizes: [512]

            # Maskable icons
            - src: "icons/maskable-icon-192.png"
              sizes: [192]
              purpose: "maskable"
            - src: "icons/maskable-icon-512.png"
              sizes: [512]
              purpose: "maskable"

            # Vector icon (optional)
            - src: "icons/icon.svg"
              sizes: 0  # 'any' size

Using Symfony UX Icons

If you have symfony/ux-icons installed, you can use icon libraries:

pwa:
    manifest:
        icons:
            - src: "bx:badge-check"
              sizes: [192]
            - src: "heroicons:check-circle"
              sizes: [512]

See Symfony UX Icons for available icons.

Migration from Deprecated Command

Old Approach (Deprecated)

# This no longer works
php bin/console pwa:create:icons

New Approach

Generate icons using online tools or CLI tools
Place icons in your assets/icons/ directory
Configure in pwa.yaml:

pwa:
    manifest:
        icons:
            - src: "icons/icon-192.png"
              sizes: [192]
            - src: "icons/icon-512.png"
              sizes: [512]

Compile assets:

php bin/console asset-map:compile

Testing Icons

1. Lighthouse PWA Audit

# Run Lighthouse
npx lighthouse https://your-app.com --view

Check the PWA section for icon requirements.

2. Chrome DevTools

1. Open DevTools (F12)
2. Go to Application → Manifest
3. Check "Icons" section
4. Verify all sizes are present

3. Install on Device

Android: Install PWA, check app drawer icon
iOS: Add to home screen, check icon appearance
Desktop: Install, check taskbar/dock icon

4. Maskable Icon Tester

Visit https://maskable.app/editor and upload your maskable icons to verify the safe zone.

Common Issues

Icons Not Appearing

Problem: Icons don't show after installation

Solutions:

Clear browser cache
Check icon paths are correct
Verify icons are served (check network tab)
Ensure AssetMapper compiled assets
Check file permissions

Wrong Icon Size

Problem: Icon appears pixelated or blurry

Solutions:

Provide higher resolution icons (512px minimum)
Include appropriate size for each platform
Use vector SVG for scalability

Maskable Icons Not Adapting

Problem: Maskable icons get cropped incorrectly

Solutions:

Ensure safe zone is respected (center 80%)
Test with https://maskable.app/
Provide solid background (no transparency)
Check purpose is set to "maskable"

Platform-Specific Icons

Android

Requirements:

Minimum: 192x192 and 512x512
Format: PNG with transparency or solid background
Maskable: Highly recommended

icons:
    - src: "icons/android-192.png"
      sizes: [192]
    - src: "icons/android-512.png"
      sizes: [512]
    - src: "icons/android-maskable-512.png"
      sizes: [512]
      purpose: "maskable"

iOS

Requirements:

Recommended: 180x180 for Apple Touch Icon
Format: PNG, no transparency
Additional meta tag may be needed

<!-- In your HTML head -->
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">

Windows

Requirements:

Recommended: 144x144, 256x256
Format: PNG or ICO
May require separate configuration

icons:
    - src: "icons/windows-144.png"
      sizes: [144]
    - src: "icons/windows-256.png"
      sizes: [256]

Advanced Icon Features

For advanced icon configuration including rounded corners, image scaling, and background colors, see the complete Icons documentation.

Icons (Manifest) - Complete icon configuration
Screenshots - App screenshot management
AssetMapper - Asset management
Symfony UX Icons - Icon library integration

Resources

PWA Builder: https://www.pwabuilder.com/
Maskable.app: https://maskable.app/
Favicon Generator: https://realfavicongenerator.net/
MDN Icons: https://developer.mozilla.org/en-US/docs/Web/Manifest/icons
Web.dev PWA Icons: https://web.dev/add-manifest/#icons

PreviousWeb Share NextScreenshots

Last updated 6 days ago

Was this helpful?

Overview

Icon Configuration

Basic Configuration

Recommended Icon Generation Tools

Online Tools

Command-Line Tools

Icon Requirements

Required Sizes

Recommended Sizes

Maskable Icons

Icon Design Guidelines

Standard Icons

Maskable Icons

Design Tips

File Organization

Recommended Structure

Configuration Example

Using Symfony UX Icons

Migration from Deprecated Command

Old Approach (Deprecated)

New Approach

Testing Icons

1. Lighthouse PWA Audit

2. Chrome DevTools

3. Install on Device

4. Maskable Icon Tester

Common Issues

Icons Not Appearing

Wrong Icon Size

Maskable Icons Not Adapting

Platform-Specific Icons

Android

iOS

Windows

Advanced Icon Features

Related Documentation

Resources