generateMetadata
You can use the metadata object or the generateMetadata function to define metadata.
The metadata object
To define static metadata, export a Metadata object from a layout.js or page.js file.
import type { Metadata } from 'next'
export const metadata: Metadata = {
title: '...',
description: '...',
}
export default function Page() {}export const metadata = {
title: '...',
description: '...',
}
export default function Page() {}See the Metadata Fields for a complete list of supported options.
generateMetadata function
Dynamic metadata depends on dynamic information, such as the current route parameters, external data, or metadata in parent segments, can be set by exporting a generateMetadata function that returns a Metadata object.
Resolving generateMetadata is part of rendering the page. If the page can be prerendered and generateMetadata doesn't introduce dynamic behavior, the resulting metadata is included in the page's initial HTML.
Otherwise the metadata resolved from generateMetadata can be streamed after sending the initial UI.
import type { Metadata, ResolvingMetadata } from 'next'
type Props = {
params: Promise<{ id: string }>
searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}
export async function generateMetadata(
{ params, searchParams }: Props,
parent: ResolvingMetadata
): Promise<Metadata> {
// read route params
const { id } = await params
// fetch data
const product = await fetch(`https://.../${id}`).then((res) => res.json())
// optionally access and extend (rather than replace) parent metadata
const previousImages = (await parent).openGraph?.images || []
return {
title: product.title,
openGraph: {
images: ['/some-specific-page-image.jpg', ...previousImages],
},
}
}
export default function Page({ params, searchParams }: Props) {}export async function generateMetadata({ params, searchParams }, parent) {
// read route params
const { id } = await params
// fetch data
const product = await fetch(`https://.../${id}`).then((res) => res.json())
// optionally access and extend (rather than replace) parent metadata
const previousImages = (await parent).openGraph?.images || []
return {
title: product.title,
openGraph: {
images: ['/some-specific-page-image.jpg', ...previousImages],
},
}
}
export default function Page({ params, searchParams }) {}For type completion of params and searchParams, you can type the first argument with PageProps<'/route'> or LayoutProps<'/route'> for pages and layouts respectively.
Good to know:
- Metadata can be added to
layout.jsandpage.jsfiles.- Next.js will automatically resolve the metadata, and create the relevant
<head>tags for the page.- The
metadataobject andgenerateMetadatafunction exports are only supported in Server Components.- You cannot export both the
metadataobject andgenerateMetadatafunction from the same route segment.fetchrequests insidegenerateMetadataare automatically memoized for the same data acrossgenerateMetadata,generateStaticParams, Layouts, Pages, and Server Components.- React
cachecan be used iffetchis unavailable.- A page's explicit
openGraph.imagesortwitter.imagesproperty frommetadataorgenerateMetadataoverrides the corresponding file-based images in the same segment or inherited from parent segments.
Why generateMetadata is Server Component only
generateMetadata and the metadata export are only supported in Server Components because metadata must be resolved on the server before the page component is rendered. This allows Next.js to include the metadata in the initial HTML response.
If you need to use Client Component features, keep your page.tsx as a Server Component and move the Client Component logic to a separate file:
import type { Metadata } from 'next'
import { InteractiveComponent } from './interactive-component'
export const metadata: Metadata = {
title: 'My Page',
}
export default function Page() {
return <InteractiveComponent />
}import { InteractiveComponent } from './interactive-component'
export const metadata = {
title: 'My Page',
}
export default function Page() {
return <InteractiveComponent />
}'use client'
export function InteractiveComponent() {
// Client-side interactivity (hooks, event handlers, etc.)
}'use client'
export function InteractiveComponent() {
// Client-side interactivity (hooks, event handlers, etc.)
}Reference
Parameters
generateMetadata function accepts the following parameters:
-
props- An object containing the parameters of the current route:-
params- An object containing the dynamic route parameters object from the root segment down to the segmentgenerateMetadatais called from. Examples:Route URL paramsapp/shop/[slug]/page.js/shop/1{ slug: '1' }app/shop/[tag]/[item]/page.js/shop/1/2{ tag: '1', item: '2' }app/shop/[...slug]/page.js/shop/1/2{ slug: ['1', '2'] } -
searchParams- An object containing the current URL's search params. Examples:URL searchParams/shop?a=1{ a: '1' }/shop?a=1&b=2{ a: '1', b: '2' }/shop?a=1&a=2{ a: ['1', '2'] }
-
-
parent- A promise of the resolved metadata from parent route segments.
Returns
generateMetadata should return a Metadata object containing one or more metadata fields.
Good to know:
- If metadata doesn't depend on request information, it should be defined using the static
metadataobject rather thangenerateMetadata.fetchrequests are automatically memoized for the same data acrossgenerateMetadata,generateStaticParams, Layouts, Pages, and Server Components. Reactcachecan be used iffetchis unavailable.searchParamsare only available inpage.jssegments.- The
redirect()andnotFound()Next.js methods can also be used insidegenerateMetadata.
Metadata Fields
The same fields are available to the static metadata object and the object returned by generateMetadata. Fields are optional and can be combined as needed.
Configure themeColor, colorScheme, and viewport settings through viewport or generateViewport. The corresponding metadata fields are deprecated.
title
The title attribute is used to set the title of the document. It can be defined as a simple string or an optional template object.
String
export const metadata = {
title: 'Next.js',
}<title>Next.js</title>default
title.default can be used to provide a fallback title to child route segments that don't define a title.
import type { Metadata } from 'next'
export const metadata: Metadata = {
title: {
default: 'Acme',
},
}import type { Metadata } from 'next'
export const metadata: Metadata = {}
// Output: <title>Acme</title>template
title.template can be used to add a prefix or a suffix to titles defined in child route segments.
import type { Metadata } from 'next'
export const metadata: Metadata = {
title: {
template: '%s | Acme',
default: 'Acme', // a default is required when creating a template
},
}export const metadata = {
title: {
template: '%s | Acme',
default: 'Acme', // a default is required when creating a template
},
}import type { Metadata } from 'next'
export const metadata: Metadata = {
title: 'About',
}
// Output: <title>About | Acme</title>export const metadata = {
title: 'About',
}
// Output: <title>About | Acme</title>Good to know:
title.templateapplies to child route segments and not the segment it's defined in. This means:
title.defaultis required when you add atitle.template.title.templatedefined inlayout.jswill not apply to atitledefined in apage.jsof the same route segment.title.templatedefined inpage.jshas no effect because a page is always the terminating segment (it doesn't have any children route segments).title.templatehas no effect if a route has not defined atitleortitle.default.
absolute
title.absolute can be used to provide a title that ignores title.template set in parent segments.
import type { Metadata } from 'next'
export const metadata: Metadata = {
title: {
template: '%s | Acme',
},
}export const metadata = {
title: {
template: '%s | Acme',
},
}import type { Metadata } from 'next'
export const metadata: Metadata = {
title: {
absolute: 'About',
},
}
// Output: <title>About</title>export const metadata = {
title: {
absolute: 'About',
},
}
// Output: <title>About</title>Good to know:
layout.js
title(string) andtitle.defaultdefine the default title for child segments (that do not define their owntitle). It will augmenttitle.templatefrom the closest parent segment if it exists.title.absolutedefines the default title for child segments. It ignorestitle.templatefrom parent segments.title.templatedefines a new title template for child segments.page.js
- If a page does not define its own title the closest parents resolved title will be used.
title(string) defines the routes title. It will augmenttitle.templatefrom the closest parent segment if it exists.title.absolutedefines the route title. It ignorestitle.templatefrom parent segments.title.templatehas no effect inpage.jsbecause a page is always the terminating segment of a route.
description
export const metadata = {
description: 'The React Framework for the Web',
}<meta name="description" content="The React Framework for the Web" />Other fields
You can also identify the application, authors, and keywords for a page using document metadata:
export const metadata = {
generator: 'Next.js',
applicationName: 'Next.js',
referrer: 'origin-when-cross-origin',
keywords: ['Next.js', 'React', 'JavaScript'],
authors: [{ name: 'Seb' }, { name: 'Josh', url: 'https://nextjs.org' }],
creator: 'Jiachi Liu',
publisher: 'Sebastian Markbåge',
}<meta name="application-name" content="Next.js" />
<meta name="author" content="Seb" />
<link rel="author" href="https://nextjs.org" />
<meta name="author" content="Josh" />
<meta name="generator" content="Next.js" />
<meta name="keywords" content="Next.js,React,JavaScript" />
<meta name="referrer" content="origin-when-cross-origin" />
<meta name="creator" content="Jiachi Liu" />
<meta name="publisher" content="Sebastian Markbåge" />| Field | Accepted input |
|---|---|
applicationName, generator, creator, publisher | string |
authors | { name?: string, url?: string | URL } or an array of these objects |
keywords | string or string[]; arrays are joined with commas |
referrer | A supported referrer policy |
referrer accepts 'no-referrer', 'origin', 'no-referrer-when-downgrade', 'origin-when-cross-origin', 'same-origin', 'strict-origin', or 'strict-origin-when-cross-origin'.
metadataBase
metadataBase accepts an absolute URL string or a URL instance. It sets a base URL prefix for metadata fields that require a fully qualified URL.
metadataBaseallows URL-basedmetadatafields defined in the current route segment and below to use a relative path instead of an otherwise required absolute URL.- The field's relative path will be composed with
metadataBaseto form a fully qualified URL.
export const metadata = {
metadataBase: new URL('https://acme.com'),
alternates: {
canonical: '/',
languages: {
'en-US': '/en-US',
'de-DE': '/de-DE',
},
},
openGraph: {
images: '/og-image.png',
},
}<link rel="canonical" href="https://acme.com" />
<link rel="alternate" hreflang="en-US" href="https://acme.com/en-US" />
<link rel="alternate" hreflang="de-DE" href="https://acme.com/de-DE" />
<meta property="og:image" content="https://acme.com/og-image.png" />Good to know:
metadataBaseis typically set in rootapp/layout.jsto apply to URL-basedmetadatafields across all routes.- When
generateMetadatauses'use cache', its return value must be serializable.URLinstances are not supported by Cache Functions, so values such asmetadataBaseshould be returned as strings (for example,url.toString()). Seeuse cacheserialization requirements.metadataBasecan contain a subdomain e.g.https://app.acme.comor base path e.g.https://acme.com/start/from/here- If a
metadatafield provides an absolute URL,metadataBasewill be ignored.- Set
metadataBaseexplicitly when using relative URLs. Without it, social images use a fallback origin and can produce a warning; other URL fields can remain relative.- Next.js will normalize duplicate slashes between
metadataBase(e.g.https://acme.com/) and a relative field (e.g./path) to a single slash (e.g.https://acme.com/path)
URL Composition
URL composition favors developer intent over default directory traversal semantics.
- Trailing slashes between
metadataBaseandmetadatafields are normalized. - An "absolute" path in a
metadatafield (that typically would replace the whole URL path) is treated as a "relative" path (starting from the end ofmetadataBase).
For example, given the following metadataBase:
import type { Metadata } from 'next'
export const metadata: Metadata = {
metadataBase: new URL('https://acme.com'),
}export const metadata = {
metadataBase: new URL('https://acme.com'),
}Any metadata fields that inherit the above metadataBase and set their own value will be resolved as follows:
metadata field | Resolved URL |
|---|---|
/ | https://acme.com |
./ | https://acme.com |
payments | https://acme.com/payments |
/payments | https://acme.com/payments |
./payments | https://acme.com/payments |
../payments | https://acme.com/payments |
https://beta.acme.com/payments | https://beta.acme.com/payments |
formatDetection
formatDetection accepts boolean telephone, date, address, email, and url fields. Set a field to false to add its key=no directive; true and omitted fields add no directive. See Apple's format-detection reference for telephone detection behavior.
export const metadata = {
formatDetection: {
email: false,
address: false,
telephone: false,
},
}<meta name="format-detection" content="telephone=no, address=no, email=no" />openGraph
openGraph configures Open Graph metadata for a page. Image URLs can be absolute, or relative when metadataBase is set. Use absolute URLs for audio and video.
export const metadata = {
openGraph: {
title: 'Next.js',
description: 'The React Framework for the Web',
url: 'https://nextjs.org',
type: 'website',
images: [{ url: 'https://nextjs.org/og.png', width: 800, height: 600 }],
},
}<meta property="og:title" content="Next.js" />
<meta property="og:description" content="The React Framework for the Web" />
<meta property="og:url" content="https://nextjs.org" />
<meta property="og:type" content="website" />
<meta property="og:image" content="https://nextjs.org/og.png" />
<meta property="og:image:width" content="800" />
<meta property="og:image:height" content="600" />Open Graph fields
All Open Graph types accept these fields. See the Open Graph protocol for property meanings and requirements.
| Field | Accepted input |
|---|---|
title | string or a title object |
description, siteName, locale, countryName | string |
url | string or URL |
alternateLocale, emails, phoneNumbers, faxNumbers | string or string[] |
determiner | 'a', 'an', 'the', 'auto', or '' (omits the tag) |
ttl | number |
images, audio, videos | URL string, URL, media descriptor, or an array of these values |
Open Graph media descriptors
Media descriptors accept a required url and optional structured properties:
| Field | Type | Applies to |
|---|---|---|
url, secureUrl | string or URL | Images, audio, video |
type | string | Images, audio, video |
width, height | string or number | Images, video |
alt | string | Images |
Relative image URLs are resolved with metadataBase. Use absolute URLs for audio and video.
Open Graph types
Set type to add fields for an Open Graph object type. For example:
export const metadata = {
openGraph: {
type: 'article',
publishedTime: '2026-01-01T00:00:00.000Z',
authors: ['https://example.com/authors/ada'],
},
}<meta property="og:type" content="article" />
<meta property="article:published_time" content="2026-01-01T00:00:00.000Z" />
<meta property="article:author" content="https://example.com/authors/ada" />Good to know: Use the file-based Metadata API to generate Open Graph image metadata from image files.
The following table lists the fields Next.js supports for each type. All types also accept the common Open Graph fields.
type | Additional fields |
|---|---|
'website' | None |
'article' | publishedTime, modifiedTime, expirationTime, authors, section, tags |
'book' | isbn, releaseDate, authors, tags |
'profile' | firstName, lastName, username, gender |
'music.song' | duration, albums, musicians |
'music.album' | songs, musicians, releaseDate |
'music.playlist' | songs, creators |
'music.radio_station' | creators |
'video.movie' | actors, directors, writers, duration, releaseDate, tags |
'video.episode' | actors, directors, writers, duration, releaseDate, tags, series |
'video.tv_show' | None |
'video.other' | None |
| Type-specific field | Accepted input |
|---|---|
publishedTime, modifiedTime, expirationTime, releaseDate | Date/time string |
isbn, section, firstName, lastName, username, gender | string |
duration | number |
tags | string or string[] |
authors, musicians, creators, directors, writers | string, URL, or an array of either |
series | string or URL |
albums, songs | string, URL, { url: string | URL, disc?: number, track?: number }, or an array of these values |
actors | string, URL, { url: string | URL, role?: string }, or an array of these values |
Next.js maps camel-cased field names to protocol properties, such as modifiedTime to article:modified_time.
robots
robots sets crawler directives for the page. Use googleBot to provide separate directives for Googlebot:
import type { Metadata } from 'next'
export const metadata: Metadata = {
robots: {
index: true,
follow: true,
nocache: false,
googleBot: {
index: true,
follow: true,
noimageindex: false,
'max-video-preview': -1,
'max-image-preview': 'large',
'max-snippet': -1,
},
},
}<meta name="robots" content="index, follow" />
<meta
name="googlebot"
content="index, follow, max-video-preview:-1, max-image-preview:large, max-snippet:-1"
/>Robots fields
Both robots and googleBot accept a directive string or an object. Their object fields are listed below. Only the robots object accepts a googleBot field.
| Field | Accepted input |
|---|---|
index, follow | boolean |
noarchive, nosnippet, noimageindex, nocache, notranslate, indexifembedded, nositelinkssearchbox | boolean |
unavailable_after | string |
'max-video-preview' | number or string |
'max-image-preview' | 'none', 'standard', or 'large' |
'max-snippet' | number |
googleBot | string or a crawler directive object |
For index and follow, false emits noindex and nofollow. Other boolean fields emit their directive only when true. The deprecated object keys noindex and nofollow are not accepted boolean options.
See Google's robots meta tag reference for directive meanings and Googlebot support. Next.js emits the configured tags; each crawler determines which directives it honors.
icons
icons adds icon links, grouped by category:
export const metadata = {
icons: {
icon: [
{ url: '/icon.png' },
{ url: '/icon-dark.png', media: '(prefers-color-scheme: dark)' },
],
shortcut: '/shortcut-icon.png',
apple: '/apple-icon.png',
other: { rel: 'mask-icon', url: '/mask-icon.svg', color: '#000000' },
},
}<link rel="shortcut icon" href="/shortcut-icon.png" />
<link rel="icon" href="/icon.png" />
<link rel="icon" href="/icon-dark.png" media="(prefers-color-scheme: dark)" />
<link rel="apple-touch-icon" href="/apple-icon.png" />
<link rel="mask-icon" href="/mask-icon.svg" color="#000000" />Good to know: Use the file-based Metadata API to generate icon metadata from image files.
Icon categories and descriptors
icons accepts a URL string, URL instance, array of URLs/descriptors, or category object. Each category accepts a single item or an array; other accepts descriptors only.
| Category | Default rel |
|---|---|
icon | icon |
shortcut | shortcut icon |
apple | apple-touch-icon |
other | icon |
Only a descriptor's url is required. An explicit rel overrides the category default. See the <link> reference for attribute meanings.
| Descriptor field | Type |
|---|---|
url | string or URL |
type, sizes, color, rel, media | string |
fetchPriority | 'high', 'low', or 'auto' |
themeColor
Deprecated: The
themeColoroption inmetadatais deprecated as of Next.js 14. Please use theviewportconfiguration instead.
colorScheme
Deprecated: The
colorSchemeoption inmetadatais deprecated as of Next.js 14. Please use theviewportconfiguration instead.
manifest
manifest links to a web app manifest. It accepts a URL string or a URL instance.
export const metadata = {
manifest: 'https://nextjs.org/manifest.json',
}<link rel="manifest" href="https://nextjs.org/manifest.json" />twitter
twitter configures Twitter Card metadata. Image URLs can be absolute, or relative when metadataBase is set.
Set card to choose the card type. For example, use 'summary_large_image' for a card with a large image:
export const metadata = {
twitter: {
card: 'summary_large_image',
title: 'Next.js',
description: 'The React Framework for the Web',
siteId: '1467726470533754880',
creator: '@nextjs',
creatorId: '1467726470533754880',
images: ['https://nextjs.org/og.png'],
},
}<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site:id" content="1467726470533754880" />
<meta name="twitter:creator" content="@nextjs" />
<meta name="twitter:creator:id" content="1467726470533754880" />
<meta name="twitter:title" content="Next.js" />
<meta name="twitter:description" content="The React Framework for the Web" />
<meta name="twitter:image" content="https://nextjs.org/og.png" />Twitter fields
All card types accept these fields:
| Field | Accepted input |
|---|---|
card | 'summary', 'summary_large_image', 'player', or 'app' |
site, siteId, creator, creatorId, description | string |
title | string or a title object |
images | URL string, URL, image descriptor, or an array of these values |
If card is omitted, the resolver uses 'summary_large_image' when the supplied images resolve to a non-empty list, or 'summary' otherwise. Set card explicitly when you need a specific card type.
When openGraph is configured, its title, description, and images can populate missing Twitter fields. When an openGraph or twitter object is configured, missing social titles and descriptions can also inherit the document's title and description.
Player cards
For card: 'player', provide the media player URL, stream URL, and dimensions in players. Use an array of these objects for multiple players:
import type { Metadata } from 'next'
export const metadata: Metadata = {
twitter: {
card: 'player',
players: {
playerUrl: 'https://example.com/player',
streamUrl: 'https://example.com/video.mp4',
width: 1280,
height: 720,
},
},
}export const metadata = {
twitter: {
card: 'player',
players: {
playerUrl: 'https://example.com/player',
streamUrl: 'https://example.com/video.mp4',
width: 1280,
height: 720,
},
},
}All four player fields are required. playerUrl and streamUrl accept absolute URL strings or URL instances; width and height are numbers.
App cards
For card: 'app', provide an app object. The id and url maps accept optional iphone, ipad, and googleplay keys:
export const metadata = {
twitter: {
card: 'app',
app: {
name: 'Example App',
id: {
iphone: '123456789',
ipad: '123456789',
googleplay: 'com.example.app',
},
url: { iphone: 'https://example.com/app' },
},
},
}| Field | Accepted input |
|---|---|
id | Required map. iPhone/iPad IDs accept strings or numbers; Google Play IDs accept strings. |
url | Optional map of absolute URL strings or URL instances |
name | Optional string, shared by all platforms |
Twitter image descriptors
Twitter image descriptors use the same fields as Open Graph image descriptors: required url and optional alt, secureUrl, type, width, and height.
viewport
Deprecated: The
viewportoption inmetadatais deprecated as of Next.js 14. Please use theviewportconfiguration instead.
verification
verification supports google, yahoo, yandex, and me. Each accepts a string, a number, or an array of strings/numbers. Use other to map additional meta names to the same value forms.
export const metadata = {
verification: {
google: 'google',
yandex: 'yandex',
yahoo: 'yahoo',
me: ['my-email', 'my-link'],
other: {
'custom-verification': 'custom-token',
},
},
}<meta name="google-site-verification" content="google" />
<meta name="y_key" content="yahoo" />
<meta name="yandex-verification" content="yandex" />
<meta name="me" content="my-email" />
<meta name="me" content="my-link" />
<meta name="custom-verification" content="custom-token" />appleWebApp
appleWebApp configures web app metadata such as the title, startup images, and status bar style. See Apple's Safari metadata reference for platform-specific behavior:
export const metadata = {
appleWebApp: {
title: 'Apple Web App',
statusBarStyle: 'black-translucent',
startupImage: [
'/assets/startup/apple-touch-startup-image-768x1004.png',
{
url: '/assets/startup/apple-touch-startup-image-1536x2008.png',
media: '(device-width: 768px) and (device-height: 1024px)',
},
],
},
}appleWebApp accepts true, false, or an object. true enables web app capability; false omits the Apple web app metadata. The object fields are:
| Field | Type | Default |
|---|---|---|
capable | boolean | true when an object is supplied |
title | string | None |
startupImage | URL string, { url: string, media?: string }, or an array of either | None |
statusBarStyle | 'default', 'black', or 'black-translucent' | 'default' |
itunes
Use itunes to configure an apple-itunes-app Smart App Banner:
export const metadata = {
itunes: {
appId: 'myAppStoreID',
appArgument: 'myAppArgument',
},
}<meta
name="apple-itunes-app"
content="app-id=myAppStoreID, app-argument=myAppArgument"
/>appId is a required string. The optional appArgument string is resolved using metadataBase and the current route.
alternates
alternates adds links for the canonical URL and other versions of the page, such as translations and an RSS feed:
export const metadata = {
alternates: {
canonical: { url: 'https://nextjs.org', title: 'Next.js' },
languages: {
'en-US': 'https://nextjs.org/en-US',
'de-DE': 'https://nextjs.org/de-DE',
'x-default': 'https://nextjs.org',
},
media: {
'only screen and (max-width: 600px)': 'https://nextjs.org/mobile',
},
types: {
'application/rss+xml': [
{ url: 'https://nextjs.org/rss', title: 'RSS feed' },
],
},
},
}<link rel="canonical" href="https://nextjs.org" title="Next.js" />
<link rel="alternate" hreflang="en-US" href="https://nextjs.org/en-US" />
<link rel="alternate" hreflang="de-DE" href="https://nextjs.org/de-DE" />
<link rel="alternate" hreflang="x-default" href="https://nextjs.org" />
<link
rel="alternate"
media="only screen and (max-width: 600px)"
href="https://nextjs.org/mobile"
/>
<link
rel="alternate"
type="application/rss+xml"
href="https://nextjs.org/rss"
title="RSS feed"
/>| Field | Accepted input |
|---|---|
canonical | URL string, URL, or { url: string | URL, title?: string } |
languages | Map of language codes (including 'x-default') to a URL string, URL, or descriptor array |
media | Map of media queries to a URL string, URL, or descriptor array |
types | Map of content types to a URL string, URL, or descriptor array |
Descriptors in the maps use { url: string | URL, title?: string }. An optional descriptor title adds a title attribute to the link. Use arrays to provide multiple links for the same map key.
appLinks
appLinks describes native app destinations for the page. Configure the platforms your app supports:
export const metadata = {
appLinks: {
ios: {
url: 'https://nextjs.org/ios',
app_store_id: 'app_store_id',
},
android: {
package: 'com.example.android/package',
app_name: 'app_name_android',
},
web: {
url: 'https://nextjs.org/web',
should_fallback: true,
},
},
}<meta property="al:ios:url" content="https://nextjs.org/ios" />
<meta property="al:ios:app_store_id" content="app_store_id" />
<meta property="al:android:package" content="com.example.android/package" />
<meta property="al:android:app_name" content="app_name_android" />
<meta property="al:web:url" content="https://nextjs.org/web" />
<meta property="al:web:should_fallback" content="true" />Each platform accepts one descriptor or an array of descriptors. Descriptor fields are:
| Platform | Required fields | Optional fields |
|---|---|---|
ios, iphone, ipad | url (string or URL) | app_store_id (string or number), app_name (string) |
android | package (string) | url (string or URL), class (string), app_name (string) |
windows_phone, windows, windows_universal | url (string or URL) | app_id (string), app_name (string) |
web | url (string or URL) | should_fallback (boolean) |
Each field emits al:<platform>:<field>, such as al:iphone:app_name or al:windows:app_id.
archives
archives links to a collection of records, documents, or other materials of historical interest (source). It accepts a string or an array of strings.
export const metadata = {
archives: ['https://nextjs.org/13'],
}<link rel="archives" href="https://nextjs.org/13" />assets
assets accepts a string or an array of strings.
export const metadata = {
assets: ['https://nextjs.org/assets'],
}<link rel="assets" href="https://nextjs.org/assets" />bookmarks
bookmarks accepts a string or an array of strings.
export const metadata = {
bookmarks: ['https://nextjs.org/13'],
}<link rel="bookmarks" href="https://nextjs.org/13" />pagination
pagination links to the previous and next pages in a sequence. Its previous and next fields each accept a string or URL and emit rel="prev" and rel="next" links.
export const metadata = {
pagination: {
previous: 'https://nextjs.org/blog?page=1',
next: 'https://nextjs.org/blog?page=3',
},
}<link rel="prev" href="https://nextjs.org/blog?page=1" />
<link rel="next" href="https://nextjs.org/blog?page=3" />abstract
abstract accepts a string and emits <meta name="abstract" content="..." />. Prefer description, which supersedes this field.
classification
classification accepts a string and emits <meta name="classification" content="..." />.
category
category accepts a string and emits a category meta tag.
export const metadata = {
category: 'technology',
}<meta name="category" content="technology" />facebook
facebook.appId accepts a string; facebook.admins accepts a string or string array. Supply both appId and an array of admins to emit both sets of tags. See the Facebook reference for platform requirements.
export const metadata = {
facebook: {
appId: '12345678',
admins: ['12345678', '87654321'],
},
}<meta property="fb:app_id" content="12345678" />
<meta property="fb:admins" content="12345678" />
<meta property="fb:admins" content="87654321" />pinterest
Use pinterest.richPin to enable or disable Pinterest Rich Pins. It accepts a boolean or a string and emits the pinterest-rich-pin meta tag.
export const metadata = {
pinterest: {
richPin: true,
},
}<meta property="pinterest-rich-pin" content="true" />other
Use other for custom named meta tags. Values can be strings, numbers, or arrays of either. Arrays emit multiple tags with the same name:
export const metadata = {
other: {
custom: ['meta1', 'meta2'],
},
}<meta name="custom" content="meta1" /> <meta name="custom" content="meta2" />Types
You can add type safety to your metadata by using the Metadata type. If you are using the built-in TypeScript plugin in your IDE, you do not need to manually add the type, but you can still explicitly add it if you want.
metadata object
import type { Metadata } from 'next'
export const metadata: Metadata = {
title: 'Next.js',
}generateMetadata function
Regular function
import type { Metadata } from 'next'
export function generateMetadata(): Metadata {
return {
title: 'Next.js',
}
}Async function
import type { Metadata } from 'next'
export async function generateMetadata(): Promise<Metadata> {
return {
title: 'Next.js',
}
}With segment props
import type { Metadata } from 'next'
type Props = {
params: Promise<{ id: string }>
searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}
export function generateMetadata({ params, searchParams }: Props): Metadata {
return {
title: 'Next.js',
}
}
export default function Page({ params, searchParams }: Props) {}With parent metadata
import type { Metadata, ResolvingMetadata } from 'next'
export async function generateMetadata(
{ params, searchParams }: Props,
parent: ResolvingMetadata
): Promise<Metadata> {
return {
title: 'Next.js',
}
}JavaScript Projects
For JavaScript projects, you can use JSDoc to add type safety.
/** @type {import("next").Metadata} */
export const metadata = {
title: 'Next.js',
}Unsupported Metadata
The legacy top-level keys apple-touch-fullscreen and apple-touch-icon-precomposed are deprecated and do not accept values. Use appleWebApp and icons.apple respectively. An icon descriptor's rel is a separate link attribute.
The following metadata types do not currently have built-in support. However, they can still be rendered in the layout or page itself.
| Metadata | Recommendation |
|---|---|
<meta http-equiv="..."> | Use appropriate HTTP Headers via redirect(), Proxy, Security Headers |
<base> | Render the tag in the layout or page itself. |
<noscript> | Render the tag in the layout or page itself. |
<style> | Learn more about styling in Next.js. |
<script> | Learn more about using scripts. |
<link rel="stylesheet" /> | import stylesheets directly in the layout or page itself. |
<link rel="preload" /> | Use ReactDOM preload method |
<link rel="preconnect" /> | Use ReactDOM preconnect method |
<link rel="dns-prefetch" /> | Use ReactDOM prefetchDNS method |
Resource hints
The <link> element has a number of rel keywords that can be used to hint to the browser that an external resource is likely to be needed. The browser uses this information to apply preloading optimizations depending on the keyword.
While the Metadata API doesn't directly support these hints, you can use new ReactDOM methods to safely insert them into the <head> of the document.
'use client'
import ReactDOM from 'react-dom'
export function PreloadResources() {
ReactDOM.preload('...', { as: '...' })
ReactDOM.preconnect('...', { crossOrigin: '...' })
ReactDOM.prefetchDNS('...')
return '...'
}'use client'
import ReactDOM from 'react-dom'
export function PreloadResources() {
ReactDOM.preload('...', { as: '...' })
ReactDOM.preconnect('...', { crossOrigin: '...' })
ReactDOM.prefetchDNS('...')
return '...'
}<link rel="preload">
Start loading a resource early in the page rendering (browser) lifecycle. MDN Docs.
ReactDOM.preload(href: string, options: { as: string })<link rel="preload" href="..." as="..." /><link rel="preconnect">
Preemptively initiate a connection to an origin. MDN Docs.
ReactDOM.preconnect(href: string, options?: { crossOrigin?: string })<link rel="preconnect" href="..." crossorigin /><link rel="dns-prefetch">
Attempt to resolve a domain name before resources get requested. MDN Docs.
ReactDOM.prefetchDNS(href: string)<link rel="dns-prefetch" href="..." />Good to know:
- These methods are currently only supported in Client Components, which are still Server Side Rendered on initial page load.
- Next.js in-built features such as
next/font,next/imageandnext/scriptautomatically handle relevant resource hints.
Behavior
Default Fields
There are two default meta tags that are always added even if a route doesn't define metadata:
- The meta charset tag sets the character encoding for the website.
- The meta viewport tag sets the viewport width and scale for the website to adjust for different devices.
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />Good to know: You can customize the default viewport meta tag using the
viewportobject orgenerateViewportfunction.
Streaming metadata
Streaming metadata allows Next.js to render and send the initial UI to the browser, without waiting for generateMetadata to complete.
When generateMetadata resolves, the resulting metadata tags are appended to the <body> tag. We have verified that metadata is interpreted correctly by bots that execute JavaScript and inspect the full DOM (e.g. Googlebot).
For HTML-limited bots that can’t execute JavaScript (e.g. facebookexternalhit), Next.js waits for generateMetadata before starting the response. The resulting metadata is available in the <head> tag. After generateMetadata resolves, Next.js can start the response and stream the remaining page content.
Next.js automatically detects HTML-limited bots by looking at the User Agent header. You can use the htmlLimitedBots option in your Next.js config file to override the default User Agent list.
To fully disable streaming metadata:
import type { NextConfig } from 'next'
const config: NextConfig = {
htmlLimitedBots: /.*/,
}
export default configmodule.exports = {
htmlLimitedBots: /.*/,
}Streaming metadata improves perceived performance by reducing TTFB and can help lowering LCP time.
Overriding htmlLimitedBots could lead to longer response times. Streaming metadata is an advanced feature, and the default should be sufficient for most cases.
With Cache Components
When Cache Components is enabled, generateMetadata follows the same rules as other components. If metadata accesses runtime data (cookies(), headers(), params, searchParams) or performs uncached data fetching, it defers to request time.
How Next.js handles this depends on the rest of your page:
- If other parts also defer to request time: Prerendering generates a static shell, and metadata streams in with other deferred content.
- If the page or layout is otherwise fully prerenderable: Next.js requires an explicit choice: cache the data if possible, or signal that deferred rendering is intentional.
Streaming metadata at runtime while the rest of the page is fully prerenderable is not common. To ensure this behavior is intentional, an error is raised indicating which page or layout needs to be handled.
To resolve this, you have two options. If metadata depends on external data but not runtime data, use use cache:
export async function generateMetadata() {
'use cache'
const { title, description } = await db.query('site-metadata')
return { title, description }
}If metadata genuinely requires runtime data, add a dynamic marker component to your page:
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { connection } from 'next/server'
export async function generateMetadata() {
const token = (await cookies()).get('token')?.value
// ... use token to fetch personalized metadata
return { title: 'Personalized Title' }
}
const Connection = async () => {
await connection()
return null
}
async function DynamicMarker() {
return (
<Suspense>
<Connection />
</Suspense>
)
}
export default function Page() {
// DO NOT place await connection() here
// doing so prevents the article tag content from
// being included in the static shell
return (
<>
<article>Static content</article>
<DynamicMarker />
</>
)
}The DynamicMarker component renders nothing but tells Next.js the page has intentional dynamic content. By wrapping it in Suspense, the static content still prerenders normally.
See Next.js encountered runtime data in generateMetadata() and Next.js encountered uncached data in generateMetadata() for full fix options and trade-offs.
Ordering
Metadata is evaluated in order, starting from the root segment down to the segment closest to the final page.js segment. For example:
app/layout.tsx(Root Layout)app/blog/layout.tsx(Nested Blog Layout)app/blog/[slug]/page.tsx(Blog Page)
Merging
Following the evaluation order, Metadata objects exported from multiple segments in the same route are shallowly merged together to form the final metadata output of a route. Duplicate keys are replaced based on their ordering.
This means metadata with nested fields such as openGraph and robots that are defined in an earlier segment are overwritten by the last segment to define them.
The other field is an exception: its custom tag names are merged across segments. When two segments provide the same custom tag name, the later value replaces the earlier value for that name.
Overwriting fields
export const metadata = {
title: 'Acme',
openGraph: {
title: 'Acme',
description: 'Acme is a...',
},
}export const metadata = {
title: 'Blog',
openGraph: {
title: 'Blog',
},
}
// Output:
// <title>Blog</title>
// <meta property="og:title" content="Blog" />In the example above:
titlefromapp/layout.jsis replaced bytitleinapp/blog/page.js.- All
openGraphfields fromapp/layout.jsare replaced inapp/blog/page.jsbecauseapp/blog/page.jssetsopenGraphmetadata. Note the absence ofopenGraph.description.
If you'd like to share some nested fields between segments while overwriting others, you can pull them out into a separate variable:
export const openGraphImage = { images: ['http://...'] }import { openGraphImage } from './shared-metadata'
export const metadata = {
openGraph: {
...openGraphImage,
title: 'Home',
},
}import { openGraphImage } from '../shared-metadata'
export const metadata = {
openGraph: {
...openGraphImage,
title: 'About',
},
}In the example above, the OG image is shared between app/layout.js and app/about/page.js while the titles are different.
Inheriting fields
export const metadata = {
title: 'Acme',
openGraph: {
title: 'Acme',
description: 'Acme is a...',
},
}export const metadata = {
title: 'About',
}
// Output:
// <title>About</title>
// <meta property="og:title" content="Acme" />
// <meta property="og:description" content="Acme is a..." />Notes
titlefromapp/layout.jsis replaced bytitleinapp/about/page.js.- All
openGraphfields fromapp/layout.jsare inherited inapp/about/page.jsbecauseapp/about/page.jsdoesn't setopenGraphmetadata.
Version History
| Version | Changes |
|---|---|
v15.2.0 | Introduced streaming support to generateMetadata. |
v14.0.0 | viewport, themeColor, and colorScheme deprecated in favor of the viewport configuration. |
v13.2.0 | metadata and generateMetadata introduced. |
Next Steps
View all the Metadata API options.