iOS ignores an SVG apple-touch-icon

On 2026-10-06 the dev.to account daniel_pertu published a report on the install surface of pub-trivia.app, a web app for pub quiz nights, and its subject is an icon declaration that every tool in the build accepts and iOS does not use. The report states that the site declares <link rel="apple-touch-icon" href="/icon.svg">, that iOS expects a PNG there, and that handing it an SVG makes it ignore the declaration and fall back to a snapshot of the page, so the home screen entry shows a screenshot of the landing page where the logo should be (the report).

What the report examines

The report works from public artefacts it fetches itself: the app’s manifest and the icon declarations in its document head, which it prints along with the curl commands that produce them. Each finding is taken in turn below, in the terms the report and the documentation it concerns actually use (the report).

The manifest the report prints

The report prints the entire manifest for pub-trivia.app, fetched with curl -s https://pub-trivia.app/manifest.webmanifest. The object it shows gives name and short_name as PubTrivia, a description of “Live pub quiz nights, scan, join, play!”, start_url as /, display as standalone, background_color and theme_color both as #171717, and an icons array with a single entry: /icon.svg, with sizes of any, type of image/svg+xml, and "purpose": "maskable". The report’s own count of that output is seven fields and one icon, with no screenshots, no shortcuts, no categories, and no id (the report).

The report’s stated reason for that size is that a manifest serves people who install the site, and that the app has two audiences of which only one would. It describes a player arriving by scanning a code on their table, playing for one evening, and never returning to that URL, and a host who opens the same site every week, usually on the same laptop or tablet behind the bar. For the host the report calls a standalone window a genuine improvement, naming no address bar to mistype and no tab that somebody closes mid round, and concludes that display: standalone is there for exactly one user per venue (the report).

The report then defends the field choices behind that object. On start_url, it states that the value is / rather than /dashboard, because booting an installed app directly into the dashboard is nicer when the user is signed in and worse when they are not, since the app then opens on a redirect to a login form, and the landing page handles both states. On theme_color, the report states that the value appears twice, once in the manifest and once as a <meta name="theme-color"> element in the document head, and that this is not a mistake: the manifest value applies when the site is installed and the meta tag applies to browser chrome on an ordinary visit, which is every player’s visit (the report).

MDN documents that relationship between the two theme colour mechanisms. It states that the theme_color member specifies the default colour for a web application’s user interface, that the colour may be applied to various browser UI elements such as the toolbar, address bar, and status bar, and that it can be particularly noticeable in contexts like the task switcher or when the app is added to the home screen. MDN states that in browsers that support theme_color, the manifest value serves as the default theme colour across all pages where the manifest is applied, and that this default can be overridden using the theme-color value of the name attribute in the HTML <meta> element, which enables different theme colours for individual pages (MDN, theme_color).

The icon declaration iOS reads

The report prints the icon declarations the page emits, obtained by grepping the served HTML: a <link rel="manifest">, a <link rel="icon"> pointing at a fingerprinted favicon.ico with sizes="200x200" and type="image/x-icon", a second <link rel="icon"> pointing at /favicon.svg, and <link rel="apple-touch-icon" href="/icon.svg">. It identifies that last line as the bug, states that iOS does not read the manifest for a home screen icon, that it reads apple-touch-icon, and that it expects a PNG, conventionally 180 by 180. Its account of what happens with an SVG is that iOS does not scale the vector logo elegantly: it ignores the declaration and falls back to a snapshot of the page, so somebody adding the site to their home screen gets a small, blurry screenshot of the landing page. The fix the report gives is a 180 by 180 PNG and one changed href (the report).

The report cites webhint’s apple-touch-icon hint as its source for the iOS behaviour, and that hint states both halves of the problem. It states that apple-touch-icons requires that at least one Apple touch icon is present and of a standard size, and that since iOS 1.1.3, Safari for iOS has supported a way for developers to specify an image that will be used to represent the web site or app on the home screen, known as the touch icon. On the manifest question it states that as of iOS 11.1.0, Safari for iOS supports the web app manifest file, which provides a standard, cross-browser way of defining, among other things, the icons browsers can use in various contexts, and that Safari nevertheless ignores the icons defined in the web app manifest and still uses the non-standard apple-touch-icon (webhint, Use Apple touch icon).

The hint also supplies the format and size rules the report’s SVG fails. It states that it checks whether one or more apple-touch-icon declarations exist in the <head>, that each has rel="apple-touch-icon", that each declared image is accessible and does not result in a 404, and that each declared image is a PNG of one of the resolutions it lists. Those resolutions, which it attributes to Apple’s current guidance, are 180px by 180px for iPhone, 120px by 120px for iPhone X and Plus, 167px by 167px for iPad Pro, and 152px by 152px for iPad and iPad mini. It lists a declared image that is not a PNG, and a declared image that is not one of those sizes, among the examples that trigger the hint (webhint, Use Apple touch icon).

Two further details in the hint bear on how a touch icon should be declared. It states that not declaring the touch icon in the page and having it in the root of the site is not recommended, as Apple may change what is requested by default, and that when using one image there is no need to use the sizes attribute. It also states that in older versions of Safari for iOS the precomposed keyword could be used to prevent iOS from adding visual effects to the touch icon, naming rounded corners, drop shadow, and reflective shine, and that starting with iOS 7 no special effects are applied to touch icons, so there is no need to use precomposed (webhint, Use Apple touch icon).

The manifest icon with one purpose

