Modern Web Weekly #55
The modern web, tested and explained in plain English
How screenshots for the install dialog of PWAs really work
If you have created an installable web app, you really should include screenshots in the manifest.json file to enable the enhanced install dialog. This dialog is available in Chrome on desktop and Android and shows a native app-like install dialog that shows the name and description of the app and a couple of screenshots:
You can include these screenshots by adding them to manifest.json like this:
{
"screenshots": [
{
"src": "/src/img/screenshots/shot1-mobile.png",
"sizes": "400x822",
"type": "image/png",
"form_factor": "narrow"
},
{
"src": "/src/img/screenshots/shot2-desktop.png",
"sizes": "1280x676",
"type": "image/png",
"form_factor": "wide"
},
]
}I extensively tested this feature and found a lot of behavior that’s not specified or even contrary to the listed specifications.
Here we go.
form_factor
You can specify a total of 8 screenshots and specify which ones should be shown in the dialog on mobile and desktop by setting the form_factor property to “narrow” or “wide” respectively.
According to MDN, when form_factor is not specified, the screenshot should be considered suitable for all screen types but in practice, this is not the case. I found that when screenshots don’t have a form_factor specified, they’re only shown on mobile devices, not on desktop. Only screenshots with form_factor “wide” are shown on desktop devices.
It doesn’t matter if the screenshots without form_factor are wide, desktop-sized images, they will be shown on mobile devices anyway. You can even have images with mixed aspect ratios: a mobile device will simply pick the first image and show other images that have the same aspect ratio, regardless of the order in which they appear in manifest.json. Images with an aspect ratio other than the first image will be ignored.
When form_factor “narrow” is specified, mobile devices will only use these images if they have the same aspect ratio, regardless of the order in which they appear in manifest.json.
Conversely, images with form_factor “wide” will all be shown on desktop, regardless of their aspect ratios.
On mobile devices, a total of 5 screenshots will be shown in total.
Conclusion
With these testing results, my recommendation is to always specify a form_factor for both mobile and desktop devices and make sure that all images per form_factor have the same aspect ratio. This way, you can be sure that the right screenshots will be shown on the right platform.
Defining the label of the Home Screen icon with short_name
Besides the name member of manifest.json that specifies the full name of your PWA, you can also specify the short_name member which holds a shorter version of the name.
But how exactly is this used?
The short_name is the name that appears as the label below the icon on the Home Screen of Android devices and as the tooltip when hovering over the icon in the Dock on macOS.
PWAs installed through Chrome and Edge show the full name of the app on Windows and macOS.
Here’s what the icons look like on Android, iOS, and macOS:
As you’ll probably notice, there is limited space for the label on Android and iOS.
I tested how the platforms behave and this is what I found.
There is room for around 15 to 18 characters on both Android and iOS for the label. This also depends on the width of the letters that are used, so if the short_name has a lot of capital letters your milage may vary. On macOS, the tooltip that is shown when you hover over the icon is simply expanded to accommodate the amount of letters.
If the short_name can’t be fit in the label, it will be truncated and an ellipsis will be shown:
iOS will first try to fit the whole short_name in the label by compressing the space between the letters:
Android 15 can fit a few more letters than Android 14 and lower. Where the short_name “What PWA Can Do” is truncated on Android 14, it’s fully shown on Android 15:
It will take some trial and error to find to optimal length for short_name for your app if it’s close to 15 characters depending on the width of the characters used, but if it’s below 15 you should generally be safe.
It’s best to avoid a short_name with ellipsis as it makes it less readable and harder to understand. Also, keep in mind that users are able to edit the label on iOS and macOS when they first install your app.
PWA Audit: on your way to a great PWA
Do you already have a PWA, but are you running into issues with performance, security, or functionality? Or are you not sure how to make your PWA better?
I can help you by running an audit of your PWA
I will evaluate it on more than 35 criteria and provide you with clear and actionable instructions on how to improve it. No generic stuff that you can get anywhere, but an in-depth quality checkup to get you on your way to a great PWA.
Some of the criteria I will evaluate it on are:
Installability
Cross-device and cross-platform compatibility
Offline support
Usability
Effective use of modern web APIs
Performance
Security
Your investment in the improvement of your PWA through the audit is €599 excluding VAT (where applicable).
If you want to request an audit or first would like to know more, you can
fill out the form or book a call with me.
Web apps on iOS 26
Apple announced that on iOS 26, any website can be installed as an app to the Home Screen, similar to web apps added to the Dock on macOS.
The interesting thing is that on macOS, web apps added to the Dock will capture links within their scope. This means that when you click a link to your app in an email or a text message, macOS will open the installed web app instead of the default browser.
This is a proprietary Apple implementation and is unrelated to the handle_links property of manifest.json. I hoped that this would mean that this same link capturing behavior would be brought to iOS, but unfortunately, it seems this is not the case.
I tested this in Simulator and a link to What PWA Can Do Today in the Calendar app was opened in Safari instead of the PWA. On macOS, the same link was opened in the installed app.
I haven’t been able to test this in the Mail or Notes apps since these apps are not available in this Simulator build (and can’t be installed), but I suspect this link capturing won’t be impelemented in iOS 26.
Hopefully, it will be implemented in a later build but Apple being Apple, we’ll have to wait till the final build to find out.
I’ll keep you posted…