logoredraws.com

Configure a favicon in Next.js

How to set up a favicon in Next.js 13 and 14 with the App Router, prepare vector logo artwork for small sizes, and add dark mode variants that stay visible.

Published

Contents
  1. The short answer
  2. Which files Next.js recognizes
  3. Configuring icons through metadata
  4. Dark mode inside a single SVG favicon
  5. Pages Router projects
  6. Preparing the logo artwork for a favicon
  7. Final inspection
  8. What this guidance does not cover

The short answer

In Next.js 13 and 14 with the App Router, the simplest way to set a favicon is to place a file named favicon.ico at the root of the app directory. Next.js detects it and adds the matching link tag to the document head. You do not need to edit a layout or head component. For more control, you can add icon and apple-icon image files to the same folder, or declare icons in the metadata export of your root layout. The metadata option is also how you serve separate light and dark variants.

This article covers two things. It explains the Next.js configuration, and it explains how to prepare the vector logo that the favicon comes from. A favicon is usually your logo mark reduced to a few dozen pixels, so how the artwork is built affects the result as much as the code does.

Which files Next.js recognizes

The App Router uses file conventions for icons. The table below summarizes the documented conventions. Check the Next.js documentation for your installed version, because details have changed between releases.

File | Where it goes | What it does
favicon.ico | Root of the app directory only | Classic browser tab icon
icon.ico, icon.png, icon.jpg, icon.jpeg or icon.svg | App directory or a route segment | General site icon; Next.js reads the file to set type and sizes
apple-icon.png, apple-icon.jpg or apple-icon.jpeg | App directory or a route segment | Icon used when a page is saved to an Apple device home screen
icon.js, icon.tsx or apple-icon.tsx | App directory or a route segment | Generates the icon in code, using ImageResponse

You can supply several general icons by adding a number to the file name, such as icon1.png and icon2.svg. If an icon is declared both as a file and in the metadata object, the file-based version takes priority. To keep the setup easy to reason about, choose one approach per icon.

New projects created with the standard starter include a default favicon.ico inside the app directory. Replace or delete it. Do not put a second favicon.ico in the public folder, because Next.js reports a conflict when a public file and an app route resolve to the same path.

Configuring icons through metadata

If your icon files live in the public folder, or you need attributes the file conventions do not set, declare them in the root layout. Each icon entry can carry a url, type, sizes and media value. The media value is what makes light and dark variants possible.

// app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  icons: {
    icon: [
      { url: '/favicon.ico', sizes: 'any' },
      { url: '/icon-light.png', type: 'image/png', media: '(prefers-color-scheme: light)' },
      { url: '/icon-dark.png', type: 'image/png', media: '(prefers-color-scheme: dark)' },
    ],
    apple: '/apple-icon.png',
  },
}

Paths that begin with a slash resolve to the public folder. Next.js turns each entry into a link tag. Whether a browser respects the media attribute on icon links, and whether it swaps the icon live when the system theme changes, depends on the browser. The material for this article includes no browser test results, so test on the browsers your audience uses before relying on this behavior.

Dark mode inside a single SVG favicon

Instead of two files, you can use one SVG icon that changes its own colors. Because an SVG can include a style block, a prefers-color-scheme media query inside the file can recolor the mark when the browser or operating system uses a dark theme.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
  <style>
    .mark { fill: #111111; }
    @media (prefers-color-scheme: dark) {
      .mark { fill: #ffffff; }
    }
  </style>
  <path class="mark" d="M4 4h24v24H4z"/>
</svg>

Save this file as icon.svg in the app directory and Next.js will link it. Keep two limits in mind. First, the media query follows the browser or system theme, not a theme switch built into your site. Second, support for SVG favicons has differed across browsers, so keep a favicon.ico or PNG fallback. The path in the example is a placeholder square; replace it with your own mark.

Pages Router projects

If your project still uses the pages directory, the app-directory conventions do not apply. Put the icon files in the public folder and add the link tags yourself, either in a custom document or with the Head component on the pages that need them.

Preparing the logo artwork for a favicon

A favicon is shown at very small sizes, often 16 or 32 pixels in a browser tab. Logo detail that looks fine on a page usually becomes blurry at that scale. These steps assume you have the right to adapt the logo. Being allowed to download a logo file is not the same as being allowed to modify the artwork, its fonts or the trademark, so confirm usage rights first if the logo is not yours.

  • Start from the master vector file. Open it in your vector editor and check that the logo is made of editable paths. A file with an .svg, .ai or .eps extension can still contain only an embedded raster image or a raster preview.
  • Choose the simplest version of the logo. This is usually the symbol or a single letter, not the full wordmark. Remove small details, fine text and thin strokes that will not show at tab size.
  • Convert any text to outlines. This way the icon does not depend on a font being installed, and you avoid font licensing questions when the file is distributed.
  • Expand strokes into filled shapes so line weights do not change unexpectedly when the artwork is scaled.
  • Place the mark on a square artboard with a little even padding. Set a square viewBox for the SVG export.
  • Plan for both light and dark backgrounds. A dark mark on a transparent background can disappear on a dark tab bar. Either make a second color version, add a solid background shape behind the mark, or use the SVG media query shown above.
  • Export the files. Export an optimized SVG for icon.svg, square PNGs for icon and apple-icon (180 by 180 pixels is the common Apple touch icon size), and a multi-size favicon.ico, typically containing 16, 32 and 48 pixel versions.
  • Put each file in the app directory with the matching name, or in the public folder if you reference it through metadata.

Final inspection

  • Look at the rendered page source and confirm the expected icon link tags are in the head, with correct type, sizes and media values.
  • Open each icon URL directly to confirm it loads and is the current file.
  • Check the tab in both light and dark browser themes and make sure the mark is clearly visible in each.
  • View the 16 pixel version at actual size. If the shape blurs, simplify the artwork rather than sharpening the raster export.
  • If an old icon keeps showing, clear the cache or open a private window. Browsers cache favicons aggressively, so a stale icon is not necessarily a configuration problem.

What this guidance does not cover

The source material included no version-specific test results, no browser support data and no measurements. Statements here about how browsers handle SVG favicons and media-based icon switching are general principles, not verified results. Check them against the current Next.js documentation and your own testing on the browsers your audience uses.