---
title: "Custom Fonts"
description: "Using custom fonts in your OG Images."
canonical_url: "https://nuxtseo.com/docs/og-image/guides/custom-fonts"
last_updated: "2026-05-09T16:48:36.824Z"
---

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

1. Install `@nuxt/fonts`:

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

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

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

<note>

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

</note>

## Usage

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

```vue [components/OgImage/MyTemplate.vue]
<template>
  <div style="font-family: 'Roboto', sans-serif">
    <h1>{{ title }}</h1>
  </div>
</template>
```

## Advanced Configuration

### Provider Configuration

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

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

Different renderers support different font formats:

<table>
<thead>
  <tr>
    <th>
      Format
    </th>
    
    <th>
      Satori
    </th>
    
    <th>
      Takumi
    </th>
    
    <th>
      Browser
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      woff2
    </td>
    
    <td>
      ❌
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      woff
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ❌
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      ttf
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      otf
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ❌
    </td>
    
    <td>
      ✅
    </td>
  </tr>
</tbody>
</table>

<note>

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

</note>

## Troubleshooting

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

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

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

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