Create Favicons

Favicons are the small icons that appear in browser tabs, bookmarks, and address bars. Providing favicons that look great across all devices, browsers, and operating systems is traditionally complex and time-consuming.

Why Favicons Matter

Brand Recognition:

Instant visual identification in crowded browser tabs
Professional appearance in bookmark lists
Consistent branding across all platforms

User Experience:

Easier navigation when multiple tabs are open
Quick identification in browser history
Better mobile home screen appearance

Platform Requirements:

Each browser and OS expects different sizes
Multiple formats needed (ICO, PNG, SVG)
Special icons for touch devices and pinned tabs

Favicons are separate from app icons declared in the Web App Manifest, though they serve similar purposes. The bundle automatically generates both from a single source image.

Quick Setup

With this bundle, generating all necessary favicons takes just seconds. You only need one source file:

Requirements:

Square icon (recommended)
SVG format (preferred) or PNG (512x512px minimum)
Transparent background (highly recommended)

Basic configuration:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true
        src: icons/favicon.svg

That's it! The bundle automatically generates all required favicon sizes and formats for:

Desktop browsers (16x16, 32x32, 48x48)
Touch devices (180x180 for Apple, 192x192 for Android)
Windows tiles (70x70 to 310x310)
Safari pinned tabs
And more...

Icon Source Options

The bundle supports three types of icon sources, giving you flexibility in how you provide your favicon:

1. Asset Mapper Asset (Recommended)

Reference icons managed by Symfony's Asset Mapper:

pwa:
    favicons:
        src: icons/favicon.svg  # Relative path within assets/

Advantages:

Version control friendly
Automatic cache busting
Works with build pipeline

2. Absolute File Path

Use an existing file from your project directory:

pwa:
    favicons:
        src: /app/files/favicon.svg  # Absolute path (starts with /)

Use cases:

Files outside the assets directory
Dynamic file locations
Legacy icon files

3. Symfony UX Icons

Use any icon from the Symfony UX Icons library:

pwa:
    favicons:
        src: bx:cool  # Format: iconset:icon-name

Advantages:

No file needed
Access to thousands of icons
Consistent icon library

Popular icon sets:

heroicons: - Heroicons
fa: - Font Awesome
bx: - BoxIcons
lucide: - Lucide Icons

Customization Options

SVG Attributes

You can customize any SVG attribute directly to control how your icon is rendered. The bundle allows you to modify fill colors, stroke properties, and any other SVG root attributes:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true
        src: icons/favicon.svg
        default:
            src: icons/favicon.svg
            svg_attr:
                fill: '#2196f3'      # Set fill color
                stroke: '#ffffff'    # Set stroke color
                stroke-width: '2'    # Set stroke width

Common SVG attributes you can modify:

fill: Main fill color of the icon
stroke: Outline/border color
stroke-width: Width of the stroke
opacity: Overall transparency
color: Used when SVG uses currentColor

Legacy svg_color option:

For backward compatibility, you can still use svg_color (which sets the color attribute):

pwa:
    favicons:
        enabled: true
        src: icons/favicon.svg
        svg_color: '#15fe68'  # Equivalent to svg_attr.color

The svg_color option is a shorthand for svg_attr.color. Use svg_attr directly for more control over SVG rendering.

Example use cases:

Set brand colors for monochrome SVG icons
Add strokes to improve visibility on backgrounds
Control opacity for watermark effects
Modify multiple attributes simultaneously

Icon Scaling and Safe Zone

Different platforms apply masks to icons (circular, rounded square, etc.). To ensure your icon looks good on all platforms, use the safe zone feature.

The problem: Some platforms (especially Android) may crop icons to specific shapes:

The solution: Scale down your icon to stay within the safe zone:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        image_scale: 80 # = 80% of the original size

Recommendations:

Use image_scale: 80 (80%) for icons with text or detailed graphics
Use image_scale: 100 for simple, centered logos
Test on different Android devices to verify appearance

The bundle automatically adds transparent padding to maintain the original canvas size while scaling the icon content.

Background Color and Rounded Corners

