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.

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.

Disabling the og:image

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