DocumentationShowcaseBlog

generateImageMetadata

Learn how to generate multiple images in a single Metadata API special file.

You can use generateImageMetadata to generate different versions of one image or return multiple images for one route segment. This is useful for when you want to avoid hard-coding metadata values, such as for icons.

Parameters

generateImageMetadata function accepts the following parameters:

params (optional)

An object containing the dynamic route parameters object from the root segment down to the segment generateImageMetadata is called from.

export function generateImageMetadata({
  params,
}: {
  params: { slug: string }
}) {
  // ...
}
RouteURLparams
app/shop/icon.js/shopundefined
app/shop/[slug]/icon.js/shop/1{ slug: '1' }
app/shop/[tag]/[item]/icon.js/shop/1/2{ tag: '1', item: '2' }

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 as a promise to the props of the image generating function.

Image Metadata ObjectType
idstring (required)
altstring
size{ width: number; height: number }
contentTypestring
import { ImageResponse } from 'next/og'
 
export function generateImageMetadata() {
  return [
    {
      contentType: 'image/png',
      size: { width: 48, height: 48 },
      id: 'small',
    },
    {
      contentType: 'image/png',
      size: { width: 72, height: 72 },
      id: 'medium',
    },
  ]
}
 
export default async function Icon({ id }: { id: Promise<string | number> }) {
  const iconId = await id
  return new ImageResponse(
    (
      <div
        style={{
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: 88,
          background: '#000',
          color: '#fafafa',
        }}
      >
        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.

export default async function Icon({ id }: { id: Promise<string | number> }) {
  const iconId = await id
  // Use iconId to generate the image
}

params (optional)

A promise that resolves to an object containing the dynamic route parameters from the root segment down to the segment the image is colocated in.

export default async function Icon({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // Use slug to generate the image
}

Examples

Using external data

This example uses the params object and external data to generate multiple Open Graph images for a route segment.

import { ImageResponse } from 'next/og'
import { getCaptionForImage, getOGImages } from '@/app/utils/images'
 
export async function generateImageMetadata({
  params,
}: {
  params: { id: string }
}) {
  const images = await getOGImages(params.id)
 
  return images.map((image, idx) => ({
    id: idx,
    size: { width: 1200, height: 600 },
    alt: image.text,
    contentType: 'image/png',
  }))
}
 
export default async function Image({
  params,
  id,
}: {
  params: Promise<{ id: string }>
  id: Promise<number>
}) {
  const productId = (await params).id
  const imageId = await id
  const text = await getCaptionForImage(productId, imageId)
 
  return new ImageResponse(
    (
      <div
        style={
          {
            // ...
          }
        }
      >
        {text}
      </div>
    )
  )
}

Version History

VersionChanges
v16.0.0id passed to the Image generation function is now a promise that resolves to string or number
v16.0.0params passed to the Image generation function is now a promise that resolves to an object
v13.3.0generateImageMetadata introduced.

On this page