Experiments
Guides

App Icons

Learn how metadata files work with logos.

By following the convention for your logos, you can automatically generate link tags.

This is based on Next.js Metadata File with an almost identical API, however runtime images are not supported.

You can optionally place logos in the root of your public folder or alongside your pages directory. Any images in the pages directory will take share the same routing.

Naming Convention

favicon

  • Name: favicon.ico

Using an ico file for your favicon is a good practice as all browsers support it, you can pack multiple icon sizes into it without having to define a number of extra icon links.

The favicon.ico file should be placed in the public directory. It is supported by most browsers and displayed in the browser tab.

By default, it won't output any HTML as browsers know where to look for it. If you're using a baseURL then it will output the correct path.

head output
<link rel="icon" href="/base/favicon.ico" sizes="any" />

icon

  • Name: *icon.{ico,jpg,jpeg,png,svg}, *icon-*.{ico,jpg,jpeg,png,svg}

Icons give you greater control over the displayed icon. You can provide multiple icons and the browser will automatically select the best icon based on the device's pixel density and uses it to display the app icon.

If you have multiple icons and need to sort them, it's recommended you prefix them with their order. For example: 1.icon.png, 2.icon.png, 3.icon.png.

head output
<link rel="icon" href="/1.icon.png" sizes="32x32" type="image/png" />
<link rel="icon" href="/2.icon.png" sizes="192x192" type="image/png" />
<link rel="icon" href="/3.icon.png" sizes="360x360" type="image/png" />

Dark / Light Mode

You can also provide dark and light mode icons by appending -dark,-light, .dark or .light to the icon name.

head output
<link rel="icon" href="/icon-dark.png" type="image/png" media="(prefers-color-scheme: dark)" />
<link rel="icon" href="/icon-light.png" type="image/png" media="(prefers-color-scheme: light)" />

apple-touch-icon

  • Name: *apple-icon.{png,jpg,jpeg}, *apple-touch-icon.{png,jpg,jpeg}

Apple touch icons are used by iOS devices to display a website's icon on the home screen and in the browser tab. You can again provide multiple icons.

head output
<link rel="apple-touch-icon" href="/apple-icon.png" sizes="180x180" />

Pages Directory

You can also place logos in your pages directory. This is useful if you want to have different logos for different pages.

The naming convention is the same as the public directory.

pages/
├── index.vue
├── admin/
   ├── index.vue
   └── icon.png

This will overwrite any logos in the public directory for all admin pages.

You can optionally also place your files within the _dir directory, which will work the same way.

pages/
├── index.vue
├── admin/
   ├── _dir/
   └── icon.png # Does the same thing!
   └── index.vue