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:
<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 project | Use |
|---|---|
public/favicon.ico | Browser favicon |
public/favicon-16x16.png | Optional 16 × 16 PNG favicon |
public/favicon-32x32.png | Optional 32 × 32 PNG favicon |
public/apple-touch-icon.png | Apple home screen icon |
public/android-chrome-192x192.png | Icon referenced by the web manifest |
public/android-chrome-512x512.png | Larger icon referenced by the web manifest |
public/site.webmanifest | Optional 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.
3. Add the favicon links to index.html
For the files listed above, add these links inside the existing <head>:
<link rel="icon" href="%BASE_URL%favicon.ico">
<link rel="icon" type="image/png" sizes="32x32" href="%BASE_URL%favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="%BASE_URL%favicon-16x16.png">
<link rel="apple-touch-icon" sizes="180x180" href="%BASE_URL%apple-touch-icon.png">
<link rel="manifest" href="%BASE_URL%site.webmanifest">Only include links for files you actually deploy. If you only want the basic ICO setup, keep the first line. If your project already has a manifest, update that manifest instead of adding a second one.
Review any existing starter declaration, which might reference /vite.svg, /favicon.svg, or another template asset. Replace the unwanted reference.
Multiple icon links are valid when they intentionally supply different formats or sizes. The problem is an unintended old icon that remains eligible for selection. Browsers consider attributes such as type, sizes, and media when choosing an icon. MDN
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:
base: "/dashboard/",Place that property inside the options passed to defineConfig; preserve your existing plugins and other settings.
| Deployment location | Vite base | Expected 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:
{
"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:
npm run build
npm run previewOpen 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:
- The built HTML contains the expected favicon URL, with no unresolved
%BASE_URL%token. - Opening that URL returns the intended icon.
- The icon files are present in the build output.
- A direct visit to a nested application route still uses the correct icon URL.
- 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
| Symptom | Check next |
|---|---|
| The starter icon still appears | Inspect the rendered head for an old icon link, then compare the referenced image with your new file |
The request uses /public/favicon.ico | Remove public from the URL; retain the correct deployment prefix |
| The icon works locally but fails after deployment | Compare the production request URL with the configured base and deployed output |
| The browser requests a path under the current page | Inspect document-relative links and any HTML base element |
| The icon URL returns the app page | Check missing assets and hosting fallback rules |
| The tab icon works but the installed app icon does not | Inspect 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 →