Screenshots
Progressive Web App screenshots enable richer installation UI. As shown below, by default only the application name and short name are visible.

However, by including screenshots in the web app manifest, the installation experience can be significantly improved. These screenshots give users a visual preview of the app, enhancing their understanding and increasing the likelihood of installation.
Screenshots should showcase the most important functionalities of your application and be of high quality to attract users.
In the example below, a selection of screenshots are visible and the user can navigate to show them all. On mobile devices, the interface is different, but shows the same information.

Overview
Screenshots are an essential part of your PWA's installation experience. They help users understand what your app does before installing it.
Key benefits:
Enhanced installation UI with visual previews
Increased installation conversion rates
Showcase app's key features and functionality
Platform-specific presentation (Android, Windows, etc.)
Support for different device form factors (mobile, desktop)
Automatic format conversion and optimization
Browser/Platform Support:
Chrome (Desktop)
✅ Full
Installation dialog
Chrome (Android)
✅ Full
WebAPK install screen
Edge (Desktop)
✅ Full
Installation dialog
Windows Store
✅ Full
Store listing
Samsung Internet
✅ Full
Install prompt
Safari (iOS)
⚠️ Limited
Not displayed in install flow
Firefox
⚠️ Limited
Partial support
Basic Configuration
Simple Configuration
Complete Configuration
Configuration Parameters
src Parameter
The src parameter specifies the path to your screenshot image.
Asset Mapper Integration:
Absolute URLs:
Best Practices:
Use high-quality images (Full HD or higher recommended)
Keep file sizes reasonable (< 500 KB per screenshot)
Use consistent dimensions per form factor
Prefer WebP format for smaller file sizes
width and height Parameters
Specify screenshot dimensions in pixels. If omitted, dimensions are detected automatically.
Why specify dimensions?
Improves manifest parsing performance
Ensures correct aspect ratio detection
Helps browsers choose appropriate screenshot for device
Required for some platform app stores
format Parameter
The format parameter specifies the image format. The bundle can automatically convert images to the specified format.
Supported formats:
"png"- Lossless, good for UI screenshots"jpg"or"jpeg"- Lossy, smaller file sizes"webp"- Modern format, best compression
Format Recommendations:
UI Screenshots
WebP or PNG
Sharp text, no artifacts
Photo-heavy screens
WebP or JPEG
Better compression for photos
Maximum compatibility
PNG
Universally supported
Smallest file size
WebP
Best compression ratio
label Parameter
The label parameter provides a brief description or caption for the screenshot. This helps users understand what the feature or screen is about.
Label Best Practices:
Keep labels concise (5-10 words)
Describe the feature or functionality shown
Use consistent tone across all labels
Avoid redundant information (don't repeat app name)
Translation Support:
The label parameter supports Symfony translations:
platform Parameter
The platform parameter specifies which operating system or distribution platform the screenshot is intended for. This helps display appropriate screenshots for users on different devices.
Device Platform Identifiers:
"android"- Android devices"chromeos"- ChromeOS devices"ipados"- iPad devices"ios"- iPhone devices"kaios"- KaiOS devices"macos"- macOS devices"windows"- Windows devices"xbox"- Xbox devices
Distribution Platform Identifiers:
"chrome_web_store"- Chrome Web Store"itunes"- Apple App Store"microsoft-inbox"- Microsoft built-in apps"microsoft-store"- Microsoft Store"play"- Google Play Store
form_factor Parameter
The form_factor parameter defines the intended device form factor for your screenshots. This helps browsers display appropriate screenshots based on the user's device.
Possible values:
"narrow"- Best suited for narrow screen devices (phones, portrait tablets)"wide"- Intended for wider screen devices (desktops, landscape tablets)
Form Factor Guidelines:
"narrow"
1080x1920 (portrait)
9:16
Phones, portrait tablets
"narrow"
750x1334 (iPhone 8)
9:16
Mobile devices
"wide"
1920x1080 (landscape)
16:9
Desktops, laptops
"wide"
1280x720 (HD)
16:9
Tablets (landscape)
reference Parameter
The reference parameter allows you to specify a URL reference for the screenshot. This is for documentation purposes only and is not used by the bundle in the generated manifest.
Use cases:
Link to design specifications
Reference Figma or design tool URLs
Internal documentation links
Version tracking
Screenshot Creation
Recommended Dimensions
Mobile (Narrow):
iPhone 14 Pro
1179×2556
9:19.5
iPhone 14
1170×2532
9:19.5
iPhone 8
750×1334
9:16
Android (1080p)
1080×1920
9:16
Android (720p)
720×1280
9:16
Desktop/Tablet (Wide):
Full HD
1920×1080
16:9
HD
1280×720
16:9
iPad Pro
2048×1536
4:3
Surface Pro
2736×1824
3:2
Screenshot Creation Methods
1. Browser DevTools (Recommended)
2. Automated Tools (Puppeteer)
3. Playwright
4. OS Screenshot Tools
Windows: Win + Shift + S
macOS: Cmd + Shift + 4 (select area) or Cmd + Shift + 5 (advanced)
Linux: PrtScn or Shift + PrtScn
Complete Use Cases
Use Case 1: E-Commerce App
Use Case 2: Productivity App with Platform-Specific Screens
Use Case 3: Multi-Language App
Screenshot Optimization
File Size Optimization
1. Use WebP Format
WebP typically provides 25-35% better compression than PNG or JPEG:
2. Optimize Before Upload
Using command-line tools:
3. Compress Existing Images
Using Node.js with Sharp:
File Size Guidelines
Mobile (narrow)
< 200 KB
< 500 KB
Desktop (wide)
< 300 KB
< 800 KB
Total (all screenshots)
< 2 MB
< 5 MB
Image Quality Best Practices
Use high-resolution source
Capture at actual device resolution (not scaled up)
Use 2x or 3x scale for retina displays
Remove sensitive information
No real user data
No API keys or tokens visible
Use placeholder/demo content
Consistent visual design
Same theme (light/dark) across all screenshots
Consistent UI state (logged in, data loaded)
Professional appearance (no dev tools, no errors)
Optimize content
Show actual features, not loading states
Include realistic but anonymized data
Highlight key functionality
Platform-Specific Requirements
Android / Google Play
Requirements:
Minimum: 2 screenshots
Maximum: 8 screenshots
Format: PNG or JPEG
Dimensions: 320px - 3840px (width or height)
Aspect ratio: 16:9 or 9:16 recommended
iOS / App Store
Requirements:
Screenshots for each supported device size
Format: PNG or JPEG
No transparency
Actual device screenshots preferred
Different sizes for iPhone and iPad
Windows / Microsoft Store
Requirements:
Minimum: 1 screenshot
Format: PNG, JPEG, or GIF
Dimensions: Minimum 1366×768 or larger
Aspect ratio: 16:9 recommended
Testing Screenshots
1. Validate in Manifest
Check that screenshots are correctly included in the generated manifest:
Expected output:
2. Browser DevTools
3. Test Installation Flow
Desktop:
Android:
4. Lighthouse PWA Audit
Best Practices
1. Quantity and Sequence
Recommended number:
Minimum: 3 screenshots
Ideal: 4-6 screenshots
Maximum: 8 screenshots (platform limit)
Logical sequence:
2. Content Quality
Quality checklist:
3. Form Factor Strategy
Provide screenshots for both narrow and wide form factors:
4. Performance Optimization
Minimize file sizes:
5. Accessibility
Descriptive labels:
6. Localization
Use translation keys for international apps:
Common Issues
1. Screenshots Not Appearing in Install Dialog
Problem: Screenshots configured but not showing during installation
Solutions:
2. Screenshots Appear Blurry or Pixelated
Problem: Low quality or incorrect dimensions
Solutions:
3. Wrong Screenshots Shown for Device
Problem: Desktop screenshots shown on mobile or vice versa
Solutions:
4. Screenshots Not Converting to WebP
Problem: format: "webp" specified but images not converting
Solutions:
5. File Size Too Large
Problem: Screenshots causing slow manifest loading
Solutions:
Troubleshooting Checklist
Before submitting your PWA:
Related Documentation
Icons - Icon configuration for your PWA
Application Information - App metadata configuration
Translations - Localizing your manifest
Resources
MDN Web Docs: https://developer.mozilla.org/en-US/docs/Web/Manifest/screenshots
Web.dev: https://web.dev/add-manifest/#screenshots
PWA Builder: https://www.pwabuilder.com/ - Test and validate screenshots
Chrome DevTools: https://developer.chrome.com/docs/devtools/
Puppeteer: https://pptr.dev/ - Automated screenshot generation
Playwright: https://playwright.dev/ - Browser automation
Sharp: https://sharp.pixelplumbing.com/ - Image optimization library
Last updated
Was this helpful?