close
Guide
Config
Plugin
API
Community
Guide
Config
Plugin
API
Community

html.appIcon

  • Type:
type AppIconItem = {
  src: string;
  size: number;
  target?: 'apple-touch-icon' | 'web-app-manifest';
};

type AppIcon = {
  name?: string;
  icons: AppIconItem[];
  filename?: string;
};
  • Default: undefined

Set the web application icons to display when added to the home screen of a mobile device:

  • Generate the web app manifest file and its icons field.
  • Generate the apple-touch-icon and manifest tags in the HTML file.
TIP

Refer to the following documents for more information:

Example

For display on different devices, you will need to prepare several icons of different sizes.

The most commonly used icon sizes are 192x192 and 512x512, and you can customize the icon sizes and quantities to suit your needs.

export default {
  html: {
    appIcon: {
      name: 'My Website',
      icons: [
        { src: './src/assets/icon-192.png', size: 192 },
        { src: './src/assets/icon-512.png', size: 512 },
      ],
    },
  },
};

After compilation, the following tags will be automatically generated in the HTML:

<link rel="manifest" href="/manifest.webmanifest" />
<link
  rel="apple-touch-icon"
  sizes="180x180"
  href="/static/image/icon-192.png"
/>

Here, manifest.webmanifest is a JSON file that contains information about the application's name, icons, and other details.

{
  "name": "My Website",
  "icons": [
    {
      "src": "/static/image/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/static/image/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}
Icon size

For Chromium, you must provide at least a 192x192 pixel icon and a 512x512 pixel icon. If only those two icon sizes are provided, Chrome automatically scales the icons to fit the device. If you'd prefer to scale your own icons, and adjust them for pixel-perfection, provide icons in increments of 48dp.

name

  • Type: string
  • Default value: undefined

The name of the application that will be displayed when it is added to the home screen of the mobile device. If not set, the manifest.webmanifest file will not be generated.

For more details, see Web app manifests - name.

icons

  • Type: AppIconItem[]
  • Default value: undefined

The list of icons:

  • src is the path of the icon, which can be a URL, an absolute file path, or a relative path to the project root.
  • size is the size of the icon in pixels.
  • target refers to the intended target for the icon, which can be either apple-touch-icon or web-app-manifest. If target is not set, by default, the manifest file will include all icons, while the apple-touch-icon tags will only include icons smaller than 200x200.

Example

src can be set to an absolute path:

import path from 'node:path';

export default {
  html: {
    appIcon: {
      name: 'My Website',
      icons: [
        { src: path.resolve(__dirname, './assets/icon-192.png'), size: 192 },
        { src: path.resolve(__dirname, './assets/icon-512.png'), size: 512 },
      ],
    },
  },
};

Use target to specify the target for the icon:

export default {
  html: {
    appIcon: {
      name: 'My Website',
      icons: [
        {
          src: './src/assets/icon-180.png',
          size: 180,
          target: 'apple-touch-icon',
        },
        {
          src: './src/assets/icon-192.png',
          size: 192,
          target: 'web-app-manifest',
        },
        {
          src: './src/assets/icon-512.png',
          size: 512,
          target: 'web-app-manifest',
        },
      ],
    },
  },
};

filename

  • Type: string
  • Default value: 'manifest.webmanifest'

The filename of the manifest file.

export default {
  html: {
    appIcon: {
      filename: 'manifest.json',
    },
  },
};