Screenshots

Deprecated: The command pwa:create:screenshot is deprecated and has been removed. Create screenshots manually or use screen capture tools.

Overview

Screenshots enhance your PWA's installation experience by showing users what your app looks like before they install it. They appear in app stores, installation prompts, and PWA directories.

Screenshot Configuration

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

Basic Configuration

/config/packages/pwa.yaml

pwa:
    manifest:
        screenshots:
            - src: "screenshots/home.png"
              sizes: [1280, 720]
              form_factor: "wide"
            - src: "screenshots/mobile-home.png"
              sizes: [750, 1334]
              form_factor: "narrow"

Creating Screenshots

Manual Screenshots

1. Browser DevTools (Recommended)

# Chrome/Edge DevTools
1. Open your PWA (F12)
2. Click device toolbar (Ctrl+Shift+M)
3. Select device/resolution
4. Click "Capture screenshot" (in DevTools menu)
5. Or use Cmd+Shift+P → "Capture screenshot"

2. OS Screen Capture

Windows: Win + Shift + S
macOS: Cmd + Shift + 4
Linux: PrtScn or Shift + PrtScn

3. Browser Extensions

Awesome Screenshot
FireShot
Full Page Screen Capture

Automated Screenshots

Puppeteer (Node.js)

const puppeteer = require('puppeteer');

async function captureScreenshots() {
    const browser = await puppeteer.launch();
    const page = await browser.newPage();

    // Desktop screenshot
    await page.setViewport({ width: 1280, height: 720 });
    await page.goto('https://your-app.com');
    await page.screenshot({
        path: 'screenshots/desktop-home.png',
        fullPage: false
    });

    // Mobile screenshot
    await page.setViewport({ width: 375, height: 667 });
    await page.goto('https://your-app.com');
    await page.screenshot({
        path: 'screenshots/mobile-home.png',
        fullPage: false
    });

    await browser.close();
}

captureScreenshots();

Playwright

const { chromium } = require('playwright');

async function captureScreenshots() {
    const browser = await chromium.launch();
    const page = await browser.newPage();

    // Desktop
    await page.setViewportSize({ width: 1280, height: 720 });
    await page.goto('https://your-app.com');
    await page.screenshot({ path: 'screenshots/desktop.png' });

    // Mobile
    await page.setViewportSize({ width: 375, height: 667 });
    await page.goto('https://your-app.com');
    await page.screenshot({ path: 'screenshots/mobile.png' });

    await browser.close();
}

Screenshot Requirements

Recommended Sizes

Mobile (Narrow)

screenshots:
    - src: "screenshots/mobile-1.png"
      sizes: [750, 1334]        # iPhone 8
      form_factor: "narrow"
    - src: "screenshots/mobile-2.png"
      sizes: [1080, 1920]       # Android
      form_factor: "narrow"

Desktop/Tablet (Wide)

screenshots:
    - src: "screenshots/desktop-1.png"
      sizes: [1280, 720]        # HD
      form_factor: "wide"
    - src: "screenshots/desktop-2.png"
      sizes: [1920, 1080]       # Full HD
      form_factor: "wide"

Platform-Specific

screenshots:
    # Android
    - src: "screenshots/android-1.png"
      sizes: [1080, 1920]
      platform: "android"
      form_factor: "narrow"

    # iOS
    - src: "screenshots/ios-1.png"
      sizes: [1284, 2778]       # iPhone 13 Pro Max
      platform: "ios"
      form_factor: "narrow"

    # Windows
    - src: "screenshots/windows-1.png"
      sizes: [1920, 1080]
      platform: "windows"
      form_factor: "wide"

Screenshot Guidelines

Content Best Practices

Show Key Features: Highlight main functionality
Use Real Data: Show actual app content, not placeholders
Keep UI Clean: Remove debug info, test data
Consistent Branding: Match your app's design
Clear Text: Ensure text is readable

Number of Screenshots

Minimum: 1-2 screenshots
Recommended: 3-5 screenshots
Maximum: 8 screenshots (platform limit)

Rationale:

Too few: Doesn't showcase app properly
Too many: Overwhelming, slow loading
Sweet spot: 3-5 showing main features

Screenshot Sequence

Order screenshots logically:

