---
title: generateMetadata
description: Learn how to add Metadata to your Next.js application for improved search engine optimization (SEO) and web shareability.
url: "https://nextjs.org/docs/app/api-reference/functions/generate-metadata"
docs_index: /docs/llms.txt
lastUpdated: 2026-11-12
prerequisites:
  - "API Reference: /docs/app/api-reference"
  - "Functions: /docs/app/api-reference/functions"
related:
  - /docs/app/api-reference/file-conventions/metadata
  - /docs/app/api-reference/functions/generate-viewport
  - /docs/app/getting-started/caching
  - /docs/app/api-reference/config/next-config-js/cacheComponents
---

> For an index of all documentation, see [/docs/llms.txt](/docs/llms.txt).

You can use the `metadata` object or the `generateMetadata` function to define metadata.

## The `metadata` object

To define static metadata, export a [`Metadata` object](#metadata-fields) from a `layout.js` or `page.js` file.

**TypeScript**

```tsx title="layout.tsx | page.tsx" 
import type { Metadata } from 'next'

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

export default function Page() {}
```

**JavaScript**

```jsx title="layout.js | page.js" 
export const metadata = {
  title: '...',
  description: '...',
}

export default function Page() {}
```

> See the [Metadata Fields](#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](#metadata-fields).

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](/docs/app/api-reference/functions/generate-metadata#streaming-metadata) after sending the initial UI.

**TypeScript**

```tsx title="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) {}
```

**JavaScript**

```jsx title="app/products/[id]/page.js" 
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'>`](/docs/app/api-reference/file-conventions/page#page-props-helper) or [`LayoutProps<'/route'>`](/docs/app/api-reference/file-conventions/layout#layout-props-helper) 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](/docs/app/glossary#memoization) for the same data across `generateMetadata`, `generateStaticParams`, Layouts, Pages, and Server Components.
> - React [`cache` can be used](https://react.dev/reference/react/cache) if `fetch` is unavailable.
> - A page's explicit `openGraph.images` or `twitter.images` property from `metadata` or `generateMetadata` overrides the corresponding [file-based images](/docs/app/api-reference/file-conventions/metadata/opengraph-image#precedence-with-metadata-exports) 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:

**TypeScript**

```tsx title="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 />
}
```

```tsx title="app/interactive-component.tsx" 
'use client'

export function InteractiveComponent() {
  // Client-side interactivity (hooks, event handlers, etc.)
}
```

**JavaScript**

```jsx title="app/page.js" 
import { InteractiveComponent } from './interactive-component'

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

export default function Page() {
  return <InteractiveComponent />
}
```

```jsx title="app/interactive-component.js" 
'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](/docs/app/api-reference/file-conventions/dynamic-routes) object from the root segment down to the segment `generateMetadata` is called from. Examples:

    | Route                           | URL         | `params`                  |
    | ------------------------------- | ----------- | ------------------------- |
    | `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](https://developer.mozilla.org/docs/Learn/Common_questions/What_is_a_URL#parameters). 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](#metadata-fields) 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](#the-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](https://react.dev/reference/react/cache) if `fetch` is unavailable.
> - `searchParams` are only available in `page.js` segments.
> - The [`redirect()`](/docs/app/api-reference/functions/redirect) and [`notFound()`](/docs/app/api-reference/functions/not-found) 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](/docs/app/api-reference/functions/generate-viewport) 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](#string) or an optional [template object](#template).

#### String

```jsx title="layout.js | page.js"
export const metadata = {
  title: 'Next.js',
}
```

```html title="<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`.

```tsx title="app/layout.tsx"
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    default: 'Acme',
  },
}
```

```tsx title="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.

**TypeScript**

```tsx title="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
  },
}
```

```tsx title="app/about/page.tsx" 
import type { Metadata } from 'next'

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

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

**JavaScript**

```jsx title="app/layout.js" 
export const metadata = {
  title: {
    template: '%s | Acme',
    default: 'Acme', // a default is required when creating a template
  },
}
```

```jsx title="app/about/page.js" 
export const 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.

**TypeScript**

```tsx title="app/layout.tsx" 
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    template: '%s | Acme',
  },
}
```

```tsx title="app/about/page.tsx" 
import type { Metadata } from 'next'

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

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

**JavaScript**

```jsx title="app/layout.js" 
export const metadata = {
  title: {
    template: '%s | Acme',
  },
}
```

