--- title: "defineOgImage()" description: "Define an og:image for the current page." canonical_url: "https://nuxtseo.com/docs/og-image/api/define-og-image" last_updated: "2026-05-05T18:41:36.305Z" --- ## Introduction 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 ```ts defineOgImage(component, props, options) ``` - `component`: The component name (e.g., `'NuxtSeo'`, `'MyTemplate'`) - `props`: Props to pass to the component - `options`: Additional options like `cacheMaxAgeSeconds`, `extension`, etc. ```ts // Simple defineOgImage('NuxtSeo', { 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](/docs/og-image/api/config). ### `width` - Type: `number | (() => number) | Ref` - Default: `1200` The width of the image. ### `height` - Type: `number | (() => number) | Ref` - Default: `600` The height of the image. ### `alt` - Type: `string | (() => string) | Ref` - Default: `undefined` The alt text of the image. It's recommended to always provide this for accessibility. ### `props` - Type: `Record` - 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. Screenshots created via [defineOgImageScreenshot](/docs/og-image/api/define-og-image-screenshot) default to `'jpeg'`. See the [JPEGs](/docs/og-image/guides/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` The `html` option is deprecated and will be removed in the next major version due to SSRF risk. Use a Vue component instead. This option is disabled when `security.strict` is enabled. - Type: `string` - Default: `undefined` Inline HTML to use when generating the image. See the [inline HTML templates](#inline-html-templates) section for more details. ### `url` - Type: `string | (() => string) | Ref` - 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, this key is used directly for caching instead of the auto-generated key. ### `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:
Value Behavior
'og' (default) Generates both og:image and twitter:image meta tags
'twitter' Generates only twitter:image meta tags
Any other string Generates only og:image meta tags (additional images)
```ts defineOgImage([ { title: 'Default' }, // key: 'og' (default) { title: 'Square', key: 'square', width: 450, height: 450 }, ]) ``` See [Multiple OG Images](/docs/og-image/guides/whatsapp) for more details. ### `resvg` - Type: `ResvgRenderOptions` - Default: `{}` Options to pass to Resvg when generating images. See the [Resvg docs](https://github.com/yisibl/resvg-js). ### `satori` - Type: `SatoriOptions` - Default: `{}` Options to pass to Satori when generating images. See the [Satori docs](https://github.com/vercel/satori). ### `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](https://sharp.pixelplumbing.com/). ### `screenshot` - Type: `ScreenshotOptions` - Default: `{}` Options to pass to the browser when generating screenshots. See the [defineOgImageScreenshot](/docs/og-image/api/define-og-image-screenshot) documentation for more details. ### `fonts` - Default: `[]` Deprecated. Configure fonts via [`@nuxt/fonts`](https://fonts.nuxt.com) instead. The module automatically detects and uses fonts from `@nuxt/fonts`. Extra fonts to use when rendering this OG image. See the [Custom Fonts](/docs/og-image/guides/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`). Community templates (like `NuxtSeo`) are only available in development by default. You must [eject them](/docs/og-image/guides/community-templates) before building for production. 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 ```ts defineOgImage('MyCustomComponent', { title: 'Hello' }) // Select a specific renderer variant defineOgImage('MyCustomComponent.takumi', { title: 'Hello' }) ``` ## Usage ### Inline HTML Templates We deprecate the inline HTML templates feature and will remove it in the next major version. Use a Vue component instead. If you have a simple template and prefer to inline it, you can do so using the `html` option: ```ts defineOgImage('NuxtSeo', {}, { html: `
hello world
`, }) ``` ### Using an Existing Image To use a pre-prepared image instead of generating one, use `useSeoMeta()` directly: ```ts 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: ```ts defineOgImage('NuxtSeo', { 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: ```ts defineOgImage('NuxtSeo', { 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: ```ts defineOgImage('NuxtSeo', [ { 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: ```ts const urls = defineOgImage('NuxtSeo', { title: 'My Page' }, [ { key: 'og' }, { key: 'square', width: 450, height: 450 }, ]) // urls = [ // '/_og/s/title_My+Page,p_...', // '/_og/s/k_square,w_450,h_450,title_My+Page,p_...' // ] ``` See the [WhatsApp guide](/docs/og-image/guides/whatsapp) 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](/docs/og-image/guides/resolve-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](/docs/og-image/guides/performance) guide for full strategies. ## Disabling the og:image When you use `defineOgImage` with `false` it will disable the og:image for the current page.