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.

Why Startup Images Matter

User Experience:

• Smooth transition from home screen to app

• Professional first impression

• Reduces perceived loading time

• Masks initial page rendering

Platform Expectations:

• iOS users expect splash screens like native apps

• Android handles this automatically with icon + background

• Builds trust and credibility

Branding:

• Reinforces brand identity

• Consistent across app launches

• Matches app theme and design

How It Works

The startup image generation differs by platform:

Android

Android automatically generates splash screens using:

• Your app icon (from manifest)

• Background color (from manifest background_color)

• No additional configuration needed

What Android shows:

1. Centered app icon

2. Solid background color

3. Short duration (until app loads)

iOS

iOS requires specific splash screen images for each device size and orientation:

Device variations:

• iPhone models (SE, 8, X, 11, 12, 13, 14, 15, etc.)

• iPad models (different sizes)

• Portrait and landscape orientations

The challenge: This traditionally requires dozens of different image files!

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

Automatic Generation

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

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        background_color: '#ffffff'  # Used for startup images

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)

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

Configuration Options

Basic Setup

The default configuration works for most cases:

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        background_color: '#ffffff'

Disable Startup Images

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

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        use_start_image: false  # Disable startup image generation

Why you might disable:

• Very simple web apps

• Performance concerns (fewer files)

• Custom splash screen implementation

Downsides:

• iOS shows white screen during launch

• Less professional appearance

• Missing expected UX on iOS

Dark Mode Startup Images

Dark mode icons automatically generate dark startup images:

config/packages/pwa.yaml

pwa:
    favicons:
        enabled: true

        # Light mode
        default:
            src: assets/icon.svg
            background_color: '#ffffff'

        # Dark mode
        dark:
            src: assets/icon_dark.svg
            background_color: '#000000'

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

Custom Background Colors

Choose backgrounds that match your app's theme:

pwa:
    favicons:
        enabled: true

        # Light theme with brand color
        default:
            src: assets/icon.svg
            background_color: '#2196f3'  # Material blue

        # Dark theme
        dark:
            src: assets/icon_dark.svg
            background_color: '#121212'  # Near black

Color examples:

• Light gray: #f5f5f5

• White: #ffffff

• Brand colors: #2196f3, #ff5722, etc.

• Dark gray: #121212

• Black: #000000

Best practices:

• Match your app's theme_color from manifest

• Ensure good contrast with icon

• Use colors that represent your brand

• Keep consistency between light and dark themes

Generated Files

The bundle creates startup images for all iOS devices:

iPhone Portrait:

• iPhone SE (640x1136)

• iPhone 8 (750x1334)

• iPhone 8 Plus (1242x2208)

• iPhone X/11 Pro (1125x2436)

• iPhone 11/XR (828x1792)

• iPhone 11 Pro Max (1242x2688)

• iPhone 12/13 mini (1080x2340)

• iPhone 12/13/14 (1170x2532)

• iPhone 14 Plus (1284x2778)

• iPhone 15 Pro Max (1290x2796)

iPhone Landscape:

• All above devices in landscape orientation

iPad Portrait & Landscape:

• iPad (various sizes)

• iPad Pro 11"

• iPad Pro 12.9"

Total: 30+ images covering all combinations

HTML Output

The bundle injects all necessary HTML tags:

<!-- Light mode startup images -->
<link rel="apple-touch-startup-image"
      media="(device-width: 430px) and (device-height: 932px) and (orientation: portrait)"
      href="/startup-430x932-portrait.png">

<!-- Dark mode startup images -->
<link rel="apple-touch-startup-image"
      media="(prefers-color-scheme: dark) and (device-width: 430px) and (device-height: 932px) and (orientation: portrait)"
      href="/startup-430x932-portrait-dark.png">

<!-- ...30+ more variations... -->

All this is automatic - you don't write any HTML!

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

Troubleshooting

Startup images not showing

iOS checklist:

1. PWA 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 (pwa:compile)

5. {{ pwa() }} function in HTML

Wrong colors appearing

Check:

• background_color matches your intention

• Dark mode variant configured if needed

• Cache cleared after changes

• Recompile assets

Images look pixelated

Ensure:

• Source icon is high resolution (512x512+)

• Using SVG (preferred) or large PNG

• image_scale not set too high

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)

When to disable:

• Extremely bandwidth-constrained users

• Very simple utility apps

• Custom splash implementation

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

Example Configurations

Minimal (recommended)

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        background_color: '#ffffff'
# use_start_image defaults to true

With Dark Mode

pwa:
    favicons:
        enabled: true
        default:
            src: assets/icon.svg
            background_color: '#ffffff'
        dark:
            src: assets/icon_dark.svg
            background_color: '#1a1a1a'

Brand Colors

pwa:
    favicons:
        enabled: true
        default:
            src: assets/logo.svg
            background_color: '#2196f3'  # Brand blue
            svg_attr:
                fill: '#ffffff'           # White logo

Disabled (not recommended)

pwa:
    favicons:
        enabled: true
        src: assets/icon.svg
        use_start_image: false  # Only if you have a good reason

Comparing to Native Apps

Native iOS app:

• Requires manual creation of 30+ splash images

• Must use Xcode and asset catalogs

• Updates require resubmission

PWA with this bundle:

• Automatic generation from one icon

• No manual image creation

• Updates deploy instantly

This is one of many ways PWAs simplify app development!