Dynamic social previews
A request needs a social card whose text or imagery depends on route data.
Next.js 16+ · Module
next/og
next/og exports ImageResponse for generating dynamic Open Graph, Twitter, and other images from JSX and CSS. It can be returned from Route Handlers or metadata image files.
- Since
- v14.0.0
How it works
next/og provides ImageResponse, which turns a React element and optional rendering or HTTP options into an image response. It supports JSX with a documented subset of CSS, and can be used in Route Handlers or metadata image files for generated Open Graph and Twitter images.
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 used as the image's rendered content. |
options | object | Optional image and response settings, including width, height, emoji, fonts, debug, status, statusText, and headers. |
Returns
A Response containing the generated image.
Key points
- Use
ImageResponseto render a dynamic image from a JSX tree and CSS styles. - Typical outputs include Open Graph cards and Twitter cards.
- A Route Handler can create the image when a request arrives.
- The renderer supports practical layout, typography, and nested-image features.
- HTTP response behavior can be customized with status, status text, and headers.
- Current code should import the constructor from
next/og, not its formernext/serverlocation.
Common mistakes
- The complete bundle—including JSX, CSS, fonts, images, and other assets—must stay within 500 KB.
Example: Generate an OG image in a Route Handler
import { ImageResponse } from 'next/og'
export const runtime = 'edge'
export async function GET() {
return new ImageResponse(
(
<div
style={{
width: '100%',
height: '100%',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
background: '#111827',
color: 'white',
fontSize: 64,
}}
>
Hello world!
</div>
),
{ width: 1200, height: 630 },
)
}A Route Handler returns a dynamically generated 1200×630 image containing styled JSX.
When to use it
Metadata image generation
A route segment needs a generated Open Graph or Twitter image without storing static files.
Custom-font rendering
An application needs branded typography in generated cards.
Interview questions
QWhat does ImageResponse do?
Import ImageResponse from next/og and construct it with a React element plus optional settings such as dimensions, fonts, and response metadata. The result is a web Response containing the generated image.
Follow-up: How would you generate an image for a dynamic blog post? Place an opengraph-image.tsx file in the [slug] segment, load the post data, and return an ImageResponse using the resolved route parameter.
QWhat are the main constructor inputs?
The constructor accepts a React element and an options object. Options include width and height, an emoji set, custom fonts, debugging, and HTTP response fields such as status and headers.
Follow-up: How can custom fonts be supplied? Pass font records containing a name, ArrayBuffer data, numeric weight, and normal or italic style.
QWhat styling capabilities does it provide?
It supports common CSS features such as flexbox, absolute positioning, text wrapping, centering, nested images, and custom fonts. It is intended for generated social images and integrates with Route Handlers and metadata file conventions.
Follow-up: What should be checked if an image fails during deployment? Verify the bundle remains under 500 KB and that the implementation uses APIs compatible with the Edge Runtime.
Related
Route Handlersopengraph-imagetwitter-imagegenerateImageMetadataMetadata Files