Pular para o conteúdo
Documentação do Next.js PT-BR
Esta página ainda está em inglês. A tradução ainda não foi feita; o conteúdo abaixo é o original de nextjs.org.

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.

layout.tsx | page.tsx
import type { Metadata } from 'next'

export const metadata: 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.

app/products/[id]/page.tsx
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) {}

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.js and page.js files.
  • Next.js will automatically resolve the metadata, and create the relevant <head> tags for the page.
  • The metadata object and generateMetadata function exports are only supported in Server Components.
  • You cannot export both the metadata object and generateMetadata function from the same route segment.
  • fetch requests inside generateMetadata are automatically memoized for the same data across generateMetadata, generateStaticParams, Layouts, Pages, and Server Components.
  • React cache can be used if fetch is unavailable.
  • A page's explicit openGraph.images or twitter.images property from metadata or generateMetadata overrides 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:

app/page.tsx
import type { Metadata } from 'next'
import { InteractiveComponent } from './interactive-component'

export const metadata: Metadata = {
  title: 'My Page',
}

export default function Page() {
  return <InteractiveComponent />
}
app/interactive-component.tsx
'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 segment generateMetadata is called from. Examples:

      RouteURLparams
      app/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:

      URLsearchParams
      /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 metadata object rather than generateMetadata.
  • fetch requests are automatically memoized for the same data across generateMetadata, generateStaticParams, Layouts, Pages, and Server Components. React cache can be used if fetch is unavailable.
  • searchParams are only available in page.js segments.
  • The redirect() and notFound() Next.js methods can also be used inside generateMetadata.

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

layout.js | page.js
export const metadata = {
  title: 'Next.js',
}
<head> output
<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.

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

export const metadata: Metadata = {
  title: {
    default: 'Acme',
  },
}
app/about/page.tsx
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.

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

export const metadata: Metadata = {
  title: {
    template: '%s | Acme',
    default: 'Acme', // a default is required when creating a template
  },
}
app/about/page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'About',
}

// Output: <title>About | Acme</title>

Good to know:

  • title.template applies to child route segments and not the segment it's defined in. This means:
    • title.default is required when you add a title.template.
    • title.template defined in layout.js will not apply to a title defined in a page.js of the same route segment.
    • title.template defined in page.js has no effect because a page is always the terminating segment (it doesn't have any children route segments).
  • title.template has no effect if a route has not defined a title or title.default.

absolute

title.absolute can be used to provide a title that ignores title.template set in parent segments.

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

export const metadata: Metadata = {
  title: {
    template: '%s | Acme',
  },
}
app/about/page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    absolute: 'About',
  },
}

// Output: <title>About</title>

Good to know:

  • layout.js
    • title (string) and title.default define the default title for child segments (that do not define their own title). It will augment title.template from the closest parent segment if it exists.
    • title.absolute defines the default title for child segments. It ignores title.template from parent segments.
    • title.template defines 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 augment title.template from the closest parent segment if it exists.
    • title.absolute defines the route title. It ignores title.template from parent segments.
    • title.template has no effect in page.js because a page is always the terminating segment of a route.

description

layout.js | page.js
export const metadata = {
  description: 'The React Framework for the Web',
}
<head> output
<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:

layout.js | page.js
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',
}
<head> output
<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" />
FieldAccepted input
applicationName, generator, creator, publisherstring
authors{ name?: string, url?: string | URL } or an array of these objects
keywordsstring or string[]; arrays are joined with commas
referrerA 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.

  • metadataBase allows URL-based metadata fields 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 metadataBase to form a fully qualified URL.
layout.js | page.js
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',
  },
}
<head> output
<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:

  • metadataBase is typically set in root app/layout.js to apply to URL-based metadata fields across all routes.
  • When generateMetadata uses 'use cache', its return value must be serializable. URL instances are not supported by Cache Functions, so values such as metadataBase should be returned as strings (for example, url.toString()). See use cache serialization requirements.
  • metadataBase can contain a subdomain e.g. https://app.acme.com or base path e.g. https://acme.com/start/from/here
  • If a metadata field provides an absolute URL, metadataBase will be ignored.
  • Set metadataBase explicitly 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 metadataBase and metadata fields are normalized.
  • An "absolute" path in a metadata field (that typically would replace the whole URL path) is treated as a "relative" path (starting from the end of metadataBase).

For example, given the following metadataBase:

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

export const metadata: 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 fieldResolved URL
/https://acme.com
./https://acme.com
paymentshttps://acme.com/payments
/paymentshttps://acme.com/payments
./paymentshttps://acme.com/payments
../paymentshttps://acme.com/payments
https://beta.acme.com/paymentshttps://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.

layout.js | page.js
export const metadata = {
  formatDetection: {
    email: false,
    address: false,
    telephone: false,
  },
}
<head> output
<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.

