To add a favicon in Next.js App Router, place favicon.ico in the top level of your project’s app directory. If your application uses src/app, put it there instead. Next.js uses its metadata file conventions to add the corresponding icon link automatically. nextjs.org
This guide walks through creating the files, adding an Apple touch icon, configuring an optional web manifest, and checking the deployed result. The examples assume your app is served from the domain root.
Need icon files first? Create a favicon from text or convert your logo into a favicon package.
Step 1 Generate your favicon files
Start with a simple design that remains recognizable at a small size. A short initial or a clear logo mark is usually easier to read than a detailed illustration.
In FaviconIcon, you can create a text favicon or choose a PNG, JPG, WebP, or SVG image. The image converter accepts files up to 5 MB and processes the source image in your browser. Image to ICO, Free
Preview the result at browser sizes, then choose Download package and extract the ZIP. The icon files include:
| File | Size | Role in this guide |
|---|---|---|
favicon.ico | 16×16, 32×32, and 48×48 images in one file | Browser favicon |
favicon-16x16.png | 16×16 | Optional separate PNG icon |
favicon-32x32.png | 32×32 | Optional separate PNG icon |
apple-touch-icon.png | 180×180 | Apple home screen icon |
android-chrome-192x192.png | 192×192 | Optional manifest icon |
android-chrome-512x512.png | 512×512 | Optional manifest icon |
site.webmanifest | JSON file | Optional web app metadata |
The package also includes installation and reference documents. faviconicon.org
You can start with the browser favicon and add the other surfaces when you need them. The favicon size guide explains the files in more detail.
SVG is supported as an input to the image converter. The current package exports ICO and PNG image files; it does not include an icon.svg file.
Step 2 Add the browser favicon and Apple touch icon
Use the App Router directory that already exists in your project:
| Downloaded file | Project with app/ | Project with src/app/ |
|---|---|---|
favicon.ico | app/favicon.ico | src/app/favicon.ico |
apple-touch-icon.png | Rename to app/apple-icon.png | Rename to src/app/apple-icon.png |
Replace an existing default favicon.ico with your new file. Keep the favicon at the top level of the active App Router directory.
The Apple filename matters: Next.js recognizes apple-icon.png through its icon file conventions. Simply placing apple-touch-icon.png inside app does not use that convention.
For these two files, Next.js generates the icon links. You do not need to paste the generator’s HTML tags or add a second metadata.icons configuration. nextjs.org
The separate 16×16 and 32×32 PNG files are optional in this setup because the generated ICO already contains those sizes. Keep them available if you choose the public-folder method described later.
Step 3 Add a web manifest if your app needs one
A web manifest describes your app’s name, launch behavior, and icons for supporting browsers. You can complete the browser favicon setup without adding one.
If your project already has a manifest, update that existing file or generator. For a new manifest, place these files in public:
| File | Destination |
|---|---|
site.webmanifest | public/site.webmanifest |
android-chrome-192x192.png | public/android-chrome-192x192.png |
android-chrome-512x512.png | public/android-chrome-512x512.png |
Even when your application code lives in src/app, the public directory stays at the project root. nextjs.org
Open site.webmanifest and replace the generated name with your product’s name. Here is an example for an app called Acorn Notes:
{
"name": "Acorn Notes",
"short_name": "Acorn",
"start_url": "/",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#163b2e",
"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"
}
]
}Adjust the name, colors, and start URL to match your app. This example uses "purpose": "any". Declare an icon as maskable only when its artwork has been designed for the required safe area; adding the word does not change the image. MDN
Add the manifest reference to your root layout’s existing metadata:
import type { Metadata } from 'next';
export const metadata: Metadata = {
// Keep your existing metadata fields here.
manifest: '/site.webmanifest',
};Merge that field into the object you already have. If the layout uses generateMetadata, add it to that function’s returned metadata instead. Keep your existing title, description, Open Graph settings, and layout component. nextjs.org
Next.js also supports a manifest file or generator inside app. Use one maintained manifest for your app rather than adding another copy through this guide.
A manifest and icon files contribute to an app’s installation experience. Browser installability has additional requirements, and offline behavior requires separate implementation. See MDN’s PWA installation guide.
Step 4 Check for older icon settings
Before testing, inspect the project’s existing favicon setup. A starter template or a previous implementation may still reference older artwork.
Look for:
- Another
favicon.icounderpublic. - Existing
iconorapple-iconfiles and generated icon routes. - An
iconsfield in a layout or page’s metadata. - Manually added icon links.
With the file-convention setup above, keep the browser favicon in the App Router directory. Avoid also adding public/favicon.ico, which would target the same public URL. Next.js documents conflicts between public files and application routes.
Review additional icons before removing them. Some projects intentionally use different artwork for a nested section or a separate browser theme. Replace outdated defaults while preserving those deliberate choices.
File-based metadata takes priority over configuration-based metadata, so changing an icons object may not replace artwork supplied by an existing icon file. This behavior is covered in the Next.js metadata reference.
Step 5 Verify the favicon locally and after deployment
Start your development server using the project’s existing command. For a pnpm project, that is often:
pnpm devUse the host and port shown in the terminal.
First, open /favicon.ico on that host. Confirm that it returns the new image rather than an error page or the previous icon.
Next, inspect the rendered page’s icon links. Open the actual URL from the rel="apple-touch-icon" link to check the Apple image. Next.js can generate an address with a query string, so use the emitted href rather than assuming the URL matches the original ZIP filename. nextjs.org
If you added the manifest, open /site.webmanifest and each image URL listed inside it. Check that the product name, image dimensions, and paths are correct.
After deploying, repeat those checks on the production domain. A successful local check does not establish that the files were included in the deployed build.
For a public website, use the Favicon Checker to inspect the installed setup. Review individual findings against your intended configuration; optional icon recommendations do not automatically mean the browser favicon is broken. Test Your Site Favicon, Free
Finally, inspect the actual browser tab and, if relevant, the home screen or installation experience on your target device.
Troubleshooting a Next.js favicon that is not showing
Use the symptom to decide what to check first.
For checks beyond Next.js, follow the general favicon troubleshooting guide.
| Symptom | What to check | What to do |
|---|---|---|
/favicon.ico returns 404 | File location and deployed assets | Confirm the file is in the active App Router root and included in the build. |
| The direct URL shows an old icon | The deployed file and caching layers | Compare the served image with the new source file and inspect cache headers. |
| The direct URL is correct but the tab looks old | The page’s icon links and browser state | Check for another selected icon, then try a fresh browser profile or clear cached site data. |
| The Apple icon is missing | Filename and emitted link | Use apple-icon.png for the file convention and check the actual generated URL. |
| The icon works locally but fails in production | Deployment paths, casing, and routing rules | Check the production response and ensure authentication or rewrites are not returning HTML for an image URL. |
| Only some routes show the old image | Route-specific icon files and metadata | Inspect the affected route’s rendered links before changing global settings. |
Browsers and intermediary caches can retain resources differently. A normal refresh may not resolve every stale response; MDN’s caching guide explains the distinction between revalidation, reloads, and stored responses.
If your application is deployed under a subpath such as /docs, revisit manually written asset and manifest URLs. A path beginning with / points to the domain root. Check the actual deployed addresses and the Next.js basePath documentation.
A browser favicon and a favicon in Google Search are separate checks. Google needs to discover and process the relevant pages and image, and appearance is not guaranteed. Follow Google’s favicon guidance if the browser icon works but the search result has not updated. Our Google Search favicon troubleshooting guide walks through the evidence to check next.
Alternative method using public and metadata icons
Use this approach if you want to keep the generated filenames in public and declare them explicitly. It also matches the public-folder approach offered by FaviconIcon’s framework installation snippets.
Put the icon files in the project-root public directory. Files there are served from the site root, so public/favicon-32x32.png is referenced as /favicon-32x32.png. See the Next.js public-folder documentation.
Move away from any conflicting file-convention setup before switching. In particular, do not keep both the App Router and public-folder copies of favicon.ico.
Merge the following fields into the root layout’s existing metadata:
import type { Metadata } from 'next';
export const metadata: Metadata = {
// Keep your existing metadata fields here.
icons: {
icon: [
{ url: '/favicon.ico', sizes: 'any' },
{
url: '/favicon-32x32.png',
sizes: '32x32',
type: 'image/png',
},
{
url: '/favicon-16x16.png',
sizes: '16x16',
type: 'image/png',
},
],
apple: [
{
url: '/apple-touch-icon.png',
sizes: '180x180',
type: 'image/png',
},
],
},
manifest: '/site.webmanifest',
};Include the manifest field only if you installed that manifest. Keep metadata exports in a Server Component. If the layout already exports generateMetadata, merge these settings into its returned object instead of also adding a metadata export.
The metadata API documentation covers these constraints. Choose this explicit configuration or the earlier file-convention setup according to your project.
Install the package with an AI coding assistant
If you use Claude Code, Codex, or another assistant with access to your project, download the package and give it the actual location of the extracted files.
The following prompt follows the file-convention approach used in this guide:
Add my downloaded favicon package to this Next.js App Router project.
First inspect the project structure, existing icon files, metadata, manifest,
and any basePath setting. Use the extracted package I provide.
1. Put favicon.ico at the root of the active app or src/app directory.
2. Copy apple-touch-icon.png there as apple-icon.png.
3. Preserve intentional route-specific icons and unrelated metadata.
4. Avoid conflicting public/favicon.ico files and duplicate icon declarations.
5. If the project uses a web manifest, update it with the supplied app icons
and the project's actual identity. Preserve existing app settings.
6. Do not reference an SVG file unless it actually exists.
7. Run the project's available checks and inspect the emitted icon URLs.
8. Report the files changed, checks completed, and anything still unverified.After the changes, review the diff and check the deployed site. Generated edits should still be verified against the files and URLs your application serves.
Frequently asked questions
Do I need every file in the downloaded package?
Use the files that match your intended experience. The recommended setup starts with the ICO for the browser and adds the Apple icon for home screen use. The manifest and larger PNGs are for the optional app-icon setup described above.
Can I use my SVG logo?
Yes. You can convert it into ICO and PNG files with the image favicon generator. If you want to serve a native SVG too, keep an actual SVG file and configure it separately; the current generated package does not supply one.
Do I need a manifest just to show a favicon in the browser tab?
No. You can use the browser favicon setup without installing a web manifest. Add a manifest when you need its app metadata and installation-related settings.
What if my project uses the Pages Router?
The App Router file-convention steps in this article do not apply to a Pages Router-only project. In FaviconIcon, choose the Next.js Pages Router installation option and follow the instructions for that project structure.
Create and check your favicon
Choose your starting point, download the files, and install them using one of the methods above.