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.

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.
`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.
`height`	`number` (>= 1)	Override the viewport height in pixels. Clamped to your plan’s max height.
`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.

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.

API