Skip to content

[docs] update other params type of metadata image routes #84491

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 8, 2025
Merged

[docs] update other params type of metadata image routes #84491

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
83481f5
update other docs
huozhi Oct 3, 2025
3736d10
update id type
huozhi Oct 3, 2025
13c6e5e
docs: version history top down
icyJoseph Oct 7, 2025
5909698
docs: version history where relevant
icyJoseph Oct 7, 2025
6b456c9
docs: Fix tables for input params
icyJoseph Oct 8, 2025
8ee5a2e
docs: params undefined | Promise
icyJoseph Oct 8, 2025
16f9c29
chore: generateImageMetadata still receives params as an object
icyJoseph Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 20 additions & 11 deletions docs/01-app/03-api-reference/03-file-conventions/01-metadata/app-icons.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,25 +177,33 @@ The default export function receives the following props:

#### `params` (optional)

An object containing the [dynamic route parameters](/docs/app/api-reference/file-conventions/dynamic-routes) object from the root segment down to the segment `icon` or `apple-icon` is colocated in.
A promise that resolves to an object containing the [dynamic route parameters](/docs/app/api-reference/file-conventions/dynamic-routes) object from the root segment down to the segment `icon` or `apple-icon` is colocated in.

> **Good to know**: If you use [`generateImageMetadata`](/docs/app/api-reference/functions/generate-image-metadata), the function will also receive an `id` prop that is a promise resolving to the `id` value from one of the items returned by `generateImageMetadata`.

```tsx filename="app/shop/[slug]/icon.tsx" switcher
export default function Icon({ params }: { params: { slug: string } }) {
export default async function Icon({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
// ...
}
```

```jsx filename="app/shop/[slug]/icon.js" switcher
export default function Icon({ params }) {
export default async function Icon({ params }) {
const { slug } = await params
// ...
}
```

| Route | URL | `params` |
| ------------------------------- | ----------- | ------------------------- |
| `app/shop/icon.js` | `/shop` | `undefined` |
| `app/shop/[slug]/icon.js` | `/shop/1` | `{ slug: '1' }` |
| `app/shop/[tag]/[item]/icon.js` | `/shop/1/2` | `{ tag: '1', item: '2' }` |
| Route | URL | `params` |
| ------------------------------- | ----------- | ---------------------------------- |
| `app/shop/icon.js` | `/shop` | `undefined` |
| `app/shop/[slug]/icon.js` | `/shop/1` | `Promise<{ slug: '1' }>` |
| `app/shop/[tag]/[item]/icon.js` | `/shop/1/2` | `Promise<{ tag: '1', item: '2' }>` |

### Returns

Expand Down Expand Up @@ -254,6 +262,7 @@ export default function Icon() {}

## Version History

| Version | Changes |
| --------- | -------------------------------------------- |
| `v13.3.0` | `favicon` `icon` and `apple-icon` introduced |
| Version | Changes |
| --------- | ---------------------------------------------------- |
| `v16.0.0` | `params` is now a promise that resolves to an object |
| `v13.3.0` | `favicon` `icon` and `apple-icon` introduced |
43 changes: 29 additions & 14 deletions docs/01-app/03-api-reference/03-file-conventions/01-metadata/opengraph-image.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -220,25 +220,33 @@ The default export function receives the following props:

#### `params` (optional)

An object containing the [dynamic route parameters](/docs/app/api-reference/file-conventions/dynamic-routes) object from the root segment down to the segment `opengraph-image` or `twitter-image` is colocated in.
A promise that resolves to an object containing the [dynamic route parameters](/docs/app/api-reference/file-conventions/dynamic-routes) object from the root segment down to the segment `opengraph-image` or `twitter-image` is colocated in.

> **Good to know**: If you use [`generateImageMetadata`](/docs/app/api-reference/functions/generate-image-metadata), the function will also receive an `id` prop that is a promise resolving to the `id` value from one of the items returned by `generateImageMetadata`.

```tsx filename="app/shop/[slug]/opengraph-image.tsx" switcher
export default function Image({ params }: { params: { slug: string } }) {
export default async function Image({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
// ...
}
```

```jsx filename="app/shop/[slug]/opengraph-image.js" switcher
export default function Image({ params }) {
export default async function Image({ params }) {
const { slug } = await params
// ...
}
```

| Route | URL | `params` |
| ------------------------------------------ | ----------- | ------------------------- |
| `app/shop/opengraph-image.js` | `/shop` | `undefined` |
| `app/shop/[slug]/opengraph-image.js` | `/shop/1` | `{ slug: '1' }` |
| `app/shop/[tag]/[item]/opengraph-image.js` | `/shop/1/2` | `{ tag: '1', item: '2' }` |
| Route | URL | `params` |
| ------------------------------------------ | ----------- | ---------------------------------- |
| `app/shop/opengraph-image.js` | `/shop` | `undefined` |
| `app/shop/[slug]/opengraph-image.js` | `/shop/1` | `Promise<{ slug: '1' }>` |
| `app/shop/[tag]/[item]/opengraph-image.js` | `/shop/1/2` | `Promise<{ tag: '1', item: '2' }>` |

