Static Apple touch icon
A project needs a static icon for iPhone or iPad home-screen bookmarks.
Next.js 16+ · Directive
apple-icon
The apple-icon file convention defines an Apple touch icon for an App Router application. Add a supported image under app, or generate the icon from an apple-icon route.
How it works
The apple-icon convention defines an Apple touch icon for an App Router route segment. Place a supported image file in the app directory, or create an apple-icon.js, .ts, or .tsx route that default-exports a function; Next.js evaluates it and emits the corresponding head metadata.
Syntax
app/apple-icon.(jpg|jpeg|png)
app/apple-icon.(js|ts|tsx)Returns
A generated Apple touch icon and the corresponding apple-touch-icon head metadata.
Key points
- The convention supplies an application icon through the App Router's file-based metadata system.
- For a static icon, put the appropriately named file inside the app directory or a route segment.
- Discovery is automatic; no separate metadata export is required for the file-based form.
- The Apple-specific filename is
apple-icon, with JPG, JPEG, and PNG extensions. - Dynamic icons use a route file whose default export is the generator function.
Common mistakes
- Static Apple icons support only JPG, JPEG, and PNG image files.
Example: Generated Apple icon
// app/apple-icon.tsx
import { ImageResponse } from 'next/og'
export default function AppleIcon() {
return new ImageResponse(
<div style={{ fontSize: 64, background: 'white', width: '100%', height: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
A
</div>,
)
}Place this file in the app directory to generate an Apple touch icon dynamically.
When to use it
Generated icon
The icon must reflect runtime or application-specific values.
Automatic metadata
An app wants framework-managed head metadata without manually exporting icon configuration.
Interview questions
QHow do you add a static Apple touch icon in the App Router?
Use apple-icon.jpg, apple-icon.jpeg, or apple-icon.png in the app directory. Next.js discovers the file and adds an apple-touch-icon link to the document head.
Follow-up: How can the icon be generated instead of stored as an image? Create an apple-icon.js, .ts, or .tsx route with a default-exported function.
QWhat is the code-based apple-icon convention?
The generated form is a specialized Route Handler. Its supported files are JavaScript, TypeScript, and TSX, and the default export is the generator function.
Follow-up: What changed in Next.js 16? Image-generating functions receive params and id as promises, while generateImageMetadata still receives synchronous params.
QWhat does Next.js do after discovering apple-icon?
Next.js evaluates the convention and automatically adds the appropriate metadata tags to the app's head. For Apple icons, the resulting relation is apple-touch-icon.
Follow-up: Why prefer the file convention over manually configuring metadata? It lets Next.js derive the asset's metadata from the file and generate the correct head entry.
Related
faviconiconRoute Handlersroute segment configurationgenerateImageMetadataMetadata API