---
title: "defineOgImage()"
description: "Define an og:image for the current page."
canonical_url: "https://nuxtseo.com/docs/og-image/v5/api/define-og-image"
last_updated: "2026-09-05T15:40:36.655Z"
---

## Introduction

The `defineOgImage()`{lang="ts"} 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](/docs/og-image/api/config).

### `width`

- Type: `number`{lang="ts"}
- Default: `1200`{lang="ts"}

The width of the image.

### `height`

- Type: `number`{lang="ts"}
- Default: `600`{lang="ts"}

The height of the image.

### `alt`

- Type: `string`{lang="ts"}
- Default: `undefined`{lang="ts"}

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

### `url`

- Type: `string`{lang="ts"}
- Default: `undefined`{lang="ts"}

If you already have a URL of the image to use, you can use this instead of rendering a OG image.

```ts
defineOgImage({
  url: '/my-image.png'
})
```

See [using an existing image](#using-an-existing-image) for more details.

### `renderer`

- Type: `'satori' | 'chromium'`{lang="ts"}
- Default: `'satori'`{lang="ts"}

The renderer to use when generating the image. This is useful if you want to use a different renderer for a specific page.

```ts
defineOgImage({
  component: 'MyCustomComponent',
  renderer: 'chromium' // generate screenshot of the MyCustomComponent component
})
```

### `extension`

- Type: `'png' | 'jpeg' | 'jpg'`{lang="ts"}
- Default: `'png'`{lang="ts"}

The extension to use when generating the image.

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'`{lang="ts"}
- Default: `'noto'`{lang="ts"}

The emoji set to use when generating the image.

### `html`

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

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

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

### `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 chromium when generating screenshots. See the [defineOgImageScreenshot](/docs/og-image/api/define-og-image-screenshot) documentation for more details.

### `fonts`

- Type: `InputFontConfig[]`{lang="ts"}
- Default: `[]`{lang="ts"}

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: `NuxtSeo`{lang="ts"}

The component to use when rendering the image. This is useful if you want to use a custom component.

```ts
defineOgImage({
  component: 'MyCustomComponent'
})
```

It's recommended to use the [defineOgImageComponent](/docs/og-image/api/define-og-image-component) composable instead of this
for better type safety.

### `props`

- Type: `Record<string, any>`{lang="ts"}
- Default: `undefined`{lang="ts"}

Additional props to pass to the component. This is useful if you want to pass props to a custom component.

```ts
defineOgImage({
  component: 'MyCustomTemplate',
  props: {
    myProp: 'myValue'
  }
})
```

It's recommended to use the [defineOgImageComponent](/docs/og-image/api/define-og-image-component) 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.

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

```ts
/* 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.