### Returns

Expand Down Expand Up @@ -334,8 +342,13 @@ export const size = {
}
export const contentType = 'image/png'

export default async function Image({ params }: { params: { slug: string } }) {
const post = await fetch(`https://.../posts/${params.slug}`).then((res) =>
export default async function Image({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
const post = await fetch(`https://.../posts/${slug}`).then((res) =>
res.json()
)

Expand Down Expand Up @@ -373,7 +386,8 @@ export const size = {
export const contentType = 'image/png'

export default async function Image({ params }) {
const post = await fetch(`https://.../posts/${params.slug}`).then((res) =>
const { slug } = await params
const post = await fetch(`https://.../posts/${slug}`).then((res) =>
res.json()
)

Expand Down Expand Up @@ -509,6 +523,7 @@ export default async function Image() {

## Version History

| Version | Changes |
| --------- | ------------------------------------------------- |
| `v13.3.0` | `opengraph-image` and `twitter-image` introduced. |
| Version | Changes |
| --------- | ---------------------------------------------------- |
| `v16.0.0` | `params` is now a promise that resolves to an object |
| `v13.3.0` | `opengraph-image` and `twitter-image` introduced. |
72 changes: 60 additions & 12 deletions docs/01-app/03-api-reference/04-functions/generate-image-metadata.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ export function generateImageMetadata({ params }) {

## Returns

The `generateImageMetadata` function should return an `array` of objects containing the image's metadata such as `alt` and `size`. In addition, each item **must** include an `id` value which will be passed to the props of the image generating function.
The `generateImageMetadata` function should return an `array` of objects containing the image's metadata such as `alt` and `size`. In addition, each item **must** include an `id` value which will be passed as a promise to the props of the image generating function.

| Image Metadata Object | Type |
| --------------------- | ----------------------------------- |
Expand All @@ -69,7 +69,8 @@ export function generateImageMetadata() {
]
}

export default function Icon({ id }: { id: string }) {
export default async function Icon({ id }: { id: Promise<string | number> }) {
const iconId = await id
return new ImageResponse(
(
<div
Expand All @@ -84,7 +85,7 @@ export default function Icon({ id }: { id: string }) {
color: '#fafafa',
}}
>
Icon {id}
Icon {iconId}
</div>
)
)
Expand All @@ -109,7 +110,8 @@ export function generateImageMetadata() {
]
}

export default function Icon({ id }) {
export default async function Icon({ id }) {
const iconId = await id
return new ImageResponse(
(
<div
Expand All @@ -124,13 +126,57 @@ export default function Icon({ id }) {
color: '#fafafa',
}}
>
Icon {id}
Icon {iconId}
</div>
)
)
}
```

## Image generation function props

When using `generateImageMetadata`, the default export image generation function receives the following props:

#### `id`

A promise that resolves to the `id` value from one of the items returned by `generateImageMetadata`. The `id` will be a `string` or `number` depending on what was returned from `generateImageMetadata`.

```tsx filename="icon.tsx" switcher
export default async function Icon({ id }: { id: Promise<string | number> }) {
const iconId = await id
// Use iconId to generate the image
}
```

```jsx filename="icon.js" switcher
export default async function Icon({ id }) {
const iconId = await id
// Use iconId to generate the image
}
```

#### `params` (optional)

A promise that resolves to an object containing the [dynamic route parameters](/docs/app/api-reference/file-conventions/dynamic-routes) from the root segment down to the segment the image is colocated in.

```tsx filename="icon.tsx" switcher
export default async function Icon({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
// Use slug to generate the image
}
```

```jsx filename="icon.js" switcher
export default async function Icon({ params }) {
const { slug } = await params
// Use slug to generate the image
}
```

### Examples

#### Using external data
Expand Down Expand Up @@ -160,11 +206,11 @@ export default async function Image({
params,
id,
}: {
params: { id: string }
id: number
params: Promise<{ id: string }>
id: Promise<number>
}) {
const productId = (await params).id
const imageId = id
const imageId = await id
const text = await getCaptionForImage(productId, imageId)

return new ImageResponse(
Expand Down Expand Up @@ -200,7 +246,7 @@ export async function generateImageMetadata({ params }) {

export default async function Image({ params, id }) {
const productId = (await params).id
const imageId = id
const imageId = await id
const text = await getCaptionForImage(productId, imageId)

return new ImageResponse(
Expand All @@ -221,6 +267,8 @@ export default async function Image({ params, id }) {

## Version History

| Version | Changes |
| --------- | ----------------------------------- |
| `v13.3.0` | `generateImageMetadata` introduced. |
| Version | Changes |
| --------- | --------------------------------------------------------------------------------------------------- |
| `v16.0.0` | `id` passed to the Image generation function is now a promise that resolves to `string` or `number` |
| `v16.0.0` | `params` passed to the Image generation function is now a promise that resolves to an object |
| `v13.3.0` | `generateImageMetadata` introduced. |
Loading