How to Add a Favicon to a Browser Tab With HTML
Add a browser-tab favicon with HTML, choose the right file path and format, support multiple icons, and fix common missing-icon problems.
The direct answer is to add a <link rel="icon"> element inside your document’s <head> and point href to an image file:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My site</title>
<link rel="icon" href="/favicon.ico">
</head>
<body>
<h1>My site</h1>
</body>
</html>The leading slash makes the URL site-root relative, so the browser requests https://your-domain.example/favicon.ico. Put the file where your deployed server actually exposes it. The icon link belongs in the document head, not in visible page content. MDN explains the head metadata model.
1. Add the smallest working favicon
Create an icon file, place it at your site’s public root, and add this line:
<link rel="icon" href="/favicon.ico">You can use a PNG instead:
<link rel="icon" href="/favicon.png" type="image/png">The browser uses the URL in href to fetch the resource. If your framework serves static files from a reserved directory such as public or static, put the source file there but use the final public URL in HTML. For example, a file at public/favicon.png is commonly referenced as /favicon.png after deployment.
2. Choose a favicon format and path
| Format | Example | Use it when |
|---|---|---|
| ICO | /favicon.ico |
You want the traditional root favicon and broad legacy compatibility. |
| PNG | /favicon-32.png |
You have a raster image and know its dimensions. |
| SVG | /favicon.svg |
You want a scalable vector icon and your target browsers support SVG favicons. |
Declare the MIME type when it accurately describes the file. The URL, server response, and declared type should agree. A broken path or an incorrectly served file prevents the browser from using the icon.
Browsers and other software often look for a site-root /favicon.ico automatically. The HTML standard permits that fallback when no icon link is present, but an explicit link is clearer and lets you store the file elsewhere. See the HTML Standard’s link processing rules.
3. Provide multiple icon candidates
You may offer several resources. User agents can use attributes such as media, type, and sizes to select a suitable candidate; selection is implementation-dependent.
<link rel="icon" href="/favicon.svg" type="image/svg+xml" sizes="any">
<link rel="icon" href="/favicon-32.png" type="image/png" sizes="32x32">
<link rel="icon" href="/favicon-16.png" type="image/png" sizes="16x16">Use sizes="any" for a scalable icon such as SVG. For raster files, declare dimensions that are actually present in the resource. The sizes value is advisory, so it should describe the asset rather than promise a size it does not contain. MDN’s rel reference documents these selection hints.
Conditional icons with media
If you have different assets for a condition such as a color scheme, you can add a media condition:
<link rel="icon" href="/favicon-light.svg" type="image/svg+xml" media="(prefers-color-scheme: light)">
<link rel="icon" href="/favicon-dark.svg" type="image/svg+xml" media="(prefers-color-scheme: dark)">Only add candidates that are valid and intentionally maintained. Different browsers may choose differently when several candidates are suitable.
4. Add an Apple home-screen icon separately
A browser-tab favicon and an Apple home-screen web clip icon are different declarations. If you need the latter, add:
<link rel="apple-touch-icon" href="/apple-touch-icon.png">You can include a size hint when you maintain a specific asset:
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">apple-touch-icon is a separate, non-standard convention. It is not required for a favicon to appear in a normal browser tab. MDN’s metadata guide covers the distinction.
5. Avoid obsolete markup
Use rel="icon". Do not use rel="shortcut icon" as the recommended form: MDN describes shortcut as non-conforming and advises authors to use icon instead.
6. Framework and deployment checklist
- Place the source image in the framework’s static asset directory.
- Confirm the generated HTML contains the
<link rel="icon">element inside<head>. - Open the exact public URL from
hrefdirectly in a browser. - Check that the deployment serves the file as an image and returns a successful response.
- Verify that the declared
typeandsizesmatch the actual file. - Test a fresh tab or a private window after deployment because browsers can cache icons.
7. Troubleshoot a missing favicon
| Symptom | Likely cause | Fix |
|---|---|---|
| No icon and no network request | The link is missing, outside <head>, or the deployed page is not the HTML you edited. |
Inspect the deployed document source and add the link inside <head>. |
| 404 for the icon URL | The path is wrong for the deployed site. | Open the exact href URL and move the asset or change the URL. |
| Image request succeeds but icon is ignored | The response is not served as a supported image, or type/sizes is inaccurate. |
Serve the real image file and correct or remove inaccurate hints. |
| Old icon remains | The browser has cached the favicon. | Use a fresh/private window, restart the browser, or change the asset URL when your deployment strategy allows it. |
| Root fallback works but custom path does not | The browser found /favicon.ico, masking a broken explicit link. |
Test the explicit URL directly and fix its deployment path. |
| Apple home-screen icon is absent | A regular favicon link does not declare an Apple touch icon. | Add a separate rel="apple-touch-icon" link and asset. |
These checks follow the documented link and selection behavior; browser selection can vary, so verify the actual deployed URL and markup.
8. Performance and reliability considerations
- Keep the icon small so the browser can fetch it quickly during navigation.
- Use a stable, cacheable URL and change the URL when you intentionally need to invalidate a long-lived cached asset.
- Serve every declared candidate reliably. A broken first candidate can produce inconsistent results across user agents.
- Do not declare dimensions that the raster file does not contain; inaccurate hints make candidate selection less predictable.
- Test the production hostname, subpath deployments, redirects, and content security or proxy rules that could affect static assets.
9. Capture the finished tab for documentation or QA
After deploying, you may want a repeatable screenshot of the page and its tab state for a visual regression record. ScreenshotNeo is a website screenshot API and MCP server. It can capture a URL as PNG, JPEG, WebP, or PDF, with options such as full-page capture, custom viewport, device presets, waiting for a selector or network idle, and custom CSS or JavaScript.
Or skip the browser setup
Use one request to capture the deployed page; see the ScreenshotNeo API documentation for all parameters.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
FAQ
Does a favicon have to be named favicon.ico?
No. Any supported image URL works when referenced with rel="icon". The filename favicon.ico is simply the common root fallback.
Can I use a relative path without a leading slash?
Yes. A path such as images/icon.png resolves relative to the document URL. Use /icon.png when you mean the site root, especially on nested routes.
Is apple-touch-icon required for browser tabs?
No. It targets Apple home-screen web clips and is separate from the normal tab favicon.
Should I include both SVG and PNG?
You can provide multiple candidates when you maintain accurate files and metadata. User agents choose among suitable links using hints such as type, media, and sizes.
Why does the favicon appear on one route but not another?
A document-relative URL may resolve to different directories on different routes. Use a site-root path or verify the resolved URL for each deployed page.