layout.js | page.js
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 }],
  },
}
<head> output
<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.

FieldAccepted input
titlestring or a title object
description, siteName, locale, countryNamestring
urlstring or URL
alternateLocale, emails, phoneNumbers, faxNumbersstring or string[]
determiner'a', 'an', 'the', 'auto', or '' (omits the tag)
ttlnumber
images, audio, videosURL string, URL, media descriptor, or an array of these values

Open Graph media descriptors

Media descriptors accept a required url and optional structured properties:

FieldTypeApplies to
url, secureUrlstring or URLImages, audio, video
typestringImages, audio, video
width, heightstring or numberImages, video
altstringImages

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:

layout.js | page.js
export const metadata = {
  openGraph: {
    type: 'article',
    publishedTime: '2026-01-01T00:00:00.000Z',
    authors: ['https://example.com/authors/ada'],
  },
}
<head> output
<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.

typeAdditional 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 fieldAccepted input
publishedTime, modifiedTime, expirationTime, releaseDateDate/time string
isbn, section, firstName, lastName, username, genderstring
durationnumber
tagsstring or string[]
authors, musicians, creators, directors, writersstring, URL, or an array of either
seriesstring or URL
albums, songsstring, URL, { url: string | URL, disc?: number, track?: number }, or an array of these values
actorsstring, 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:

layout.tsx | page.tsx
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,
    },
  },
}
<head> output
<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.

FieldAccepted input
index, followboolean
noarchive, nosnippet, noimageindex, nocache, notranslate, indexifembedded, nositelinkssearchboxboolean
unavailable_afterstring
'max-video-preview'number or string
'max-image-preview''none', 'standard', or 'large'
'max-snippet'number
googleBotstring 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:

layout.js | page.js
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' },
  },
}
<head> output
<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.

CategoryDefault rel
iconicon
shortcutshortcut icon
appleapple-touch-icon
othericon

Only a descriptor's url is required. An explicit rel overrides the category default. See the <link> reference for attribute meanings.

Descriptor fieldType
urlstring or URL
type, sizes, color, rel, mediastring
fetchPriority'high', 'low', or 'auto'

themeColor

Deprecated: The themeColor option in metadata is deprecated as of Next.js 14. Please use the viewport configuration instead.

colorScheme

Deprecated: The colorScheme option in metadata is deprecated as of Next.js 14. Please use the viewport configuration instead.

manifest

manifest links to a web app manifest. It accepts a URL string or a URL instance.

layout.js | page.js
export const metadata = {
  manifest: 'https://nextjs.org/manifest.json',
}
<head> output
<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:

layout.js | page.js
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'],
  },
}
<head> output
<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:

FieldAccepted input
card'summary', 'summary_large_image', 'player', or 'app'
site, siteId, creator, creatorId, descriptionstring
titlestring or a title object
imagesURL 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:

app/layout.tsx | app/page.tsx
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,
    },
  },
}

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:

layout.js | page.js
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' },
    },
  },
}
FieldAccepted input
idRequired map. iPhone/iPad IDs accept strings or numbers; Google Play IDs accept strings.
urlOptional map of absolute URL strings or URL instances
nameOptional 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 viewport option in metadata is deprecated as of Next.js 14. Please use the viewport configuration 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.

layout.js | page.js
export const metadata = {
  verification: {
    google: 'google',
    yandex: 'yandex',
    yahoo: 'yahoo',
    me: ['my-email', 'my-link'],
    other: {
      'custom-verification': 'custom-token',
    },
  },
}
<head> output
<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:

layout.js | page.js
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:

FieldTypeDefault
capablebooleantrue when an object is supplied
titlestringNone
startupImageURL string, { url: string, media?: string }, or an array of eitherNone
statusBarStyle'default', 'black', or 'black-translucent''default'

itunes

Use itunes to configure an apple-itunes-app Smart App Banner:

layout.js | page.js
export const metadata = {
  itunes: {
    appId: 'myAppStoreID',
    appArgument: 'myAppArgument',
  },
}
<head> output
<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:

layout.js | page.js
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' },
      ],
    },
  },
}
<head> output
<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"
/>
FieldAccepted input
canonicalURL string, URL, or { url: string | URL, title?: string }
languagesMap of language codes (including 'x-default') to a URL string, URL, or descriptor array
mediaMap of media queries to a URL string, URL, or descriptor array
typesMap 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 describes native app destinations for the page. Configure the platforms your app supports:

layout.js | page.js
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,
    },
  },
}
<head> output
<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:

