# iOS ignores an SVG apple-touch-icon

> A dev.to report finds a PWA declaring apple-touch-icon as an SVG, which it says iOS drops for a page screenshot, and a manifest icon marked maskable only.

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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

## 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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

### 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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

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](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

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](https://webhint.io/docs/user-guide/hints/hint-apple-touch-icons/)).

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](https://webhint.io/docs/user-guide/hints/hint-apple-touch-icons/)).

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](https://webhint.io/docs/user-guide/hints/hint-apple-touch-icons/)).

### 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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

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](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/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](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

## 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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

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](https://webhint.io/docs/user-guide/hints/hint-apple-touch-icons/)).

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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef)).

## Related entries on this site

- [Capabilities](/reference/capabilities/): follow this cross-reference
  alongside the report's discussion of installation, home-screen icons, the
  manifest, and document-head declarations.
- [Performance](/reference/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](/reference/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](https://dev.to/daniel_pertu/our-apple-touch-icon-is-an-svg-so-ios-has-been-using-a-screenshot-of-the-page-instead-25ef) (dev.to)
- [Use Apple touch icon](https://webhint.io/docs/user-guide/hints/hint-apple-touch-icons/) (webhint.io)
- [icons](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) (developer.mozilla.org)
- [theme_color](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/theme_color) (developer.mozilla.org)