Per-page Open Graph images
A blog needs a distinct social preview for every article.
Next.js 16+ · Class
ImageResponse
ImageResponse generates dynamic images from JSX and CSS in Next.js App Router applications. It is useful for Open Graph images, Twitter cards, and other request-time image endpoints.
How it works
ImageResponse turns a React element into a dynamically rendered image. Import it from next/og, optionally configure dimensions, fonts, emoji, debugging, and HTTP response properties, then return the instance from a Route Handler or metadata image file.
Syntax
new ImageResponse(element: ReactElement, options?: { width?: number; height?: number; emoji?: 'twemoji' | 'blobmoji' | 'noto' | 'openmoji'; fonts?: { name: string; data: ArrayBuffer; weight: number; style: 'normal' | 'italic' }[]; debug?: boolean; status?: number; statusText?: string; headers?: Record<string, string> })Parameters
| Name | Type | Description |
|---|---|---|
element | ReactElement | React element containing the image's JSX layout and styling. |
options | object | Optional rendering and HTTP response configuration, including dimensions, emoji, fonts, debugging, status, status text, and headers. |
Returns
An image response suitable for returning from a Route Handler or metadata image function.
Key points
- Use a React element styled with JSX and CSS as the source for a dynamically rendered image.
- Typical outputs include Open Graph images and Twitter cards, especially when their content depends on request data.
- A Route Handler can create the image when the request arrives rather than requiring a prebuilt static asset.
- The current App Router API is imported from the next/og package.
- The default output width is 1,200 pixels, unless the options object overrides it.
- The default output height is 630 pixels, unless a different value is supplied.
Common mistakes
- The complete generated-image bundle, including JSX, CSS, fonts, images, and other assets, must stay within 500 KB.
- Large fonts or embedded assets can consume the bundle limit even when the application code itself is small.
Example: Generate an image in a Route Handler
import { ImageResponse } from 'next/og'
export const runtime = 'edge'
export async function GET() {
return new ImageResponse(
(
<div
style={{
display: 'flex',
width: '100%',
height: '100%',
alignItems: 'center',
justifyContent: 'center',
background: 'white',
fontSize: 64,
}}
>
Hello, Next.js!
</div>
),
{ width: 1200, height: 630 },
)
}This Route Handler returns a generated PNG containing JSX-styled text.
When to use it
Dynamic image Route Handlers
A service exposes an endpoint that renders branded visuals from request parameters.
Metadata icons
A project needs a generated favicon or app icon.
Interview questions
QWhat does ImageResponse do?
ImageResponse accepts a React element and an options object, then produces a response suitable for an image endpoint. It is commonly used with JSX and CSS for generated social images.
Follow-up: How would you expose it? Return the ImageResponse instance from a Route Handler, or from a metadata image file such as opengraph-image.tsx.
QHow do you use ImageResponse in an App Router endpoint?
Import ImageResponse from next/og and return new ImageResponse(...) from a Route Handler. The element supplies the visual structure, while options can set width and height.
Follow-up: What must be checked when adding custom fonts or images? Include their data in the bundle and ensure the total remains at or below 500 KB.
QWhich constructor options are available?
The constructor defaults to 1200 by 630 pixels, uses twemoji for emoji, and has debugging disabled. Options also support fonts plus HTTP status, status text, and headers.
Follow-up: How can response metadata be customized? Pass status, statusText, or headers in the options object; these values are forwarded to the HTTP response.
Related
Route Handlersnext/ogopengraph-image.tsxtwitter-imageMetadata