The report’s second finding is that the single manifest icon declares "purpose": "maskable" and nothing else. It describes maskable as meaning the image has its important content inside a safe zone, so a launcher may crop it to whatever shape that platform uses, naming a circle, a squircle, and a rounded square, and calls it a promise about padding. Its argument is that declaring that as the only purpose leaves no entry saying how the icon should look uncropped, so surfaces that want a plain icon have only a maskable one to choose from, and a maskable icon used unmasked tends to look oddly small and floaty, because the padding that keeps the logo safe under a circular crop is empty margin when nothing crops it. The shape the report calls right is two entries pointing at two files, one with purpose: "any" and one with purpose: "maskable", drawn with different amounts of padding, on the grounds that they are genuinely different images rather than one image used twice (the report).

MDN’s definitions of those two keywords support that reading. MDN states that purpose is a case-sensitive keyword string that specifies one or more contexts in which the icon can be used by the browser or operating system, that if omitted the browser can use the icon for any purpose, and that browsers use these values as hints to determine where and how an icon is displayed. It defines maskable as indicating that the icon is designed with icon masks and safe zone in mind, such that any part of the image outside the safe zone can be ignored and masked away, and any as indicating that the icon can be used in any context, which it states is the default value. MDN also states that with multiple keywords the browser can use the icon for any of those purposes, so a single file can carry both claims if that is the intent (MDN, icons).

MDN separately documents the sizes value the manifest uses. It states that for raster formats like PNG, specifying the exact available sizes is recommended, and that for vector formats like SVG, any can be used to indicate scalability, which is the value the report’s manifest entry carries. It also states that specifying the type property can significantly improve performance, because it allows browsers to ignore images with unsupported formats more easily, where omitting it may require inferring the image format by more resource-intensive methods such as MIME sniffing the file for a signature (MDN, icons).

The one the report leaves alone

The third item is the favicon.ico declaration with sizes="200x200". The report states that the file is generated from the file in app/, that 200 by 200 is not a conventional favicon size, and that it is presumably what the actual bitmap inside the file measures. It states that it works and browsers scale it, that it is 4.4 KB to deliver an image displayed at 16 pixels next to a 1 KB SVG that would be sharper at every size, and that the only reason the .ico is there at all is for clients too old to take the SVG. The report leaves it in place and notes it, on the stated grounds that “works and is slightly wrong” is the natural state of favicon configuration (the report).

Why it matters for PWA developers

The report’s central observation is about feedback, not about icons. It states that nothing in the build warns about the SVG touch icon: the file resolves, the content type is correct, the SVG renders perfectly everywhere else, and the browser reports no error, so the failure appears only on a physical device, on the home screen. Generalising, it states that manifests and icon declarations are the one corner of a web app where every layer of tooling will report success on a configuration that does not work, that there is no type to get wrong, no request that 404s, and no console warning, and that the platform consuming the file is not the platform being built on, so it fails quietly by falling back to something plausible (the report).

The documented behaviour explains why a manifest audit alone does not catch it. webhint states that Safari for iOS supports the web app manifest as of iOS 11.1.0 but ignores the icons defined in it and still uses the non-standard apple-touch-icon, which means a correct icons array is not evidence about what an iOS home screen will show. That is also why webhint’s checks are written against the <head> declarations rather than the manifest: existence in <head> with rel="apple-touch-icon", accessibility of the referenced image, and PNG format at one of the listed resolutions (webhint, Use Apple touch icon).

The manifest side has the same property for a different reason. MDN describes purpose values as hints browsers use to determine where and how an icon is displayed, and maskable as a statement that the image was designed with icon masks and a safe zone in mind. Neither is verifiable from the manifest: the keyword asserts something about the artwork’s layout, and MDN’s definition of the safe zone is what makes that assertion meaningful rather than decorative. The report’s prescribed rule follows from both halves, which it states as verifying any file whose only consumer is an operating system on that operating system, once, by hand, on a real device, and for which it gives a concrete procedure: open the site in Safari, share, add to home screen, and look at the result (the report).

Related entries on this site

• Capabilities: follow this cross-reference alongside the report’s discussion of installation, home-screen icons, the manifest, and document-head declarations.
• Performance: the report weighs a 4.4 KB .ico displayed at 16 pixels against a 1 KB SVG, and MDN states that declaring icon type lets browsers skip MIME sniffing; follow this cross-reference alongside those details.
• Storage: follow this cross-reference alongside the cited material’s discussion of manifest and touch-icon declarations, icon selection, and display contexts.

Open and unverified

• Whether iOS falls back to a page screenshot specifically, rather than to some other default, when apple-touch-icon references an SVG is asserted by the report; webhint states only that the icon must be a PNG of a supported resolution and does not describe a fallback.
• Which iOS and Safari versions the report’s home screen result was observed on is not stated.
• Whether /icon.svg would be used by iOS if a PNG touch icon were declared alongside it is not addressed.
• Whether the report’s description of a maskable icon looking small and floaty when used unmasked corresponds to the behaviour of any specific launcher is not confirmed.
• Whether the 200 by 200 bitmap the report infers is inside the .ico file is actually its dimensions is stated as a presumption by the report, not a measurement.
• Whether the manifest’s sizes: "any" on the SVG entry affects which surfaces select that icon is not addressed by the report.

Sources

• Our apple-touch-icon is an SVG, so iOS has been using a screenshot of the page instead (dev.to)
• Use Apple touch icon (webhint.io)
• icons (developer.mozilla.org)
• theme_color (developer.mozilla.org)