Custom Fonts · 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)

### Getting Started

-
-
-
-

### Core Concepts

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

### Overview

-
-
-
-

### Integrations

-
-
-

Core Concepts

# Custom Fonts

[Copy for LLMs](https://nuxtseo.com/docs/og-image/guides/custom-fonts.md)

The module bundles Inter (400 and 700) and it works by default with zero configuration.

For any other font, Nuxt OG Image uses the [@nuxt/fonts](https://fonts.nuxt.com) module. **The module does not support any other method of loading custom fonts.**

## [Setup](#setup)

1. Install `@nuxt/fonts`:

```
npx nuxi module add @nuxt/fonts
```

1. Configure your fonts in `nuxt.config.ts`. You must set `global: true` for any font you intend to use in an OG Image.

nuxt.config.ts

```
export default defineNuxtConfig({
  modules: ['@nuxt/fonts', 'nuxt-og-image'],

  fonts: {
    families: [
      { name: 'Roboto', weights: [400, 700], global: true },
    ],
  },
})
```

The `global: true` option is **mandatory**. Without it, the font data will not be available to the OG Image renderer.

## [Usage](#usage)

Once configured, simply use the font family in your component styles:

components/OgImage/MyTemplate.vue

```
<template>
  <div style="font-family: 'Roboto', sans-serif">
    <h1>{{ title }}</h1>
  </div>
</template>
```

## [Advanced Configuration](#advanced-configuration)

### [Provider Configuration](#provider-configuration)

You can use any provider supported by `@nuxt/fonts`:

nuxt.config.ts

```
export default defineNuxtConfig({
  fonts: {
    families: [
      // Google Fonts (default provider)
      { name: 'Roboto', weights: [400, 700], global: true },

      // Explicit provider
      { name: 'Inter', provider: 'bunny', weights: [400, 700], global: true },

      // Local fonts (must be woff2 format)
      {
        name: 'MyFont',
        src: '/fonts/MyFont.woff2',
        weight: 400,
        global: true,
      },
    ],
  },
})
```

### [Font Format Support](#font-format-support)

Different renderers support different font formats:

| Format | Satori | Takumi | Browser |
| --- | --- | --- | --- |
| woff2 | ❌ | ✅ | ✅ |
| woff | ✅ | ❌ | ✅ |
| ttf | ✅ | ✅ | ✅ |
| otf | ✅ | ❌ | ✅ |

When using Google Fonts or other providers, `@nuxt/fonts` automatically fetches the correct format. Format compatibility only matters for local fonts.

## [Troubleshooting](#troubleshooting)

### [Font not rendering](#font-not-rendering)

1. Ensure the font has `global: true` set in your `nuxt.config.ts`.
2. Ensure the font is listed in `fonts.families`.
3. For local fonts, ensure the format matches your renderer (see table above).

### [China/Blocked regions](#chinablocked-regions)

For regions where Google Fonts is blocked, use local fonts or an alternative provider:

```
export default defineNuxtConfig({
  fonts: {
    providers: {
      google: false,
    },
    families: [
      {
        name: 'Inter',
        src: '/fonts/Inter-Regular.woff2',
        weight: 400,
        global: true,
      },
    ],
  }
})
```

## [Why is this required?](#why-is-this-required)

OG Image generation happens in a server-side or build-time environment where the DOM and standard browser font loading are not available. The `@nuxt/fonts` module provides the necessary hooks to resolve, download, and buffer font files so they can be embedded directly into the image generation process (Satori, Takumi, etc.).

Manual font loading, CSS `@font-face` rules in global CSS files, or CDN links **will not work**.

[Edit this page](https://github.com/nuxt-modules/og-image/edit/main/docs/content/3.guides/5.custom-fonts.md)

[Markdown For LLMs](https://nuxtseo.com/docs/og-image/guides/custom-fonts.md)

Did this page help you?

On this page

- [Setup](#setup)
- [Usage](#usage)
- [Advanced Configuration](#advanced-configuration)
- [Troubleshooting](#troubleshooting)
- [Why is this required?](#why-is-this-required)

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