The Web App Manifest Explained: Adding Your Site to the Home Screen

What Is a Web App Manifest?

A web app manifest is a JSON file that provides information about a web application — its name, icons, start URL, display mode, and other properties — in a standardised format that browsers and operating systems can use to install the web app on a device.

When a website includes a manifest and meets certain criteria (typically: served over HTTPS, has a service worker), the browser offers an "Add to Home Screen" or "Install" prompt. When installed, the web app appears on the device's home screen, app drawer, or taskbar like a native app — with its own icon, name, and optionally a standalone window without browser chrome.

The manifest is linked from HTML using:

<link rel="manifest" href="/manifest.json">

A Complete Manifest Example

{
  "name": "GoWin Tools",
  "short_name": "GoWin",
  "description": "Fast, clean web tools for everyday tasks",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#4f46e5",
  "orientation": "any",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-maskable.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

Key Fields Explained

name and short_name

name is the full application name used in installation prompts and splash screens. short_name is a shorter version used where space is limited — particularly below the icon on a home screen. If short_name is not provided, name is used everywhere.

Practical limits: on most Android home screens, approximately 10–12 characters are displayed below an icon before truncation. iOS displays slightly more. If your app name is long, choose a short_name carefully — "GoWin" is better than "GoWin Tools" for a home screen label.

start_url

The URL that the web app opens to when launched from the home screen. This is often / (the home page), but can be any URL within the app's scope. For apps that should open to a specific section or with a specific query parameter (for analytics tracking of PWA launches), start_url can include these: /?source=pwa.

display

Controls the browser UI shown when the app is opened:

• standalone: App opens in its own window without browser address bar, navigation buttons, or other browser chrome. Most common for PWAs that want a native app appearance.
• fullscreen: App covers the entire screen, including the OS status bar. Used for games and immersive experiences.
• minimal-ui: App has minimal browser UI — typically just a back button and URL display — but no full toolbar.
• browser: App opens in the regular browser tab. Equivalent to a normal bookmarked link.

background_color

The background color displayed on the app's splash screen while it loads. Should match the background of the app's initial screen to create a smooth launch experience. Specified as a hex color or CSS color keyword.

theme_color

The color used for the browser's UI elements when the app is open — specifically, the address bar color in Chrome on Android and the status bar tint on some platforms. Gives the app a cohesive appearance where the browser chrome matches the app's color scheme. Should be the app's primary brand color.

Note: theme_color in the manifest can be overridden by a <meta name="theme-color" content="..."> tag in the HTML, which can be dynamically changed with JavaScript — useful for apps that use different colors for different sections or that support dark mode.

icons

An array of icon objects, each specifying a source image, a sizes string (space-separated list of WxH values, or "any" for SVG), and a type (MIME type of the image).

Required sizes for broad support:

• 192×192 PNG: Used by Android/Chrome for home screen icons and splash screens
• 512×512 PNG: Required by Chrome for PWA install on Android; used for splash screens at high DPI
• Maskable icon: A variant designed to work with adaptive icon masking on Android (see below)
• iOS still uses the apple-touch-icon HTML link rather than manifest icons — manifest icons are not used for iOS home screen

Maskable Icons: Android Adaptive Icons

Android 8.0 (Oreo) introduced "adaptive icons" — a system where apps provide a foreground layer and a background layer, and the OS applies a shape mask (circle, rounded square, squircle, etc.) that varies by device and user preference. Without a properly designed maskable icon, the browser uses a fallback that may look clipped or poorly framed.

A maskable icon must have the main design within the "safe zone" — a circle inscribed within the icon's square bounds, approximately 80% of the total icon size. The area outside the safe zone may be clipped by the OS mask shape. The icon should have a solid background color that extends to the edges — no transparent background — so that any mask shape produces a coherent result.

The "purpose": "maskable" field in the manifest icon object signals that this icon is designed for adaptive icon masking. A separate maskable icon is typically needed alongside the standard icon — because the maskable version's "safe zone" constraint means the logo appears smaller than in the standard version, which may look wrong as a browser tab icon.

PWA Requirements Beyond the Manifest

A manifest alone does not make a site installable as a PWA. Chrome's installability requirements (as of 2023) include:

• Served over HTTPS (or localhost for development)
• A valid web app manifest with the required fields
• A registered service worker with a fetch event handler (for offline support)
• The icons array must include at least one 192×192 and one 512×512 icon
• The site must not be already installed

When all requirements are met, Chrome shows an install prompt automatically (or on user action for non-mobile contexts). The install experience and thresholds have changed across Chrome versions — Google has adjusted the installability criteria several times to balance user experience against prompting fatigue.

Generate your favicon →