```jsx title="app/about/page.js" 
export const 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`

```jsx title="layout.js | page.js"
export const metadata = {
  description: 'The React Framework for the Web',
}
```

```html title="<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](https://html.spec.whatwg.org/multipage/semantics.html#standard-metadata-names):

```jsx title="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',
}
```

```html title="<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" />
```

| 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](https://developer.mozilla.org/docs/Web/HTML/Reference/Elements/meta/name/referrer) |

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

```jsx title="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',
  },
}
```

```html title="<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](/docs/app/api-reference/directives/use-cache#serialization).
> - `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`:

**TypeScript**

```tsx title="app/layout.tsx" 
import type { Metadata } from 'next'

export const metadata: Metadata = {
  metadataBase: new URL('https://acme.com'),
}
```

**JavaScript**

```jsx title="app/layout.js" 
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](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html) for telephone detection behavior.

```jsx title="layout.js | page.js"
export const metadata = {
  formatDetection: {
    email: false,
    address: false,
    telephone: false,
  },
}
```

```html title="<head> output"
<meta name="format-detection" content="telephone=no, address=no, email=no" />
```

### `openGraph`

`openGraph` configures [Open Graph metadata](https://ogp.me/) for a page. Image URLs can be absolute, or relative when [`metadataBase`](#metadatabase) is set. Use absolute URLs for audio and video.

```jsx title="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 }],
  },
}
```

```html title="<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](https://ogp.me/#metadata) for property meanings and requirements.

| Field                                                     | Accepted input                                                   |
| --------------------------------------------------------- | ---------------------------------------------------------------- |
| `title`                                                   | `string` or a [title object](#title)                             |
| `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](https://ogp.me/#structured):

| 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`](#metadatabase). Use absolute URLs for audio and video.

#### Open Graph types

Set `type` to add fields for an [Open Graph object type](https://ogp.me/#types). For example:

```jsx title="layout.js | page.js"
export const metadata = {
  openGraph: {
    type: 'article',
    publishedTime: '2026-01-01T00:00:00.000Z',
    authors: ['https://example.com/authors/ada'],
  },
}
```

```html title="<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](/docs/app/api-reference/file-conventions/metadata/opengraph-image#image-files-jpg-png-gif) 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](#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:

```tsx title="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,
    },
  },
}
```

```html title="<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.

| 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](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) 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:

```jsx title="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' },
  },
}
```

```html title="<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](/docs/app/api-reference/file-conventions/metadata/app-icons#image-files-ico-jpg-png) 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](https://developer.mozilla.org/docs/Web/HTML/Reference/Elements/link#attributes) for attribute meanings.

| Descriptor field                         | Type                           |
| ---------------------------------------- | ------------------------------ |
| `url`                                    | `string` or `URL`              |
| `type`, `sizes`, `color`, `rel`, `media` | `string`                       |
| `fetchPriority`                          | `'high'`, `'low'`, or `'auto'` |

### `themeColor`

> **Deprecated:**
>
> The `themeColor` option in `metadata` is deprecated as of Next.js 14. Please use the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport) instead.

### `colorScheme`

> **Deprecated:**
>
> The `colorScheme` option in `metadata` is deprecated as of Next.js 14. Please use the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport) instead.

### `manifest`

`manifest` links to a [web app manifest](https://developer.mozilla.org/docs/Web/Manifest). It accepts a URL string or a `URL` instance.

```jsx title="layout.js | page.js"
export const metadata = {
  manifest: 'https://nextjs.org/manifest.json',
}
```

```html title="<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`](#metadatabase) is set.

Set `card` to choose the card type. For example, use `'summary_large_image'` for a card with a large image:

```jsx title="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'],
  },
}
```

```html title="<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:

| Field                                                   | Accepted input                                                                                 |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `card`                                                  | `'summary'`, `'summary_large_image'`, `'player'`, or `'app'`                                   |
| `site`, `siteId`, `creator`, `creatorId`, `description` | `string`                                                                                       |
| `title`                                                 | `string` or a [title object](#title)                                                           |
| `images`                                                | URL string, `URL`, [image descriptor](#twitter-image-descriptors), 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:

**TypeScript**

```tsx title="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,
    },
  },
}
```

**JavaScript**

```jsx title="app/layout.jsx | app/page.jsx" 
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:

