--- 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-08-24T03:54:54.346Z" --- The `defineOgImage()`{lang="ts"} 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' })`{lang="ts"}. ## 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`{lang="ts"} - Default: `1200`{lang="ts"} The width of the image. ### `height` - Type: `number | (() => number) | Ref`{lang="ts"} - Default: `600`{lang="ts"} The height of the image. ### `alt` - Type: `string | (() => string) | Ref`{lang="ts"} - Default: `undefined`{lang="ts"} The alt text of the image. It's recommended to always provide this for accessibility. ### `props` - Type: `Record`{lang="ts"} - Default: `{}`{lang="ts"} Props to pass to the component. When using the `defineOgImage('ComponentName', { ...props })`{lang="ts"} shorthand, this is the second argument. ### `extension` - Type: `'png' | 'jpeg' | 'jpg' | 'webp' | 'svg' | 'html'`{lang="ts"} - Default: `'png'`{lang="ts"} The extension to use when generating the image. ::note 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`{lang="ts"} - Default: `'noto'`{lang="ts"} The emoji set to use when generating the image. Set to `false` to disable emoji rendering. ### `html` ::deprecated The `html` option is deprecated and the next major version will remove it due to SSRF risk. Use a Vue component instead. `security.strict` disables this option. :: - Type: `string`{lang="ts"} - Default: `undefined`{lang="ts"} 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`{lang="ts"} - Default: `undefined`{lang="ts"} Use a prebuilt image instead of generating one. Should be an absolute URL. ### `cacheMaxAgeSeconds` - Type: `number`{lang="ts"} - Default: `60 * 60 * 24 * 3`{lang="ts"} (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`{lang="ts"} - Default: `undefined`{lang="ts"} Custom cache key for this OG image. When set, the module uses this key directly for caching instead of the auto-generated key. ### `key` - Type: `string`{lang="ts"} - Default: `'og'`{lang="ts"} 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`{lang="ts"} - Default: `{}`{lang="ts"} Options to pass to Resvg when generating images. See the [Resvg docs](https://github.com/yisibl/resvg-js). ### `satori` - Type: `SatoriOptions`{lang="ts"} - Default: `{}`{lang="ts"} Options to pass to Satori when generating images. See the [Satori docs](https://github.com/vercel/satori). ### `takumi` - Type: `TakumiOptions`{lang="ts"} - Default: `{}`{lang="ts"} Options to pass to the Takumi renderer. ### `sharp` - Type: `SharpOptions`{lang="ts"} - Default: `{}`{lang="ts"} Options to pass to Sharp when generating images. See the [Sharp docs](https://sharp.pixelplumbing.com/). ### `screenshot` - Type: `ScreenshotOptions`{lang="ts"} - Default: `{}`{lang="ts"} 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: `[]`{lang="ts"} ::deprecated 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`{lang="ts"} - Default: First non-community component, or `NuxtSeo`{lang="ts"} 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`). ::note 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 ::deprecated 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()`{lang="ts"} 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()`{lang="ts"}. ## 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/`{lang="html"} 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. This is useful when passing an array of conditional variants, letting you skip an entry without an `if` branch around the call.