defineOgImage() · Nuxt OG Image · Nuxt SEO

-
-
-
-

[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?

.

OG Image

-
-
-
-
-
-
-
-
-
-

Search…```k`` /`

v6 (latest)

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

### Nuxt API

-
-
-
-
-
-

### Nitro API

-

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

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

- Type: `number| (() => number)| Ref<number>`
- Default: `1200`

The width of the image.

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

- Type: `number| (() => number)| Ref<number>`
- Default: `600`

The height of the image.

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

- Type: `string| (() => string)| Ref<string>`
- Default: `undefined`

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

### [`props`](#props-1)

- Type: `Record<string, any>`
- Default: `{}`

Props to pass to the component. When using the `defineOgImage('ComponentName', { ...props})` shorthand, this is the second argument.

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

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

The extension to use when generating the image.

Screenshots created via

 default to `'jpeg'`.

See the

 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| (() => string)| Ref<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

 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

 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

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

Community templates (like `NuxtSeo`) are only available in development by default. You must

 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

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

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

## [Usage](#usage)

### [Inline HTML Templates](#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:

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

 for more details.

## [Embedding On Other Pages](#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

.
## [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

 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?

On this page

- [Introduction](#introduction)
- [Syntax](#syntax)
- [Props](#props)
- [Usage](#usage)
- [Multiple OG Images](#multiple-og-images)
- [Embedding On Other Pages](#embedding-on-other-pages)
- [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)

###

-
-

Modules

-
-
-
-
-
-
-
-
-

###

-
-
-

###

Nuxt

-
-
-
-
-

Vue

-
-
-
-
-
-
-
-

###

-
-
-
-
-
-
-
-
-
-

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