screenshots:
    - "screenshots/01-splash.png"      # Welcome/landing
    - "screenshots/02-main.png"        # Main interface
    - "screenshots/03-feature1.png"    # Key feature #1
    - "screenshots/04-feature2.png"    # Key feature #2
    - "screenshots/05-settings.png"    # Configuration/settings

Design Guidelines

Visual Quality

Resolution: High-DPI (2x or 3x)
Format: PNG (preferred) or JPEG
Compression: Optimize without quality loss
Aspect Ratio: Match target device

Composition

Framing: Show full interface or focused feature
Spacing: Leave some breathing room
Highlights: Use subtle overlays to emphasize features
Annotations: Add brief captions if helpful

Consistency

Same viewport: All screenshots same dimensions per form factor
Same theme: Light/dark mode consistent across all
Same state: Logged in, data loaded, no errors
Same branding: Colors, fonts match throughout

File Organization

Recommended Structure

assets/
└── screenshots/
    ├── mobile/
    │   ├── 01-home.png
    │   ├── 02-feature1.png
    │   ├── 03-feature2.png
    │   └── 04-settings.png
    ├── desktop/
    │   ├── 01-home.png
    │   ├── 02-dashboard.png
    │   └── 03-reports.png
    └── tablet/
        ├── 01-home.png
        └── 02-main.png

Configuration Example

pwa:
    manifest:
        screenshots:
            # Mobile screenshots
            - src: "screenshots/mobile/01-home.png"
              sizes: [750, 1334]
              form_factor: "narrow"
              platform: "android"
              label: "Home screen with recent activity"

            - src: "screenshots/mobile/02-feature1.png"
              sizes: [750, 1334]
              form_factor: "narrow"
              platform: "android"
              label: "Task management view"

            - src: "screenshots/mobile/03-feature2.png"
              sizes: [750, 1334]
              form_factor: "narrow"
              platform: "android"
              label: "Analytics dashboard"

            # Desktop screenshots
            - src: "screenshots/desktop/01-home.png"
              sizes: [1280, 720]
              form_factor: "wide"
              label: "Main dashboard interface"

            - src: "screenshots/desktop/02-dashboard.png"
              sizes: [1280, 720]
              form_factor: "wide"
              label: "Advanced analytics view"

Optimizing Screenshots

Image Optimization

1. Use Image Compression Tools

