FaviconIcon

Updated

How to Add a Favicon in React and Vite

On this page

To add a favicon to a standard React app built with Vite, put the icon in public/ and add a favicon link inside the <head> of your project’s root index.html. Configure Vite’s deployment base if your app lives under a subfolder.

This guide covers the browser tab icon, optional Apple and web app icons, and the checks that catch problems before and after deployment. It assumes a Vite app that uses index.html as its HTML entry point.

Quick setup

Save your icon as public/favicon.ico, then add this line to the existing <head> in index.html:

Basic ICO link
<link rel="icon" href="%BASE_URL%favicon.ico">

Replace the existing starter favicon declaration if it points to an icon you no longer want. Keep the rest of your HTML, including the script that starts your React app.

Vite supports HTML replacement of its environment constants. Here, %BASE_URL% uses the configured base: with /, the result is /favicon.ico; with /dashboard/, it is /dashboard/favicon.ico. Use %BASE_URL%favicon.ico without an extra slash between the placeholder and the filename. Vite

1. Create your favicon files

Start with a simple mark that remains recognizable when reduced to the size of a browser tab. Preview it on both light and dark backgrounds.

Use the FaviconIcon generator for a text favicon, or the image to favicon converter for an existing logo. Download the package and extract it.

You can start with the ICO file for a browser tab. The PNG, Apple touch icon, and manifest files extend the setup to other uses. You do not need every file merely to display a tab icon.

2. Put the files in public

With Vite’s default configuration, use the public directory at the project root. If your project changes publicDir, use that configured directory.

File in your projectUse
public/favicon.icoBrowser favicon
public/favicon-16x16.pngOptional 16 × 16 PNG favicon
public/favicon-32x32.pngOptional 32 × 32 PNG favicon
public/apple-touch-icon.pngApple home screen icon
public/android-chrome-192x192.pngIcon referenced by the web manifest
public/android-chrome-512x512.pngLarger icon referenced by the web manifest
public/site.webmanifestOptional web app manifest

Vite copies public files into the build output without renaming them. For a site served at the domain root, public/favicon.ico becomes available at /favicon.ico, not /public/favicon.ico. The directory name belongs to your project structure, not the public URL. Vite

Keep downloaded installation notes with your project documentation; they do not need to be served as public assets.

4. Match the base path to your deployment

An app at https://example.com/ normally uses Vite’s default base: "/".

An app at https://example.com/dashboard/ needs that deployment prefix. Add or update the base property in your existing Vite configuration:

Vite base option
base: "/dashboard/",

Place that property inside the options passed to defineConfig; preserve your existing plugins and other settings.

Deployment locationVite baseExpected favicon path
Domain root//favicon.ico
Subfolder named dashboard/dashboard//dashboard/favicon.ico
GitHub Pages project named notes/notes//notes/favicon.ico

Vite also rewrites recognized asset references in source HTML to respect base. A source reference such as /favicon.ico is not automatically a deployment bug. What matters is the URL in the built HTML and the request made on the deployed site. The explicit %BASE_URL% pattern makes the intended prefix clear. Vite

Keep the icon at public/favicon.ico; you do not need an extra public/dashboard/ directory for this configuration.

Rebuild after changing the base. For a client-routed app deployed at a known subfolder, use that explicit prefix instead of assuming ./ will resolve correctly from every nested URL.

5. Configure the optional web manifest

If you use site.webmanifest, update its application name and icon paths before publishing. A manifest saved in public/ is copied unchanged; Vite does not expand %BASE_URL% inside that JSON file.

When the manifest and its icons share a directory, relative icon paths keep them together. For example:

Web manifest
{
  "name": "Acorn Notes",
  "short_name": "Acorn",
  "start_url": "./",
  "display": "standalone",
  "icons": [
    {
      "src": "android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "android-chrome-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    }
  ]
}

Replace the sample name with your app’s name. If you already have a manifest, merge the relevant changes and retain its other settings.

At /dashboard/site.webmanifest, the first relative icon path resolves to /dashboard/android-chrome-192x192.png. A leading slash would instead point to the domain root. MDN

The example’s start_url: "./" points to the manifest’s directory, suitable when that is your app’s entry location. Change it if your launch page is elsewhere. MDN

Use purpose: "any" for ordinary artwork. Only declare a maskable icon when you have designed and checked its safe area. This manifest supplies app metadata and icons; a browser tab favicon does not require a manifest.

6. Verify the production build

If your project uses the standard Vite npm scripts, run:

Build and preview commands
npm run build
npm run preview

Open the URL printed by the preview server, including your configured base path. Vite’s preview command serves the built output for local inspection; deploy the generated output through your hosting setup. Vite

Check these points:

  1. The built HTML contains the expected favicon URL, with no unresolved %BASE_URL% token.
  2. Opening that URL returns the intended icon.
  3. The icon files are present in the build output.
  4. A direct visit to a nested application route still uses the correct icon URL.
  5. If you added a manifest, its icon URLs also resolve correctly.

Repeat the checks on the production hostname. A working local preview cannot confirm your host’s routing rules, deployed files, or cache state.

For a public deployment, run the page URL through the favicon checker to review the icon declarations and files exposed by your site.

Common React and Vite favicon problems

SymptomCheck next
The starter icon still appearsInspect the rendered head for an old icon link, then compare the referenced image with your new file
The request uses /public/favicon.icoRemove public from the URL; retain the correct deployment prefix
The icon works locally but fails after deploymentCompare the production request URL with the configured base and deployed output
The browser requests a path under the current pageInspect document-relative links and any HTML base element
The icon URL returns the app pageCheck missing assets and hosting fallback rules
The tab icon works but the installed app icon does notInspect the Apple touch icon or manifest separately

If the URL serves the right image but a browser still shows the previous one, investigate caching after confirming the active icon links. The favicon not showing guide walks through browser state, CDN caching, response types, and deployment differences.

Frequently asked questions

Do I need a React package to add a favicon?

No additional package is needed for the static setup shown here. Keep the icon files in the public directory and declare them in your HTML head.

Should I put the favicon in src or public?

For a fixed filename that you want to reference directly, public is the straightforward option. Assets imported from source code follow Vite’s asset processing rules. Use one approach consistently.

Do I have to use an ICO file?

No. A PNG favicon can also be declared with rel="icon" and the matching type and sizes. The ICO example is convenient when using a generated package that already includes it.

Do I need a manifest for a browser tab icon?

No. Use the manifest when you need web app metadata and related icons. Keep ordinary favicon links even when you also have a manifest.

Create and check your favicon

Create a favicon package, install the files using the steps above, then check the deployed site.

For a failure that persists after deployment, continue with Favicon Not Showing.

Download the reproducible Next.js and Vite example projects →