Skip to content
    App Router...Metadata Filesfavicon, apple-icon, and icon

    favicon, apple-icon, and icon

    The favicon, apple-icon or, icon file conventions allow you to set icons for your application.

    They are useful for adding app icons that appear in places like web browser tabs, phone home screens, and search engine results.

    There are two ways to set app icons:

    Image files (.ico, .jpg, .png)

    Use an image file to set an app icon by placing a favicon, icon, or apple-icon image file the root /app segment.

    Next.js will evaluate the file and automatically add the appropriate tags to your app's <head> element.

    File conventionSupported file types
    favicon.ico
    icon.ico, .jpg, .jpeg, .png, .svg
    apple-icon.jpg, .jpeg, .png,

    favicon

    Add a favicon.ico image file to the root /app route segment.

    <head> output
    <link rel="icon" href="/favicon.ico" sizes="any" />

    icon

    Add an icon.(ico|jpg|jpeg|png|svg) image file to the root /app route segment.

    <head> output
    <link
      rel="icon"
      href="/icon?<generated>"
      type="image/<generated>"
      sizes="<generated>"
    />

    apple-icon

    Add an apple-icon.(jpg|jpeg|png) image file to the root /app route segment.

    <head> output
    <link
      rel="apple-touch-icon"
      href="/apple-icon?<generated>"
      type="image/<generated>"
      sizes="<generated>"
    />

    Good to know

    • You can set multiple icons by adding a number suffix to the file name. For example, icon1.png, icon2.png, etc. Numbered files will sort lexically.
    • App icons can only be set in the root /app segment.
    • The appropriate <link> tags and attributes such as rel, href, type, and sizes are determined by the icon type and metadata of the evaluated file.
      • For example, a 32 by 32px .png file will have type="image/png" and sizes="32x32" attributes.
    • sizes="any" is added to favicon.ico output to avoid a browser bug where an .ico icon is favored over .svg.

    Generate icons using code (.js, .ts, .tsx)

    In addition to using literal image files, you can programmatically generate icons using code.

    Generate an app icon by creating an icon or apple-icon route that default exports a function.

    File conventionSupported file types
    icon.js, .ts, .tsx
    apple-icon.js, .ts, .tsx

    The easiest way to generate an icon is to use the ImageResponse API from next/server.

    app/icon.tsx
    import { ImageResponse } from 'next/server';
     
    // Route segment config
    export const runtime = 'edge';
     
    // Image metadata
    export const size = {
      width: 32,
      height: 32,
    };
    export const contentType = 'image/png';
     
    // Image generation
    export default function Icon() {
      return new ImageResponse(
        (
          // ImageResponse JSX element
          <div
            style={{
              fontSize: 24,
              background: 'black',
              width: '100%',
              height: '100%',
              display: 'flex',
              alignItems: 'center',
              justifyContent: 'center',
              color: 'white',
            }}
          >
            A
          </div>
        ),
        // ImageResponse options
        {
          // For convenience, we can re-use the exported icons size metadata
          // config to also set the ImageResponse's width and height.
          ...size,
        },
      );
    }
    <head> output
    <link rel="icon" href="/icon?<generated>" type="image/png" sizes="32x32" />

    Good to know

    Props

    The default export function receives the following props:

    params (optional)

    An object containing the dynamic route parameters object from the root segment down to the segment icon or apple-icon is colocated in.

    app/shop/[slug]/icon.tsx
    export default function Icon({ params }: { params: { slug: string } }) {
      // ...
    }
    RouteURLparams
    app/shop/icon.js/shopundefined
    app/shop/[slug]/icon.js/shop/1{ slug: '1' }
    app/shop/[tag]/[item]/icon.js/shop/1/2{ tag: '1', item: '2' }
    app/shop/[...slug]/icon.js/shop/1/2{ slug: ['1', '2'] }

    Returns

    The default export function should return a Blob | ArrayBuffer | TypedArray | DataView | ReadableStream | Response.

    Note: ImageResponse satisfies this return type.

    Config exports

    You can optionally configure the icon's metadata by exporting size and contentType variables from the icon or apple-icon route.

    OptionType
    size{ width: number; height: number }
    contentTypestring - image MIME type

    size

    icon.tsx / apple-icon.tsx
    export const size = { width: 32, height: 32 };
     
    export default function Icon() {}
    <head> output
    <link rel="icon" sizes="32x32" />

    contentType

    icon.tsx / apple-icon.tsx
    export const contentType = 'image/png';
     
    export default function Icon() {}
    <head> output
    <link rel="icon" type="image/png" />

    Route Segment Config

    icon and apple-icon are specialized Route Handlers that can use the same route segment configuration options as Pages and Layouts.

    OptionTypeDefault
    dynamic'auto' | 'force-dynamic' | 'error' | 'force-static''auto'
    revalidatefalse | 'force-cache' | 0 | numberfalse
    runtime'nodejs' | 'edge''nodejs'
    preferredRegion'auto' | 'global' | 'home' | string | string[]'auto'
    app/icon.tsx
    export const runtime = 'edge';
     
    export default function Icon() {}

    Was this helpful?