A web app manifest is a JSON file that describes a web application to the browser, defining its name, icons, start URL, scope, colors and display mode so that the site can be installed and launched like a native app. In the mobile web, it is the core building block of progressive web apps: it controls how an installed app appears on the home screen, in the app switcher and on the splash screen, and whether it opens with or without browser interface.
The format is standardized by the W3C as the Web Application Manifest specification. A page points to the file with a link element whose relation is manifest, and the file is conventionally served as manifest.webmanifest or manifest.json with the media type application/manifest+json.
How browsers use the web app manifest
When a page loads, the browser fetches and parses the manifest in the background. It uses the data in three moments: to decide whether the site is installable, to build the installation prompt or menu entry, and to configure the app window each time the installed app starts.
On launch, the browser opens the start URL inside the declared display mode, applies the theme color to system bars and, on Android, shows a generated splash screen built from the name, background color and an icon. Navigation that stays inside the scope remains in the app window, while links outside it open in a regular browser tab.
| Member | Example value | Effect |
|---|---|---|
| name and short_name | Full name and a label under 12 characters | Install dialog and home screen label |
| start_url | A path such as /app/?source=pwa | Page opened when the app launches |
| scope | A path such as /app/ | Boundary of the app experience |
| display | standalone | Window style without browser chrome |
| icons | PNG files at 192 and 512 pixels | Home screen, splash and app switcher |
| theme_color and background_color | Hex color values | System bar tint and splash background |
| id | A stable identifier string | Keeps installs linked when URLs change |
Display modes and advanced members
The display member decides how much browser interface remains visible. Browsers fall back along a defined chain when a mode is not supported, and the newer display_override member lets developers list preferred modes in order before the standard fallback applies.
| Mode | Visible browser interface | Typical use |
|---|---|---|
| fullscreen | None, not even system bars | Games and immersive media |
| standalone | None, system bars remain | Most installable web apps |
| minimal-ui | Small set of navigation controls | Apps that need a back or reload button |
| browser | Full browser interface | Ordinary website behavior |
Further members extend integration with the operating system. Shortcuts add quick actions to the app icon’s context menu, screenshots and description enrich the install dialog, and share_target lets the app receive shared content from other apps on supporting platforms. Support varies by browser, so these are progressive enhancements rather than guarantees.
Installability requirements and platform differences
A manifest alone does not make a site installable. Browsers also require a secure HTTPS context, and Chromium-based browsers check that the manifest contains a name, suitable icons, a start URL and an app-like display mode before offering an install prompt.
| Platform | Manifest support | Installation path |
|---|---|---|
| Chrome on Android | Broad, including shortcuts and share target | Install prompt or browser menu |
| Samsung Internet | Broad | Install option in the browser menu |
| Safari on iOS and iPadOS | Partial, core members respected | Add to Home Screen from the share menu |
| Firefox on Android | Core members | Install option in the browser menu |
On iOS, home screen web apps gained features such as web push notifications in recent versions, but they still require the user to install the app manually. Developers often keep Apple touch icon tags alongside the manifest to control icons reliably on older Apple devices.
Writing a good manifest
A well-prepared manifest focuses on stable identity and high-quality icons. Mistakes in these two areas are visible to every user who installs the app.
- Provide icons at 192 and 512 pixels at minimum, plus a maskable icon with a safe zone so Android can crop it into different shapes.
- Set an explicit id early, because changing the start URL later would otherwise create a separate app identity.
- Keep short_name brief enough to fit under a home screen icon without truncation.
- Match theme_color with the matching meta tag in the page, so colors stay consistent before and after installation.
- Add a tracking parameter to start_url if analytics should separate installed launches from browser visits.
The manifest works together with a service worker, which provides offline behavior and caching. The manifest describes how the app looks and launches, while the service worker controls what happens when the network is slow or absent.
Common problems
Most issues surface in browser developer tools, which display parsed manifest values and installability warnings. Typical problems are easy to fix once identified.
| Symptom | Likely cause | Fix |
|---|---|---|
| No install option appears | Missing icons, name or HTTPS | Check installability warnings in developer tools |
| Icon shows a white border | Icon not marked as maskable | Add a maskable icon with safe padding |
| Links open in the browser | Scope narrower than app paths | Widen the scope to cover all app pages |
| Duplicate installs after redesign | Start URL changed without an id | Define a stable id member |
In plain words
A web app manifest is a small information card about a website that the browser reads. It tells the phone the app’s name, which picture to use as the icon, which page to open first and which colors to show.
Thanks to this card, a website can be added to the home screen and open in its own window, without the address bar, so it feels like a regular app. Without it, the phone would only save a simple bookmark.
A real-world example
A regional public transport operator runs a mobile website for timetables and ticket purchase. Many riders open it several times a day from a bookmark, and the team wants it to behave like an app without building separate native apps.
The developers add a manifest with the name, a short name of eight characters, maskable icons at 192 and 512 pixels, a start URL pointing to the journey planner, standalone display and the operator’s brand color. They also add a service worker that caches the latest timetable. Riders on Android now receive an install prompt, iPhone users are shown short instructions for Add to Home Screen, and installed launches tracked through the start URL parameter show that a growing share of daily visits comes from the home screen icon rather than the browser.