Create polished, platform-native looking icons by adding backgrounds and rounded corners:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        background_color: "#ffffff" # Hex color for the icon background
        border_radius: 10 # = 10% of the size. 50% is a circle.

Parameters:

background_color: Hex color code (e.g., #ffffff for white)
border_radius: Percentage of icon size (0-50)
- 0: Square corners
- 10: Slightly rounded (modern look)
- 25: Very rounded
- 50: Perfect circle

Visual examples:

border_radius: 0 → Square icon
border_radius: 10 → iOS-like rounded square
border_radius: 20 → Android Material style
border_radius: 50 → Circle

The border_radius option only works when background_color is set. Without a background, corners remain transparent.

Common combinations:

# iOS style
background_color: "#ffffff"
border_radius: 18

# Material Design
background_color: "#2196f3"
border_radius: 20

# Circular icon
background_color: "#000000"
border_radius: 50

Dark Mode Icons

Support dark themes with dedicated dark mode icons. Modern devices automatically switch between light and dark icons based on system theme:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true

        # Light mode icon (shown in light theme)
        default:
            src: assets/icon.svg
            background_color: '#ffffff'

        # Dark mode icon (shown in dark theme)
        dark:
            src: assets/icon_dark.svg
            background_color: '#000000'

How it works:

default: Light theme icon (used when system is in light mode)
dark: Dark theme icon (used when system is in dark mode)
Browser automatically switches based on user's system theme preference

Benefits:

Better user experience in dark mode
Maintains brand visibility in all themes
Professional, modern appearance
Automatic theme switching

Example scenarios:

Light background icon for light mode, dark background for dark mode
Inverted color scheme for better contrast
Different icon variants optimized for each theme

When dark is defined, default becomes the light mode variant. Without dark, default is used for both themes.

Platform-Specific Features

Safari Pinned Tab Icon

Safari's pinned tabs use a special monochrome icon. Configure it with a single color:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        safari_pinned_tab_color: "#f5ef06" # Safari only
        use_silhouette: true
        potrace: "/path/to/potrace" #Optional.
        # Only if potrace is installed in a non-conventional folder

Icon rendering:

By default, uses your icon as-is (with background/border-radius if configured)
Set use_silhouette: true for a clean silhouette effect

Silhouette mode:

Generates a single-color silhouette of your icon, perfect for Safari's minimalist pinned tab design.

Silhouette mode requires potrace to be installed on your system. Install it via your package manager (e.g., apt install potrace on Debian/Ubuntu).

Custom potrace path:

If potrace is installed in a non-standard location:

pwa:
    favicons:
        potrace: "/usr/local/bin/potrace"  # Custom path

Windows Tiles

Enable special tiles for Windows 8/10 Start Menu and taskbar:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        tile_color: "#f5ef06" # Windows 8 to 10 only

What gets generated:

Small tile (70x70)
Medium tile (150x150)
Wide tile (310x150)
Large tile (310x310)

Windows tiles ignore background_color and border_radius options. The tile color is applied as a flat background by Windows itself.

Use cases:

Windows desktop applications
Corporate environments using Windows
Apps pinned to Windows Start Menu

Legacy Browser Support

Low Resolution Icons

By default, the bundle generates icons optimized for modern devices. Enable additional icon sizes for legacy browsers and older devices:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        low_resolution: true

Additional sizes generated:

16x16 (very old browsers)
24x24 (Windows XP)
32x32 (standard favicon)
64x64 (high-DPI favicon)
96x96 (Google TV)
128x128 (Chrome Web Store)

When to enable:

Supporting iOS 6 or older
Chrome 20 or older browsers
Legacy Android devices (pre-4.3)
Enterprise environments with old hardware

Enabling low_resolution increases compilation time and generates more files. Only enable if you need legacy browser support.

Complete Configuration Example

Here's a comprehensive configuration showing both modern and legacy formats:

Modern Configuration (Recommended)

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true

        # Light mode theme
        default:
            src: assets/icon.svg
            background_color: '#ffffff'
            border_radius: 18
            image_scale: 80
            svg_attr:
                fill: '#2196f3'
                stroke: '#ffffff'

        # Dark mode theme
        dark:
            src: assets/icon_dark.svg
            background_color: '#000000'
            border_radius: 18
            image_scale: 80
            svg_attr:
                fill: '#ffffff'
                stroke: '#2196f3'

        # Platform-specific
        safari_pinned_tab_color: '#2196f3'
        use_silhouette: true
        tile_color: '#2196f3'

        # Additional options
        use_start_image: true
        low_resolution: false
        potrace: 'potrace'  # Path to potrace binary

Legacy Configuration (Still Supported)

For backward compatibility, the legacy format still works:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true

        # Source (will be converted to default.src)
        src: assets/icon.svg
        svg_color: '#2196f3'  # Converted to default.svg_attr.color
        background_color: '#ffffff'

        # Styling
        border_radius: 18
        image_scale: 80

        # Dark mode
        src_dark: assets/icon_dark.svg
        background_color_dark: '#000000'

        # Platform-specific
        safari_pinned_tab_color: '#2196f3'
        use_silhouette: true
        tile_color: '#2196f3'

Deprecated: The legacy format is deprecated and will be removed in version 2.x.

Deprecated options:

src → use default.src
svg_color → use default.svg_attr.color or svg_attr
background_color → use default.background_color
src_dark → use dark.src
background_color_dark → use dark.background_color
border_radius → use default.border_radius and/or dark.border_radius
image_scale → use default.image_scale and/or dark.image_scale

Migrate to the default and dark structure for full control and future compatibility.

Best Practices

Use SVG when possible: Scales perfectly to all sizes without quality loss
Transparent backgrounds: Works on any platform background color
Simple designs: Complex details may not be visible at small sizes (16x16)
Test safe zone: Ensure important elements stay within 80% of icon area
Dark mode support: Provide dark icons for better user experience
Skip legacy support: Unless you have specific requirements, modern icons are sufficient

Troubleshooting

Icons not appearing

Check:

Icon file exists at specified path
File format is supported (SVG, PNG)
Compilation ran successfully (pwa:compile)
HTML includes {{ pwa() }} function

Icon quality issues

Solutions:

Use SVG instead of PNG for better scaling
Ensure PNG is at least 512x512 pixels
Use image_scale to add safe zone padding
Test on actual devices

Silhouette not generating

Requirements:

potrace must be installed
Icon must have clear shapes (not gradients)
Use potrace parameter if in custom location

Dark icons not switching

Verify:

Device/browser supports dark mode
Both default and dark sections are configured
Icons have been recompiled
System theme is actually changing (test in browser DevTools)

What Gets Generated

When you compile favicons, the bundle creates:

Standard favicons:

favicon.ico (multi-size ICO file)
favicon.svg (for modern browsers)
apple-touch-icon.png (180x180 for iOS)
icon-192.png, icon-512.png (for Android)

HTML tags injected by {{ pwa() }}:

<link rel="icon" type="image/svg+xml" href="/favicon.svg">
<link rel="icon" type="image/png" sizes="192x192" href="/icon-192.png">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="mask-icon" href="/safari-pinned-tab.svg" color="#2196f3">
<meta name="msapplication-TileColor" content="#2196f3">

All files are automatically optimized and cached for production.

PreviousDeployment NextStartup Images

Last updated 1 month ago

Was this helpful?

Good evening

Why Favicons Matter

Quick Setup

Icon Source Options

1. Asset Mapper Asset (Recommended)

2. Absolute File Path

3. Symfony UX Icons

Customization Options

SVG Attributes

Icon Scaling and Safe Zone

Background Color and Rounded Corners

Dark Mode Icons

Platform-Specific Features

Safari Pinned Tab Icon

Windows Tiles

Legacy Browser Support

Low Resolution Icons

Complete Configuration Example

Modern Configuration (Recommended)

Legacy Configuration (Still Supported)

Best Practices

Troubleshooting

Icons not appearing

Icon quality issues

Silhouette not generating

Dark icons not switching

What Gets Generated