# Using ImageOptim (macOS)
imageoptim screenshots/*.png

# Using TinyPNG (CLI)
npx tinypng-cli screenshots/*.png

# Using Sharp (Node.js)
npx sharp-cli -i screenshot.png -o optimized.png

2. Convert to WebP (if supported)

# Using cwebp
for file in screenshots/*.png; do
    cwebp -q 80 "$file" -o "${file%.png}.webp"
done

3. Serve Appropriate Format

screenshots:
    - src: "screenshots/home.webp"
      format: "image/webp"
      sizes: [1280, 720]
    - src: "screenshots/home.png"
      format: "image/png"
      sizes: [1280, 720]

File Size Guidelines

Target: < 500 KB per screenshot
Maximum: < 1 MB per screenshot
Total: All screenshots < 5 MB combined

Platform-Specific Requirements

Android / Google Play

Requirements:

Minimum: 2 screenshots
Format: PNG or JPEG
Dimensions: 320-3840 pixels
Aspect ratio: 16:9 or 9:16

screenshots:
    - src: "screenshots/android-1.png"
      sizes: [1080, 1920]
      platform: "play"
      form_factor: "narrow"

iOS / App Store

Requirements:

Screenshots for each device size
Format: PNG or JPEG
No transparency
Actual device screenshots preferred

screenshots:
    - src: "screenshots/iphone-14-pro.png"
      sizes: [1179, 2556]
      platform: "ios"
      form_factor: "narrow"

Windows / Microsoft Store

Requirements:

Minimum: 1 screenshot
Format: PNG, JPEG, or GIF
Dimensions: 1366 x 768 or larger

screenshots:
    - src: "screenshots/windows.png"
      sizes: [1920, 1080]
      platform: "windows"
      form_factor: "wide"

Testing Screenshots

1. Validate in Manifest

// Check screenshots in manifest
fetch('/manifest.json')
    .then(r => r.json())
    .then(manifest => {
        console.log('Screenshots:', manifest.screenshots);

        manifest.screenshots?.forEach((screenshot, index) => {
            console.log(`Screenshot ${index + 1}:`, {
                src: screenshot.src,
                sizes: screenshot.sizes,
                form_factor: screenshot.form_factor,
                platform: screenshot.platform
            });
        });
    });

2. Check in DevTools

1. Open DevTools (F12)
2. Go to Application → Manifest
3. Check "Screenshots" section
4. Verify images load correctly
5. Check dimensions and labels

3. Test Install Flow

Desktop: Install PWA, check screenshots in install dialog
Mobile: Add to home screen, check screenshots
App Stores: Submit to test store, verify display

4. Preview Tools

Chrome: chrome://apps (after installation)
PWA Builder: https://www.pwabuilder.com/
Web.dev: Use PWA analyzer tools

Common Issues

Screenshots Not Showing

Problem: Screenshots don't appear in install prompt

Solutions:

Verify screenshot paths are correct
Check images are accessible (CORS)
Ensure proper sizes specified
Clear browser cache
Check manifest is valid JSON

Screenshots Too Large

Problem: Installation slow due to large screenshots

Solutions:

Compress images (TinyPNG, ImageOptim)
Reduce dimensions if too large
Use WebP format
Lazy load screenshots if possible

Wrong Aspect Ratio

Problem: Screenshots appear stretched or cropped

Solutions:

Match device aspect ratios
Use form_factor correctly (narrow/wide)
Test on actual devices
Create platform-specific screenshots

Poor Quality

Problem: Screenshots look blurry or pixelated

Solutions:

Use high-resolution source
Capture at 2x or 3x scale
Use lossless compression
Don't upscale small images

Advanced Features

Adding Labels

Provide context with descriptive labels:

screenshots:
    - src: "screenshots/dashboard.png"
      sizes: [1280, 720]
      label: "Real-time analytics dashboard with customizable widgets"
      form_factor: "wide"

    - src: "screenshots/reports.png"
      sizes: [1280, 720]
      label: "Detailed reports with export functionality"
      form_factor: "wide"

Multiple Platforms

Serve different screenshots per platform:

screenshots:
    # Android-specific
    - src: "screenshots/android-home.png"
      platform: "android"
      form_factor: "narrow"

    # iOS-specific
    - src: "screenshots/ios-home.png"
      platform: "ios"
      form_factor: "narrow"

    # Desktop-specific
    - src: "screenshots/desktop-home.png"
      platform: "windows"
      form_factor: "wide"

Migration from Deprecated Command

Old Approach (Deprecated)

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

New Approach

Capture screenshots using browser DevTools or automation
Optimize images using compression tools
Place in assets directory: assets/screenshots/
Configure in pwa.yaml:

pwa:
    manifest:
        screenshots:
            - src: "screenshots/home.png"
              sizes: [1280, 720]

Compile assets:

php bin/console asset-map:compile

Best Practices Checklist

Before publishing:

Screenshots (Manifest) - Complete configuration
Icons - Icon management
AssetMapper - Asset management

Resources

PWA Builder: https://www.pwabuilder.com/
TinyPNG: https://tinypng.com/
ImageOptim: https://imageoptim.com/
MDN Screenshots: https://developer.mozilla.org/en-US/docs/Web/Manifest/screenshots
Web.dev: https://web.dev/add-manifest/#screenshots

PreviousIcons NextNon-Standard Parameters

Last updated 1 month ago

Was this helpful?

Good night

Overview

Screenshot Configuration

Basic Configuration

Creating Screenshots

Manual Screenshots

Automated Screenshots

Screenshot Requirements

Recommended Sizes

Platform-Specific

Screenshot Guidelines

Content Best Practices

Number of Screenshots

Screenshot Sequence

Design Guidelines

Visual Quality

Composition

Consistency

File Organization

Recommended Structure

Configuration Example

Optimizing Screenshots

Image Optimization

File Size Guidelines

Platform-Specific Requirements

Android / Google Play

iOS / App Store

Windows / Microsoft Store

Testing Screenshots

1. Validate in Manifest

2. Check in DevTools

3. Test Install Flow

4. Preview Tools

Common Issues

Screenshots Not Showing

Screenshots Too Large

Wrong Aspect Ratio

Poor Quality

Advanced Features

Adding Labels

Multiple Platforms

Migration from Deprecated Command

Old Approach (Deprecated)

New Approach

Best Practices Checklist

Related Documentation

Resources