JavaScript API

window.__og = window.__og || [];

One of the coolest features, in our opinion, is the ability to link your opengraph images and dynamically change the destination based on the latest render data. When leveraging a clientside framework like React, Vue.js, Svelte, or Ember.js for compositing images you often need to wait for elements to finish loading. To support this, we provide an API via the __og global variable to defer the render completion until you are absolutley ready. All renders are limited to a maximum of 5 seconds before it will be timed out and the default image is returned.

Adding the __og global variable requires you to push the ['ready'] or ['capture', selector_or_element] helper onto the stack telling the image renderer your content is ready for capture.

If you are not using the __og global variable, the renderer will wait for all fonts and images on the page to load.

Helpers

We’ve built in some common helpers to assist with your integration.

ready

window.__og.push(['ready'])

This is required (unless you are using capture) to signal the the image renderer that your content is ready for capture.

When using ready it should be the last helper as it will stop the pipeline.

capture

window.__og.push(['capture', selector_or_element]);

This is a shortcut helper combining link, preload, clip and ready into a single call. The selector_or_element can be any CSS selector that resolves to a single element, or the element itself. If the target element has an href attribute, the href will be used as the link metadata. Once all child img elements are loaded, the clip helper is called with the bounds of the element and finally ready.

When using capture it should be the last helper as it will stop the pipeline.

preload

window.__og.push(['preload', 'fonts', 'https://images.unsplash.com/photo-1636333825251-d921e6ff88e4']);
window.__og.push(['preload', 'fonts', 'images']);
window.__og.push(['preload', 'fonts']);
window.__og.push(['preload', 'https://images.unsplash.com/photo-1636333825251-d921e6ff88e4']);
window.__og.push(['preload', 'images']);

Arguments

• ‘fonts’ - Waits for all the fonts to load before rendering
• ‘images’ - Waits for all the images to load before rendering
• image url - Waits for the image to load before rendering

clip

window.__og.push(['clip', 0, 0, 1200, 630]);

Allows you to return a clipped portion of the image. Clipping requires the Professional Plan.

The clip rectangle can be any aspect ratio your plan allows, so this is also how you produce a vertical 9:16 card — clip a 1080×1920 region for a story / TikTok-shaped image:

window.__og.push(['clip', 0, 0, 1080, 1920]);

link

window.__og.push(['link', 'https://www.example.com']);

Sets the url to redirect the user when using link.opengraphimage.com

config

window.__og.push(['config', {
  format: 'webp',
  quality: 80,
  width: 1200,
  height: 630,
  transparent_background: true,
  skip: false
}]);

Dynamically override rendering options from your page’s JavaScript. This is useful when your template needs to control the output format, dimensions, or quality based on page content or state.

Requires the Professional or Enterprise plan.

Options

Option	Type	Description
format	"jpeg", "png", or "webp"	Override the output image format. Static formats only — see the note below.
quality	0–100	Set the image quality (applies to JPEG and WebP).
width	number (>= 1)	Override the viewport width in pixels. Clamped to your plan’s max width (see below).
height	number (>= 1)	Override the viewport height in pixels. Clamped to your plan’s max height (see below).
transparent_background	boolean	Enable a transparent background (PNG and WebP only).
skip	boolean	When true, skip image capture entirely. The render will return a skipped status with no image data.

Only the options you include will be overridden — all others keep their default values. Invalid options are rejected with an error.

Size clamps by plan. width / height are clamped to your plan’s maximum: Starter 1200×630, Professional 2048×2048, Enterprise 4096×4096 (absolute infrastructure ceiling 8192 in any dimension). Any aspect ratio within the cap works — a 1080×1920 request produces a vertical 9:16 story card on Professional and up. On Free/Starter the size stays 1200×630.

Animated output is NOT set here. The ['config'] format field accepts only the static formats (jpeg / png / webp); a page cannot self-upgrade a render to an animated format at runtime. Animated output (gif / animated_webp) is set at the origin/render level — og origin create/update --format gif, or create_origin(format:) — not via this per-page override. See the animation topic.

metadata

window.__og.push(['metadata', {
  id: 1,
  name: 'Jill Gamer'
}]);

Sets the x-ogi-meta header when “Send Metadata Header” is checked in your origin config.