# 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.

## 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

### 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.

## Automatic Generation

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

{% code title="config/packages/pwa.yaml" lineNumbers="true" %}

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

{% endcode %}

**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)

{% hint style="success" %}
The bundle generates 30+ startup images automatically to cover all iOS devices and orientations!
{% endhint %}

## Configuration Options

### Disable Startup Images

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

{% code title="config/packages/pwa.yaml" lineNumbers="true" %}

```yaml
pwa:
    favicons:
        enabled: true
        default:
            src: assets/icon.svg
        use_start_image: false
```

{% endcode %}

**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:

{% code title="config/packages/pwa.yaml" lineNumbers="true" %}

```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'
```

{% endcode %}

**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

## 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

## HTML Output

The bundle injects all necessary HTML tags:

```html
<!-- 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 when you include `{{ pwa() }}` in your template.

## 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 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>`

### 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)

{% hint style="info" %}
For most PWAs, the user experience benefit of startup images far outweighs the minimal performance impact.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pwa.spomky-labs.com/favicons/startup-images.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.