```jsx title="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' },
    },
  },
}
```

| 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](#open-graph-media-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](/docs/app/api-reference/functions/generate-viewport) 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.

```jsx title="layout.js | page.js"
export const metadata = {
  verification: {
    google: 'google',
    yandex: 'yandex',
    yahoo: 'yahoo',
    me: ['my-email', 'my-link'],
    other: {
      'custom-verification': 'custom-token',
    },
  },
}
```

```html title="<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](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html) for platform-specific behavior:

```jsx title="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:

| 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](https://developer.apple.com/documentation/webkit/promoting-apps-with-smart-app-banners):

```jsx title="layout.js | page.js"
export const metadata = {
  itunes: {
    appId: 'myAppStoreID',
    appArgument: 'myAppArgument',
  },
}
```

```html title="<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`](#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:

```jsx title="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' },
      ],
    },
  },
}
```

```html title="<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"
/>
```

| 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:

```jsx title="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,
    },
  },
}
```

```html title="<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:

| 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](https://www.w3.org/TR/2011/WD-html5-20110113/links.html#rel-archives)). It accepts a string or an array of strings.

```jsx title="layout.js | page.js"
export const metadata = {
  archives: ['https://nextjs.org/13'],
}
```

```html title="<head> output"
<link rel="archives" href="https://nextjs.org/13" />
```

### `assets`

`assets` accepts a string or an array of strings.

```jsx title="layout.js | page.js"
export const metadata = {
  assets: ['https://nextjs.org/assets'],
}
```

```html title="<head> output"
<link rel="assets" href="https://nextjs.org/assets" />
```

### `bookmarks`

`bookmarks` accepts a string or an array of strings.

```jsx title="layout.js | page.js"
export const metadata = {
  bookmarks: ['https://nextjs.org/13'],
}
```

```html title="<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.

```jsx title="layout.js | page.js"
export const metadata = {
  pagination: {
    previous: 'https://nextjs.org/blog?page=1',
    next: 'https://nextjs.org/blog?page=3',
  },
}
```

```html title="<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`](#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.

```jsx title="layout.js | page.js"
export const metadata = {
  category: 'technology',
}
```

```html title="<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](https://developers.facebook.com/docs/plugins/comments/#moderation-setup-instructions) for platform requirements.

```jsx title="layout.js | page.js"
export const metadata = {
  facebook: {
    appId: '12345678',
    admins: ['12345678', '87654321'],
  },
}
```

```html title="<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](https://developers.pinterest.com/docs/web-features/rich-pins-overview/). It accepts a boolean or a string and emits the `pinterest-rich-pin` meta tag.

```jsx title="layout.js | page.js"
export const metadata = {
  pinterest: {
    richPin: true,
  },
}
```

```html title="<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:

```jsx title="layout.js | page.js"
export const metadata = {
  other: {
    custom: ['meta1', 'meta2'],
  },
}
```

```html title="<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](/docs/app/api-reference/config/typescript) in your IDE, you do not need to manually add the type, but you can still explicitly add it if you want.

### `metadata` object

```tsx title="layout.tsx | page.tsx"
import type { Metadata } from 'next'

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

### `generateMetadata` function

#### Regular function

```tsx title="layout.tsx | page.tsx"
import type { Metadata } from 'next'

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

#### Async function

```tsx title="layout.tsx | page.tsx"
import type { Metadata } from 'next'

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

#### With segment props

```tsx title="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

```tsx title="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.

```js title="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.

| Metadata                      | Recommendation                                                                                                                                                                                                                               |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<meta http-equiv="...">`     | Use appropriate HTTP Headers via [`redirect()`](/docs/app/api-reference/functions/redirect), [Proxy](/docs/app/api-reference/file-conventions/proxy#nextresponse), [Security Headers](/docs/app/api-reference/config/next-config-js/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](/docs/app/getting-started/css).                                                                                                                                                                        |
| `<script>`                    | Learn more about [using scripts](/docs/app/guides/scripts).                                                                                                                                                                                  |
| `<link rel="stylesheet" />`   | `import` stylesheets directly in the layout or page itself.                                                                                                                                                                                  |
| `<link rel="preload" />`      | Use [ReactDOM preload method](#link-relpreload)                                                                                                                                                                                              |
| `<link rel="preconnect" />`   | Use [ReactDOM preconnect method](#link-relpreconnect)                                                                                                                                                                                        |
| `<link rel="dns-prefetch" />` | Use [ReactDOM prefetchDNS method](#link-reldns-prefetch)                                                                                                                                                                                     |

## 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](https://github.com/facebook/react/pull/26237) to safely insert them into the `<head>` of the document.

**TypeScript**

```tsx title="app/preload-resources.tsx" 
'use client'

import ReactDOM from 'react-dom'

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

  return '...'
}
```

**JavaScript**

```jsx title="app/preload-resources.js" 
'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](https://developer.mozilla.org/docs/Web/HTML/Attributes/rel/preload).

