ImageResponse API Reference
Reference for the ImageResponse constructor and its options.
ImageResponse
The ImageResponse class is the central API for generating and serving dynamic images. It extends the standard Web API Response and is designed to be returned directly from a SvelteKit server route (+server.ts).
The constructor takes the component/HTML template, rendering options, and component props.
new ImageResponse<T extends string | Component<any>>(
element: T,
options?: ImageResponseOptions,
props?: T extends Component<any> ? ComponentProps<T> : never
): Response;
ImageResponse Parameters
To create your dynamic Open Graph image, the ImageResponse constructor needs just three pieces of information, passed in this specific order. Think of this as defining the design, the settings, and the data for your image.
- Svelte Component or Raw HTML: The design of your image—what people will actually see.
- Options: The settings that define the image's size, fonts, and response headers.
- Props: The dynamic data (like a blog post title) to feed into your Svelte component.
import { ImageResponse } from '@ethercorps/sveltekit-og';
import { CustomFont, resolveFonts } from '@ethercorps/sveltekit-og/fonts';
import MySvelteComponent from '$lib/og/MySvelteComponent.svelte';
export const GET = async () => {
const props = {
title: 'Dynamic Title',
subtitle: 'Generated with Sveltekit OG'
};
const fonts = [
new CustomFont('Inter', () => fetch('https://example.com/fonts/Inter-Regular.ttf').then(res => res.arrayBuffer()), {weight: '400'})
]
return new ImageResponse(
// 1. Svelte Component or Raw HTML
MySvelteComponent,
// 2. Options
{
width: 1200,
height: 630,
fonts: await resolveFonts(fonts)
},
// 3. Svelte Component props
props
);
};
Note
Font files must be loaded as raw binary data (ArrayBuffer). The GoogleFont, CustomFont and resolveFonts utilities are provided to help you asynchronously load your custom fonts correctly before the image is generated.
Svelte Component or HTML
This parameter defines the visual content of your Open Graph image. You can provide either a Svelte component or a raw HTML string.
Suggestion
ImageResponse Options
The options object allows you to customize various technical aspects of the generated image and its HTTP response.
We automatically add `Content-Type` based on the image format and `Cache-Control` for caching. If debug mode is enabled, the `Cache-Control` header is updated to `no-cache`.
Component Props
All Options Example
Here is an example demonstrating how to use several optional parameters, including setting custom headers and enabling debug mode.
import { ImageResponse } from '@ethercorps/sveltekit-og';
import { resolveFonts } from '@ethercorps/sveltekit-og/fonts';
import MySvelteComponent from '$lib/og/MySvelteComponent.svelte';
import { FONT_DATA } from '$lib/fonts'; // Assume pre-loaded font data
export const GET = async ({ url }) => {
// 1. Prepare dynamic data
const isError = url.searchParams.has('error');
// 2. Define custom options
const options = {
width: 1200,
height: 630,
debug: url.searchParams.has('debug'), // Toggle debug mode via query param
emoji: 'blobmoji', // Use a different emoji set
fonts: await resolveFonts(FONT_DATA),
// 3. Conditional HTTP Response options
status: isError ? 404 : 200,
statusText: isError ? 'Not Found' : 'OK',
headers: {
// Override or add custom headers
'X-OG-Generator': '@ethercorps/sveltekit-og',
}
};
// 4. Define component props
const props = {
title: isError ? 'Page Not Found' : 'Standard Post Title',
};
return new ImageResponse(MySvelteComponent, options, props);
};
Resolve Fonts
resolveFonts can only be used with GoogleFont and CustomFont instances.