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.