Adding a favicon in a React or Vite project should be simple, but small differences in file placement, HTML tags, caching, and app type can turn it into a recurring annoyance. This guide gives you a clean, reusable checklist for modern frontend projects: where to put favicon files, which formats to include, how to wire them into React and Vite setups, what to test before shipping, and when to revisit your icon set as your stack or brand changes.
Overview
If you only remember one thing, remember this: favicon setup is less about React itself and more about how your frontend build serves static assets. React components do not usually control the browser tab icon directly. Instead, your favicon is typically defined in the root HTML document and served as a static file.
That distinction matters because many developers search for terms like react favicon or add favicon react app and expect a component-level solution. In most cases, the cleanest approach is simpler:
- Generate a small, consistent favicon set from a square source image.
- Place the files in the correct static asset location for your toolchain.
- Add the appropriate
<link rel="icon" ...>tags in your root HTML. - Test in local development and after deployment.
- Handle cache refresh if the old icon persists.
For a standard Vite app, that usually means placing favicon files in the public folder and referencing them from index.html. For React projects built on other setups, the exact folder may differ, but the principle stays the same: static assets live outside your component tree and are linked from the document head.
A practical baseline for most projects includes these files:
favicon.icofor broad browser compatibilityfavicon.svgif you want a crisp scalable icon in browsers that support itfavicon-32x32.pngandfavicon-16x16.pngas fallbacksapple-touch-icon.pngif your site may be saved to an iPhone home screen
If your project is also a PWA, your icon setup extends beyond the favicon. You will also want app icons in the web manifest, including sizes designed for install prompts and mobile launchers. If that is your use case, it helps to review related guidance on PWA icon requirements, maskable icons, and the Apple touch icon.
One more useful framing: your favicon is part of your visual identity system, not just a technical checkbox. If you are aligning it with your avatar, social image, or site branding, see Open Graph image vs favicon vs avatar and personal website branding checklist for the broader picture.
Checklist by scenario
Use this section as a return-to checklist whenever you start a new project, change tooling, or refresh branding assets.
Scenario 1: Basic Vite favicon setup
This is the most common path for a new frontend app.
- Create a square source image. Start with a simple, high-contrast icon. Tiny browser tabs do not reward detail-heavy designs.
- Export a small favicon set. At minimum, prepare
favicon.ico,favicon.svgif available, and PNG fallbacks such as 32x32 and 16x16. - Place the files in the Vite public folder. A common setup is:
/public/favicon.ico/public/favicon.svg/public/favicon-32x32.png/public/favicon-16x16.png/public/apple-touch-icon.png - Open the project root
index.html. In Vite, this file is part of the app root rather than hidden inside a template directory. - Add icon tags inside
<head>. For example:<link rel="icon" href="/favicon.ico" sizes="any"> <link rel="icon" type="image/svg+xml" href="/favicon.svg"> <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"> <link rel="apple-touch-icon" href="/apple-touch-icon.png"> - Run the app and check the browser tab. Open a fresh tab or a private browsing window if the old icon lingers.
- Deploy and test the production URL. Asset paths that work locally can fail after deployment if the app is served from a subpath rather than the domain root.
For most developers searching vite favicon or vite public folder favicon, this is the cleanest answer.
Scenario 2: React project with a root HTML template
If your React project is not using Vite, the exact static folder may differ, but the workflow is usually the same.
- Find the HTML entry point. This is often the file that contains your root mounting element, such as a div where React attaches.
- Find the static asset directory. Many setups expose a public directory or equivalent location for files served directly.
- Add favicon files there. Keep filenames straightforward and consistent.
- Reference the icons from the HTML head. Avoid trying to manage the favicon entirely inside app code unless you need dynamic per-route behavior.
- Check path handling. If your app is served from a subdirectory, absolute paths like
/favicon.icomay need adjustment.
If your goal is simply to add favicon to a React app, this static-first approach is usually easier to maintain than runtime head management.
Scenario 3: React or Vite app deployed under a subpath
This is where many clean local setups break.
Examples include:
- Deployments under
example.com/app/instead of the site root - GitHub Pages project sites
- Docs portals or internal tools hosted under a nested route
Checklist:
- Confirm your base path. Know whether the app lives at the domain root or a nested path.
- Review favicon URLs in generated HTML. Open the deployed page source and inspect the final paths.
- Use path conventions consistent with your bundler or host. Do not assume root-relative paths always work.
- Test direct access to the favicon URL. If the browser cannot load the file directly, the tab icon will not update.
- Check deployment-specific guidance. For Pages-style hosting, this is especially important; see GitHub Pages favicon setup.
Scenario 4: PWA or installable app
A favicon is only one part of the icon story for installable web apps.
- Keep the favicon set in the HTML head. Browser tabs still need it.
- Add app icons to your web manifest. Include the sizes your app needs for install surfaces.
- Consider a maskable icon. This helps mobile launchers crop the icon more cleanly.
- Test install flows, not just browser tabs. A favicon that looks good at 16x16 may still fail as an app icon.
If this applies to your project, pair this guide with the site’s PWA-focused checklists linked above.
Scenario 5: Dynamic favicon changes by route or state
Some apps change the favicon based on theme, environment, unread notifications, or white-label branding. This can work, but it should be deliberate.
- Start with a static default favicon. Your app should still have a sensible icon before JavaScript runs.
- Only add runtime changes if they solve a real UX problem. Notification badges or tenant-specific branding are examples.
- Make sure head updates do not create duplicate icon tags. Duplicate tags can lead to confusing browser behavior.
- Test browser refresh and route transitions. Dynamic head updates can behave differently from a full page load.
For many projects, the cleanest setup is still a stable static favicon with no runtime swapping.
What to double-check
Before you mark favicon setup complete, run through these details. They catch most issues without turning a small task into a debugging session.
File format choices
Do not rely on only one format if you want broad compatibility. A practical combination is:
- ICO for broad legacy support
- SVG for crisp modern rendering where supported
- PNG for explicit fallback sizes
If you need more context on format decisions, the topic often comes down to a simple balance of compatibility and sharpness, especially in the familiar favicon PNG vs ICO discussion.
Source image quality
A favicon should survive reduction to a tiny size. Double-check that:
- The icon reads clearly at 16x16
- Contrast is strong enough against both light and dark browser UI
- Thin strokes are not disappearing
- The design does not depend on text unless it is a single bold letter
HTML head placement
Put icon tags in the document head, not inside a rendered component tree unless your framework explicitly supports controlled metadata there. The simpler your favicon setup, the easier it is to carry from project to project.
Path correctness in production
Always inspect the deployed app. The favicon can appear correct in local development but fail in production because:
- The base path changed
- The host rewrites assets differently
- The file was not copied to the final static output
- The path casing differs from the actual filename
Cache behavior
Favicons are famously sticky. If your new icon does not show:
- Hard refresh the page
- Open the site in a private window
- Test from another browser
- Temporarily rename the favicon file and update the HTML reference
If the problem persists, work through a structured debugging pass with this favicon troubleshooting checklist.
Brand consistency
A favicon is tiny, but it still signals identity. If you maintain a personal site, portfolio, docs tool, or product dashboard, check that the favicon aligns with your logo, avatar, and page visuals. That matters not just for aesthetics but for recognition and trust. If you are tightening your identity system, review when to refresh a favicon or profile picture.
Common mistakes
The easiest favicon setups fail for a few predictable reasons. Most are avoidable with a short pre-launch review.
Trying to solve favicon setup inside React first
Developers often look for a React package or component solution before checking the root HTML document. Unless you need dynamic behavior, that adds complexity without much benefit.
Using one oversized PNG and calling it done
One large image may work in some browsers, but it is not the cleanest or most resilient setup. Include at least a minimal multi-format set.
Forgetting about the apple touch icon
If users may save your site to a mobile home screen, this omission is easy to notice later and awkward to fix after launch.
Ignoring subpath deployments
This is one of the most common deployment-specific mistakes in frontend favicon setup. A root-relative path can silently break when your app lives under a nested route.
Making the icon too detailed
A favicon is not a miniature hero graphic. Fine illustration, multiple words, or subtle gradients often disappear at small sizes.
Not validating the final output after deployment
Local success is not enough. Check the deployed page source, open the icon URLs directly, and verify the browser tab on the production domain.
Changing the icon without planning for trust and recognition
A favicon swap can be technically correct but still confusing if it does not match your public identity. In creator and professional contexts, mismatched assets can make your site feel unfinished. In more sensitive cases, visual inconsistency can make it harder for users to distinguish your real site from a copycat. For the security side of this, see the brand impersonation checklist.
When to revisit
A good favicon setup is stable, but not permanent. Revisit this checklist when the inputs change, not just when something breaks.
Come back to your favicon setup in these situations:
- When you start a new React or Vite project. Reuse a known-good baseline instead of improvising each time.
- When your deployment target changes. Moving from local-only development to a CDN, static host, internal portal, or subpath deployment can affect asset paths.
- When you refresh branding. If your logo, avatar, color system, or product name changes, the favicon should be part of that update.
- When you add PWA features. Installable apps need a broader icon system than a simple tab icon.
- When browser or toolchain behavior changes. A bundler migration, framework upgrade, or new metadata convention can justify a quick review.
- Before seasonal planning or recurring maintenance cycles. If you do quarterly frontend hygiene or pre-launch audits, add favicon checks to that list.
Here is a simple action plan you can reuse:
- Keep one master square icon source file in your design or assets folder.
- Maintain a small standard favicon package for new projects.
- Use static HTML head links as your default approach.
- Test local, production, and private-window behavior before you close the task.
- Document any base-path or deployment-specific rules in the project README.
That last step is often the difference between a one-time fix and a reusable workflow. A short README note explaining where favicon files live, which tags are required, and how the app handles asset paths will save time for your future self and anyone else touching the project.
If your work spans multiple frontend stacks, it can also help to compare stack-specific patterns. For example, if you also work in Next.js, the favicon flow differs enough to justify a dedicated reference; see this Next.js favicon guide.
The cleanest modern setup is not the most elaborate one. It is the one that remains understandable after a long gap between project starts: a simple icon set, correct static asset placement, explicit head tags, and a quick production check before launch.