Custom Fonts

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 module. The module does not support any other method of loading custom fonts.

Setup

1. Install @nuxt/fonts:

pnpm exec nuxt module add @nuxt/fonts

Nuxt OG Image v7 requires @nuxt/fonts 1.0.0 or newer. With an older version, OG images use the bundled Inter font.

2. Configure your fonts in nuxt.config.ts. Set global: true for fonts used only in OG images.

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

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

Usage

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

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

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 font files
      {
        name: 'MyFont',
        src: '/fonts/MyFont.woff2',
        weight: 400,
        global: true,
      },
    ],
  },
})

Font Format Support

Different renderers support different font formats:

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:

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.