---
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-05-06T18:45:57.439Z"
---

## Introduction

The `defineOgImage()` 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`
- Default: `1200`

The width of the image.

### `height`

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

The height of the image.

### `alt`

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

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

### `url`

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

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'`
- Default: `'satori'`

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'`
- Default: `'png'`

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'`
- Default: `'noto'`

The emoji set to use when generating the image.

### `html`

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

Inline HTML to use when generating the image. See the [inline HTML templates](#inline-html-templates) section for more details.

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

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

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

### `fonts`

- Type: `InputFontConfig[]`
- Default: `[]`

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

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

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.