```tsx
ReactDOM.preload(href: string, options: { as: string })
```

```html title="<head> output"
<link rel="preload" href="..." as="..." />
```

### `<link rel="preconnect">`

Preemptively initiate a connection to an origin. [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Attributes/rel/preconnect).

```tsx
ReactDOM.preconnect(href: string, options?: { crossOrigin?: string })
```

```html title="<head> output"
<link rel="preconnect" href="..." crossorigin />
```

### `<link rel="dns-prefetch">`

Attempt to resolve a domain name before resources get requested. [MDN Docs](https://developer.mozilla.org/docs/Web/HTML/Attributes/rel/dns-prefetch).

```tsx
ReactDOM.prefetchDNS(href: string)
```

```html title="<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](https://developer.mozilla.org/docs/Web/HTML/Element/meta#attr-charset) sets the character encoding for the website.
- The [meta viewport tag](https://developer.mozilla.org/docs/Web/HTML/Viewport_meta_tag) sets the viewport width and scale for the website to adjust for different devices.

```html
<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](/docs/app/api-reference/functions/generate-viewport).

### 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`](/docs/app/api-reference/config/next-config-js/htmlLimitedBots) option in your Next.js config file to override the default [User Agent list](https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/html-bots.ts).

To fully disable streaming metadata:

**TypeScript**

```ts title="next.config.ts" 
import type { NextConfig } from 'next'

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

export default config
```

**JavaScript**

```js title="next.config.js" 
module.exports = {
  htmlLimitedBots: /.*/,
}
```

Streaming metadata improves perceived performance by reducing [TTFB](https://developer.mozilla.org/docs/Glossary/Time_to_first_byte) and can help lowering [LCP](https://developer.mozilla.org/docs/Glossary/Largest_contentful_paint) 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](/docs/app/getting-started/caching) 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`:

```tsx highlight={2} title="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:

```tsx highlight={11-14,19,31} title="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()`](/docs/messages/blocking-prerender-metadata-runtime) and [Next.js encountered uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic) 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](#ordering), 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`](/docs/app/api-reference/functions/generate-metadata#opengraph) and [`robots`](/docs/app/api-reference/functions/generate-metadata#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

```jsx title="app/layout.js"
export const metadata = {
  title: 'Acme',
  openGraph: {
    title: 'Acme',
    description: 'Acme is a...',
  },
}
```

```jsx title="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:

```jsx title="app/shared-metadata.js"
export const openGraphImage = { images: ['http://...'] }
```

```jsx title="app/page.js"
import { openGraphImage } from './shared-metadata'

export const metadata = {
  openGraph: {
    ...openGraphImage,
    title: 'Home',
  },
}
```

```jsx title="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

```jsx title="app/layout.js"
export const metadata = {
  title: 'Acme',
  openGraph: {
    title: 'Acme',
    description: 'Acme is a...',
  },
}
```

```jsx title="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

| Version   | Changes                                                                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v15.2.0` | Introduced streaming support to `generateMetadata`.                                                                                                     |
| `v14.0.0` | `viewport`, `themeColor`, and `colorScheme` deprecated in favor of the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport). |
| `v13.2.0` | `metadata` and `generateMetadata` introduced.                                                                                                           |

## Next Steps

View all the Metadata API options.

- [Metadata Files](/docs/app/api-reference/file-conventions/metadata): API documentation for the metadata file conventions.
- [generateViewport](/docs/app/api-reference/functions/generate-viewport): API Reference for the generateViewport function.
- [Caching](/docs/app/getting-started/caching): Learn how to cache data and UI in Next.js
- [cacheComponents](/docs/app/api-reference/config/next-config-js/cacheComponents): Learn how to enable the cacheComponents flag in Next.js.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/docs/llms.txt](/docs/llms.txt)