defineOgImage() · Nuxt OG Image · Nuxt SEO

[NuxtSEO](https://nuxtseo.com/ "Home")

- [Modules](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [Tools](https://nuxtseo.com/tools)
- [Pro](https://nuxtseo.com/pro)
- [Learn SEO](https://nuxtseo.com/learn-seo/nuxt) [Releases](https://nuxtseo.com/releases)

[1.4K](https://github.com/harlan-zw/nuxt-seo)

[Nuxt SEO on GitHub](https://github.com/harlan-zw/nuxt-seo)

**OG Image v6** is here! Looking for an older version? [View v5 docs](https://nuxtseo.com/docs/og-image/v5/getting-started/introduction).

[User Guides](https://nuxtseo.com/docs/og-image/getting-started/introduction)

[API](https://nuxtseo.com/docs/og-image/api/define-og-image)

[Releases](https://nuxtseo.com/docs/og-image/releases/v6)

OG Image

- [Switch to OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction)
- [Switch to Nuxt SEO](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [Switch to Robots](https://nuxtseo.com/docs/robots/getting-started/introduction)
- [Switch to Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction)
- [Switch to Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction)
- [Switch to Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction)
- [Switch to SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction)
- [Switch to Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction)
- [Switch to Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction)
- [Switch to AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction)

Search…```k`` /`

v6 (latest)

- Playgrounds
- [Discord Support](https://discord.com/invite/275MBUBvgP)

### Nuxt API

- [`defineOgImage()`](https://nuxtseo.com/docs/og-image/api/define-og-image)
- [`defineOgImageComponent()`](https://nuxtseo.com/docs/og-image/api/define-og-image-component)
- [`defineOgImageScreenshot()`](https://nuxtseo.com/docs/og-image/api/define-og-image-screenshot)
- [Components](https://nuxtseo.com/docs/og-image/api/components)
- [nuxt.config.ts](https://nuxtseo.com/docs/og-image/api/config)
- [Nuxt Hooks](https://nuxtseo.com/docs/og-image/api/nuxt-hooks)

### Nitro API

- [Nitro Hooks](https://nuxtseo.com/docs/og-image/nitro-api/nitro-hooks)

Nuxt API

# defineOgImage()

[Copy for LLMs](https://nuxtseo.com/docs/og-image/api/define-og-image.md)

## [Introduction](#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](#syntax)

```
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.

```
// Simple
defineOgImage('NuxtSeo', { title: 'Hello World' })

// With options
defineOgImage('MyTemplate', { title: 'Hello' }, { cacheMaxAgeSeconds: 3600 })
```

## [Props](#props)

If you'd like to change the default options for all `defineOgImage` calls, you can do so in the [Nuxt Config](https://nuxtseo.com/docs/og-image/api/config).

### [`width`](#width)

- Type: `number`
- Default: `1200`

The width of the image.

### [`height`](#height)

- Type: `number`
- Default: `600`

The height of the image.

### [`alt`](#alt)

- Type: `string`
- Default: `undefined`

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

### [`extension`](#extension)

- Type: `'png' | 'jpeg' | 'jpg' | 'webp' | 'svg' | 'html'`
- Default: `'png'`

The extension to use when generating the image.

See the [JPEGs](https://nuxtseo.com/docs/og-image/guides/jpegs) guide for using JPEGs.

### [`emojis`](#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`](#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`](#url)

- Type: `string`
- Default: `undefined`

Use a prebuilt image instead of generating one. Should be an absolute URL.

### [`cacheMaxAgeSeconds`](#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`](#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`](#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) |

```
defineOgImage([
  { title: 'Default' }, // key: 'og' (default)
  { title: 'Square', key: 'square', width: 450, height: 450 },
])
```

See [Multiple OG Images](https://nuxtseo.com/docs/og-image/guides/whatsapp) for more details.

### [`resvg`](#resvg)

- Type: `ResvgRenderOptions`
- Default: `{}`

Options to pass to Resvg when generating images. See the [Resvg docs](https://github.com/yisibl/resvg-js).

### [`satori`](#satori)

- Type: `SatoriOptions`
- Default: `{}`

Options to pass to Satori when generating images. See the [Satori docs](https://github.com/vercel/satori).

### [`takumi`](#takumi)

- Type: `TakumiOptions`
- Default: `{}`

Options to pass to the Takumi renderer.

### [`sharp`](#sharp)

- Type: `SharpOptions`
- Default: `{}`

Options to pass to Sharp when generating images. See the [Sharp docs](https://sharp.pixelplumbing.com/).

### [`screenshot`](#screenshot)

- Type: `ScreenshotOptions`
- Default: `{}`

Options to pass to the browser when generating screenshots. See the [defineOgImageScreenshot](https://nuxtseo.com/docs/og-image/api/define-og-image-screenshot) documentation for more details.

### [`fonts`](#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](https://nuxtseo.com/docs/og-image/guides/custom-fonts) documentation for more details.

### [`component`](#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`).

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

```
defineOgImage('MyCustomComponent', { title: 'Hello' })

// Select a specific renderer variant
defineOgImage('MyCustomComponent.takumi', { title: 'Hello' })
```

## [Usage](#usage)

### [Inline HTML Templates](#inline-html-templates)

The inline HTML templates feature is deprecated and will be removed 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:

```
defineOgImage('NuxtSeo', {}, {
  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](#using-an-existing-image)

To use a pre-prepared image instead of generating one, use `useSeoMeta()` directly:

```
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](#multiple-og-images)

You can define multiple OG images per page for platforms like WhatsApp that require square images.

### [Shared Props with Variants (Recommended)](#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:

```
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:

```
defineOgImage('NuxtSeo', { title: 'My Page', description: 'A long description' }, [
  { key: 'og' },
  { key: 'whatsapp', width: 800, height: 800, props: { description: 'Short' } },
])
```

### [Array Syntax](#array-syntax)

Alternatively, pass an array as the second argument with all options inline:

```
defineOgImage('NuxtSeo', [
  { props: { title: 'My Page' } },
  { props: { title: 'My Page' }, key: 'whatsapp', width: 800, height: 800 },
])
```

### [Return Value](#return-value)

The function returns an array of generated image URLs:

```
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](https://nuxtseo.com/docs/og-image/guides/whatsapp) for more details.

## [Keeping URLs Short](#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](https://nuxtseo.com/docs/og-image/guides/performance) guide for full strategies.

## [Disabling the og:image](#disabling-the-ogimage)

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

[Edit this page](https://github.com/nuxt-modules/og-image/edit/main/docs/content/4.api/0.define-og-image.md)

[Markdown For LLMs](https://nuxtseo.com/docs/og-image/api/define-og-image.md)

Did this page help you?

[Error pages How to display og images for error pages](https://nuxtseo.com/docs/og-image/guides/error-pages) [defineOgImageComponent() Define an og:image for the current page with type safety.](https://nuxtseo.com/docs/og-image/api/define-og-image-component)

On this page

- [Introduction](#introduction)
- [Syntax](#syntax)
- [Props](#props)
- [Usage](#usage)
- [Multiple OG Images](#multiple-og-images)
- [Keeping URLs Short](#keeping-urls-short)
- [Disabling the og:image](#disabling-the-ogimage)

[GitHub](https://github.com/harlan-zw/nuxt-seo) [ Discord](https://discord.com/invite/275MBUBvgP)

### [NuxtSEO](https://nuxtseo.com/ "Home")

- [Getting Started](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [MCP](https://nuxtseo.com/docs/nuxt-seo/guides/mcp)

Modules

- [Robots](https://nuxtseo.com/docs/robots/getting-started/introduction)
- [Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction)
- [OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction)
- [Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction)
- [Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction)
- [SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction)
- [Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction)
- [Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction)
- [AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction)

### [NuxtSEO Pro](https://nuxtseo.com/pro "Home")

- [Getting Started](https://nuxtseo.com/pro)
- [Dashboard](https://nuxtseo.com/pro/dashboard)
- [Pro MCP](https://nuxtseo.com/docs/nuxt-seo-pro/mcp/installation)

### [Learn SEO](https://nuxtseo.com/learn-seo "Learn SEO")

Nuxt

- [Mastering Meta](https://nuxtseo.com/learn-seo/nuxt/mastering-meta)
- [Controlling Crawlers](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers)
- [Launch & Listen](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen)
- [Routes & Rendering](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering)
- [Staying Secure](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/security)

Vue

- [Vue SEO Guide](https://nuxtseo.com/learn-seo/vue)
- [Mastering Meta](https://nuxtseo.com/learn-seo/vue/mastering-meta)
- [Controlling Crawlers](https://nuxtseo.com/learn-seo/vue/controlling-crawlers)
- [SPA SEO](https://nuxtseo.com/learn-seo/vue/spa)
- [SSR Frameworks](https://nuxtseo.com/learn-seo/vue/ssr-frameworks)
- [SEO Checklist](https://nuxtseo.com/learn-seo/checklist)
- [Pre-Launch Warmup](https://nuxtseo.com/learn-seo/pre-launch-warmup)
- [Backlinks & Authority](https://nuxtseo.com/learn-seo/backlinks)

### [Tools](https://nuxtseo.com/tools "SEO Tools")

- [Social Share Debugger](https://nuxtseo.com/tools/social-share-debugger)
- [Robots.txt Generator](https://nuxtseo.com/tools/robots-txt-generator)
- [Meta Tag Checker](https://nuxtseo.com/tools/meta-tag-checker)
- [HTML to Markdown](https://nuxtseo.com/tools/html-to-markdown)
- [XML Sitemap Validator](https://nuxtseo.com/tools/xml-sitemap-validator)
- [Schema.org Validator](https://nuxtseo.com/tools/schema-validator)
- [Keyword Research Pro](https://nuxtseo.com/tools/keyword-research)
- [SERP Analyzer Pro](https://nuxtseo.com/tools/serp-analyzer)
- [Domain Rankings Pro](https://nuxtseo.com/tools/domain-rankings)

Copyright © 2023-2026 Harlan Wilton - [MIT License](https://github.com/harlan-zw/nuxt-seo/blob/main/license) · [mdream](https://mdream.dev)