search

Startup Images

Startup images (also called splash screens) are displayed when launching your PWA from the home screen. They provide visual feedback during app initialization, creating a smoother, more app-like experience.

hashtag
How It Works

The startup image generation differs by platform:

hashtag
Android

Android automatically generates splash screens using:

  • Your app icon (from manifest)

  • Background color (from manifest background_color)

  • No additional configuration needed

hashtag
iOS

iOS requires specific splash screen images for each device size and orientation. This traditionally requires dozens of different image files.

Bundle solution: Automatically generates all required sizes from your icon and background color.

hashtag
Automatic Generation

By default, when you configure favicons, startup images are automatically created:

config/packages/pwa.yaml
pwa:
    favicons:
        enabled: true
        default:
            src: assets/icon.svg
            background_color: '#ffffff'

What gets generated:

  • iOS portrait images (all device sizes)

  • iOS landscape images (all device sizes)

  • Correct media queries in HTML

  • Dark mode variants (if configured)

circle-check

The bundle generates 30+ startup images automatically to cover all iOS devices and orientations!

hashtag
Configuration Options

hashtag
Disable Startup Images

If you don't want startup images (not recommended for iOS):

Downsides:

  • iOS shows white screen during launch

  • Less professional appearance

  • Missing expected UX on iOS

hashtag
Dark Mode Startup Images

Dark mode icons automatically generate dark startup images:

Result:

  • Light startup images for light mode (from default)

  • Dark startup images for dark mode (from dark)

  • Automatic switching based on system theme

  • All device sizes generated for both themes

hashtag
Generated Files

The bundle creates startup images for all iOS devices:

iPhone Portrait & Landscape:

  • iPhone SE (640x1136)

  • iPhone 8 (750x1334)

  • iPhone 8 Plus (1242x2208)

  • iPhone X/11 Pro (1125x2436)

  • iPhone 11/XR (828x1792)

  • iPhone 12/13 mini (1080x2340)

  • iPhone 12/13/14 (1170x2532)

  • iPhone 14 Plus (1284x2778)

  • iPhone 15 Pro Max (1290x2796)

iPad Portrait & Landscape:

  • iPad (various sizes)

  • iPad Pro 11"

  • iPad Pro 12.9"

Total: 30+ images covering all combinations

hashtag
HTML Output

The bundle injects all necessary HTML tags:

All this is automatic when you include {{ pwa() }} in your template.

hashtag
Best Practices

  1. Always enable startup images: Essential for iOS PWAs

  2. Match theme colors: Use same background_color as manifest

  3. Provide dark mode: Better user experience

  4. Keep icon centered: Works best for startup screens

  5. Test on real devices: Verify appearance on iPhone and iPad

hashtag
Troubleshooting

hashtag
Startup images not showing

iOS checklist:

  1. PWA is installed to home screen (not running in Safari)

  2. use_start_image is not set to false

  3. background_color is configured

  4. Assets compiled (php bin/console pwa:compile)

  5. {{ pwa() }} function in HTML <head>

hashtag
Wrong colors appearing

Check:

  • background_color matches your intention

  • Dark mode variant configured if needed

  • Cache cleared after changes

  • Recompile assets

hashtag
Images look pixelated

Ensure:

  • Source icon is high resolution (512x512+)

  • Using SVG (preferred) or large PNG

  • image_scale not set too high

hashtag
Performance Considerations

File size impact:

  • Each startup image: 10-50 KB

  • Total for all images: ~500 KB - 1 MB

  • Cached by browser after first launch

Optimization:

  • Bundle automatically optimizes images

  • PNG compression applied

  • Only downloaded as needed (per device)

circle-info

For most PWAs, the user experience benefit of startup images far outweighs the minimal performance impact.

PreviousCreate FaviconsNextApplication Information

Last updated

Was this helpful?