defineOgImage()

The defineOgImage() composable allows you to define an og:image for the current page.

It renders a custom OG image from a Vue component. To use a pre-prepared image instead, use useSeoMeta({ ogImage: '/my-image.png' }).

Syntax

defineOgImage(component, props, options)

• component: The component name (e.g., 'NuxtSeo.takumi', 'MyTemplate')
• props: Props to pass to the component
• options: Additional options like cacheMaxAgeSeconds, extension, etc.

If a template has more than one renderer variant, add the renderer suffix, such as 'NuxtSeo.takumi'. A bare name picks the first variant it finds.

// Simple
defineOgImage('NuxtSeo.takumi', { title: 'Hello World' })

// With options
defineOgImage('MyTemplate', { title: 'Hello' }, { cacheMaxAgeSeconds: 3600 })

Props

If you'd like to change the default options for all defineOgImage calls, you can do so in the Nuxt Config.

width

• Type: number | (() => number) | Ref<number>
• Default: 1200

The width of the image.

height

• Type: number | (() => number) | Ref<number>
• Default: 600

The height of the image.

alt

• Type: string | (() => string) | Ref<string>
• Default: undefined

The alt text of the image. It's recommended to always provide this for accessibility.

props

• Type: Record<string, any>
• Default: {}

Props to pass to the component. When using the defineOgImage('ComponentName', { ...props }) shorthand, this is the second argument.

extension

• Type: 'png' | 'jpeg' | 'jpg' | 'webp' | 'svg' | 'html'
• Default: 'png'

The extension to use when generating the image.

See the JPEGs guide for using JPEGs.

emojis

• Type: 'twemoji' | 'noto' | 'fluent-emoji' | 'fluent-emoji-flat' | 'fluent-emoji-high-contrast' | 'noto-v1' | 'emojione' | 'emojione-monotone' | 'emojione-v1' | 'streamline-emojis' | 'openmoji' | false
• Default: 'noto'

The emoji set to use when generating the image. Set to false to disable emoji rendering.

html

• Type: string
• Default: undefined

Inline HTML to use when generating the image. See the inline HTML templates section for more details.

url

• Type: string | (() => string) | Ref<string>
• Default: undefined

Use a prebuilt image instead of generating one. Should be an absolute URL.

cacheMaxAgeSeconds

• Type: number
• Default: 60 * 60 * 24 * 3 (3 days)

The number of seconds to cache the image for. This is useful for reducing the number of requests to the server.

cacheKey

• Type: string
• Default: undefined

Custom cache key for this OG image. When set, the module uses this key instead of the auto-generated key. Images with the same cacheKey share one cache entry.

key

• Type: string
• Default: 'og'

A unique identifier for the OG image, enabling multiple images per page with different dimensions. The key determines which meta tags the module generates:

defineOgImage('NuxtSeo.takumi', { title: 'My Page' }, [
  { key: 'og' }, // the default key
  { key: 'square', width: 450, height: 450 },
])

See Multiple OG Images for more details.

resvg

• Type: ResvgRenderOptions
• Default: {}

Options to pass to Resvg when generating images. See the Resvg docs.

satori

• Type: SatoriOptions
• Default: {}

Options to pass to Satori when generating images. See the Satori docs.

takumi

• Type: TakumiOptions
• Default: {}

Options to pass to the Takumi renderer.

sharp

• Type: SharpOptions
• Default: {}

Options to pass to Sharp when generating images. See the Sharp docs.

screenshot

• Type: ScreenshotOptions
• Default: {}

Options to pass to the browser when generating screenshots. See the defineOgImageScreenshot documentation for more details.

fonts

• Default: []

Extra fonts to use when rendering this OG image. See the Custom Fonts documentation for more details.

component

• Type: string
• Default: First non-community component, or NuxtSeo if none exist

The component to use when rendering the image. Components must be in components/OgImage/ with a renderer suffix (e.g., MyTemplate.satori.vue).

You can reference components using:

• Bare name: 'MyTemplate' - uses the first registered variant (or the only one if unambiguous)
• Dot notation: 'MyTemplate.satori' - selects a specific renderer variant
• PascalCase: 'MyTemplateSatori' - equivalent to dot notation

defineOgImage('MyCustomComponent', { title: 'Hello' })

// Select a specific renderer variant
defineOgImage('MyCustomComponent.takumi', { title: 'Hello' })

Usage

Inline HTML Templates

If you have a simple template and prefer to inline it, you can do so using the html option:

defineOgImage('NuxtSeo.takumi', {}, {
  html: `<div class="w-full h-full text-6xl flex justify-end items-end bg-blue-500 text-white">
    <div class="mb-10 underline mr-10">hello world</div>
</div>`,
})

Using an Existing Image

To use a pre-prepared image instead of generating one, use useSeoMeta() directly:

useSeoMeta({
  ogImage: '/my-image.png',
  ogImageWidth: 1200,
  ogImageHeight: 600,
  ogImageAlt: 'My Image',
})

This works without any interference from nuxt-og-image - the module only injects meta tags on pages that call defineOgImage().

Multiple OG Images

You can define multiple OG images per page for platforms like WhatsApp that require square images.

Shared Props with Variants (Recommended)

Pass shared props as the second argument and an array of size/key variants as the third. The module shares props across all variants - no duplication needed:

defineOgImage('NuxtSeo.takumi', { title: 'My Page', description: 'Welcome' }, [
  // Default 1200x600 for Twitter/Facebook
  { key: 'og' },
  // Square 800x800 for WhatsApp
  { key: 'whatsapp', width: 800, height: 800 },
])

Per-variant props override shared props when needed:

defineOgImage('NuxtSeo.takumi', { title: 'My Page', description: 'A long description' }, [
  { key: 'og' },
  { key: 'whatsapp', width: 800, height: 800, props: { description: 'Short' } },
])

Array Syntax

Alternatively, pass an array as the second argument with all options inline:

defineOgImage('NuxtSeo.takumi', [
  { props: { title: 'My Page' } },
  { props: { title: 'My Page' }, key: 'whatsapp', width: 800, height: 800 },
])

Return Value

The function returns an array of generated image URLs:

const urls = defineOgImage('NuxtSeo.takumi', { title: 'My Page' }, [
  { key: 'og' },
  { key: 'square', width: 450, height: 450 },
])
// urls = [
//   '/_og/d/title_My+Page,p_...',
//   '/_og/d/k_square,w_450,h_450,title_My+Page,p_...'
// ]

See the WhatsApp guide for more details.

Embedding On Other Pages

To render another page's OG image on a listing or index, use the /_og/r/ endpoint rather than reconstructing the URL. See Embedding OG Images.

Keeping URLs Short

Runtime OG image URLs encode all props in the path. To keep URLs short, pass minimal props (like a slug) and fetch data inside the component. See the Performance guide for full strategies.

Disabling the og:image

defineOgImage() does not accept false, and neither do its option arrays. To skip the og:image on one page, do not call it. To skip one variant, build the array before the call:

defineOgImage('NuxtSeo.takumi', { title: 'My Page' }, [
  { key: 'og' },
  ...(showSquare ? [{ key: 'square', width: 450, height: 450 }] : []),
])

To remove the og:image for a page or a group of pages, set ogImage: false in route rules. This also removes images from pages that call defineOgImage().