PlatformRequired fieldsOptional fields
ios, iphone, ipadurl (string or URL)app_store_id (string or number), app_name (string)
androidpackage (string)url (string or URL), class (string), app_name (string)
windows_phone, windows, windows_universalurl (string or URL)app_id (string), app_name (string)
weburl (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.

layout.js | page.js
export const metadata = {
  archives: ['https://nextjs.org/13'],
}
<head> output
<link rel="archives" href="https://nextjs.org/13" />

assets

assets accepts a string or an array of strings.

layout.js | page.js
export const metadata = {
  assets: ['https://nextjs.org/assets'],
}
<head> output
<link rel="assets" href="https://nextjs.org/assets" />

bookmarks

bookmarks accepts a string or an array of strings.

layout.js | page.js
export const metadata = {
  bookmarks: ['https://nextjs.org/13'],
}
<head> output
<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.

layout.js | page.js
export const metadata = {
  pagination: {
    previous: 'https://nextjs.org/blog?page=1',
    next: 'https://nextjs.org/blog?page=3',
  },
}
<head> output
<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.

layout.js | page.js
export const metadata = {
  category: 'technology',
}
<head> output
<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.

layout.js | page.js
export const metadata = {
  facebook: {
    appId: '12345678',
    admins: ['12345678', '87654321'],
  },
}
<head> output
<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.

layout.js | page.js
export const metadata = {
  pinterest: {
    richPin: true,
  },
}
<head> output
<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:

layout.js | page.js
export const metadata = {
  other: {
    custom: ['meta1', 'meta2'],
  },
}
<head> output
<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

layout.tsx | page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Next.js',
}

generateMetadata function

Regular function

layout.tsx | page.tsx
import type { Metadata } from 'next'

export function generateMetadata(): Metadata {
  return {
    title: 'Next.js',
  }
}

Async function

layout.tsx | page.tsx
import type { Metadata } from 'next'

export async function generateMetadata(): Promise<Metadata> {
  return {
    title: 'Next.js',
  }
}

With segment props

layout.tsx | page.tsx
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

layout.tsx | page.tsx
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.

layout.js | page.js
/** @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.

MetadataRecommendation
<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.

app/preload-resources.tsx
'use client'

import ReactDOM from 'react-dom'

export function PreloadResources() {
  ReactDOM.preload('...', { as: '...' })
  ReactDOM.preconnect('...', { crossOrigin: '...' })
  ReactDOM.prefetchDNS('...')

  return '...'
}

Start loading a resource early in the page rendering (browser) lifecycle. MDN Docs.

ReactDOM.preload(href: string, options: { as: string })
<head> output
<link rel="preload" href="..." as="..." />

Preemptively initiate a connection to an origin. MDN Docs.

ReactDOM.preconnect(href: string, options?: { crossOrigin?: string })
<head> output
<link rel="preconnect" href="..." crossorigin />

Attempt to resolve a domain name before resources get requested. MDN Docs.

ReactDOM.prefetchDNS(href: string)
<head> output
<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/image and next/script automatically 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 viewport object or generateViewport function.

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:

next.config.ts
import type { NextConfig } from 'next'

const config: NextConfig = {
  htmlLimitedBots: /.*/,
}

export default config

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:

app/page.tsx
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:

app/page.tsx
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:

  1. app/layout.tsx (Root Layout)
  2. app/blog/layout.tsx (Nested Blog Layout)
  3. 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

app/layout.js
export const metadata = {
  title: 'Acme',
  openGraph: {
    title: 'Acme',
    description: 'Acme is a...',
  },
}
app/blog/page.js
export const metadata = {
  title: 'Blog',
  openGraph: {
    title: 'Blog',
  },
}

// Output:
// <title>Blog</title>
// <meta property="og:title" content="Blog" />

In the example above:

  • title from app/layout.js is replaced by title in app/blog/page.js.
  • All openGraph fields from app/layout.js are replaced in app/blog/page.js because app/blog/page.js sets openGraph metadata. Note the absence of openGraph.description.

If you'd like to share some nested fields between segments while overwriting others, you can pull them out into a separate variable:

app/shared-metadata.js
export const openGraphImage = { images: ['http://...'] }
app/page.js
import { openGraphImage } from './shared-metadata'

export const metadata = {
  openGraph: {
    ...openGraphImage,
    title: 'Home',
  },
}
app/about/page.js
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

app/layout.js
export const metadata = {
  title: 'Acme',
  openGraph: {
    title: 'Acme',
    description: 'Acme is a...',
  },
}
app/about/page.js
export const metadata = {
  title: 'About',
}

// Output:
// <title>About</title>
// <meta property="og:title" content="Acme" />
// <meta property="og:description" content="Acme is a..." />

Notes

  • title from app/layout.js is replaced by title in app/about/page.js.
  • All openGraph fields from app/layout.js are inherited in app/about/page.js because app/about/page.js doesn't set openGraph metadata.

Version History

VersionChanges
v15.2.0Introduced streaming support to generateMetadata.
v14.0.0viewport, themeColor, and colorScheme deprecated in favor of the viewport configuration.
v13.2.0metadata and generateMetadata introduced.

Next Steps

View all the Metadata API options.