defineOgImage()

Introduction

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

It supports rendering a custom image, using an existing image, or disabling the og:image for the current page.

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
• Default: 1200

The width of the image.

height

• Type: number
• Default: 600

The height of the image.

alt

• Type: string
• Default: undefined

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

url

• Type: string
• Default: undefined

If you already have a URL of the image to use, you can use this instead of rendering a OG image.

defineOgImage({
  url: '/my-image.png'
})

See using an existing image for more details.

renderer

• Type: 'satori' | 'chromium'
• Default: 'satori'

The renderer to use when generating the image. This is useful if you want to use a different renderer for a specific page.

defineOgImage({
  component: 'MyCustomComponent',
  renderer: 'chromium' // generate screenshot of the MyCustomComponent component
})

extension

• Type: 'png' | 'jpeg' | 'jpg'
• 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'
• Default: 'noto'

The emoji set to use when generating the image.

html

• Type: string
• Default: undefined

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

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.

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 are generated:

defineOgImage([
  { title: 'Default' }, // key: 'og' (default)
  { title: 'Square', 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.

sharp

• Type: SharpOptions
• Default: {}

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

screenshot

• Type: ScreenshotOptions
• Default: {}

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

fonts

• Type: InputFontConfig[]
• Default: []

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

component

• Type: string
• Default: NuxtSeo

The component to use when rendering the image. This is useful if you want to use a custom component.

defineOgImage({
  component: 'MyCustomComponent'
})

It's recommended to use the defineOgImageComponent composable instead of this for better type safety.

props

• Type: Record<string, any>
• Default: undefined

Additional props to pass to the component. This is useful if you want to pass props to a custom component.

defineOgImage({
  component: 'MyCustomTemplate',
  props: {
    myProp: 'myValue'
  }
})

It's recommended to use the defineOgImageComponent composable instead of this for better type safety.

Usage

Inline HTML templates

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

defineOgImage({
  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

When you use defineOgImage with a url it will determine that you are using an og:image that you have already built. For example, one in your public directory, or hosted elsewhere.

Using this can be useful for overriding runtime images for specific pages.

/* app.vue */
// setting a runtime image for all pages
defineOgImage({ component: 'root' })

/* pages/static.vue */
// overriding the image using a prebuilt one
defineOgImage({ url: 'https://some-domain.png/static.png', width: 1200, height: 600, alt: 'My Image' })

Only valid Open Graph image properties will work when using url such as alt, width, height and type.

Multiple OG Images

You can define multiple OG images per page by passing an array. This is useful for platforms like WhatsApp that require square images.

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

The function returns an array of generated image URLs:

const urls = defineOgImage([
  { title: 'Default' },
  { title: 'Square', key: 'square', width: 450, height: 450 },
])
// urls = [
//   '/_og/s/title_Default,p_...',
//   '/_og/s/k_square,w_450,h_450,title_Square,p_...'
// ]

See the WhatsApp guide for more details.

Disabling the og:image

When you use defineOgImage with false it will disable the og:image for the current page.