Astro 6 Font API: Complete Guide to Modern Font Loading

TL;DR: Astro 6 introduces a new Font API that moves font configuration from CSS to astro.config.mjs. Fonts are now declared once, automatically optimized, and used via CSS variables. No more @fontsource imports or manual fallback stacks.

The Problem: Old Font Loading Was Messy

Before Astro 6, loading fonts meant:

Installing @fontsource-variable/inter (or similar)
Importing in your layout: import '@fontsource-variable/inter'
Adding to CSS: font-family: 'Inter Variable', system-ui, sans-serif
Managing fallbacks manually
Hoping for the best with performance

This worked, but it scattered font configuration across multiple files and required manual optimization.

Astro 6’s Solution: Declarative Font Configuration

Astro 6 moves font loading to astro.config.mjs with automatic optimization, subset loading, and metric-matched fallbacks.

Step 1: Configure Fonts in `astro.config.mjs`

1
import { defineConfig, fontProviders } from 'astro/config';
2

3
export default defineConfig({
4
  site: 'https://your-site.com',
5
  fonts: [
6
    {
7
      name: 'Inter',                    // Font name from fontsource
8
      cssVariable: '--font-inter',      // CSS variable to create
9
      provider: fontProviders.fontsource(),
10
      subsets: ['latin'],               // Only load characters you need
11
    },
12
  ],
13
});

What this does:

Downloads Inter from fontsource
Creates CSS variable --font-inter
Loads only Latin subset (smaller file)
Generates optimized fallbacks automatically

Step 2: Add `<Font>` Component to Your Layout

1
---
2
import { Font } from 'astro:assets';
3
---
4

5
<html>
6
  <head>
7
    <!-- Other meta tags -->
8
    <Font cssVariable="--font-inter" />
9
  </head>
10
  <body>
11
    <slot />
12
  </body>
13
</html>

Important: The <Font> component doesn’t need a family prop. Astro already knows which font from your config.

Step 3: Use the Font in CSS

1
body {
2
  font-family: var(--font-inter);
3
  /* That's it. No fallbacks. No font stacks. */
4
}

Why no fallbacks? Astro’s optimizedFallbacks: true (default) automatically generates metric-matched fallback fonts. The CSS variable is all you need.

Complete Example: Our Blog Setup

Here’s the exact configuration we use for this blog:

astro.config.mjs

1
import { defineConfig, fontProviders } from 'astro/config';
2
import tailwindcss from '@tailwindcss/vite';
3

4
export default defineConfig({
5
  site: 'https://ai-suka.pages.dev',
6
  fonts: [
7
    {
8
      name: 'Inter',
9
      cssVariable: '--font-inter',
10
      provider: fontProviders.fontsource(),
11
      subsets: ['latin'],
12
    },
13
  ],
14
  integrations: [tailwindcss()],
15
});

src/layouts/BaseHead.astro

1
---
2
import '../styles/global.css';
3
import { Font } from 'astro:assets';
4
---
5

6
<html lang="en">
7
  <head>
8
    <meta charset="utf-8" />
9
    <meta name="viewport" content="width=device-width,initial-scale=1" />
10
    <Font cssVariable="--font-inter" />
11
  </head>
12
  <body>
13
    <slot />
14
  </body>
15
</html>

src/styles/global.css

1
@import 'tailwindcss';
2

3
body {
4
  font-family: var(--font-inter);
5
  margin: 0;
6
  padding: 0;
7
  font-size: 18px;
8
  line-height: 1.7;
9
}

Font Providers

Astro 6 supports multiple font providers:

Provider	Use Case	Example
`fontProviders.fontsource()`	Self-hosted via @fontsource	Most common
`fontProviders.google()`	Google Fonts CDN	Faster for global audiences
`fontProviders.local()`	Your own font files	Custom fonts

Google Fonts Example

1
fonts: [
2
  {
3
    name: 'Roboto',
4
    cssVariable: '--font-roboto',
5
    provider: fontProviders.google(),
6
    subsets: ['latin'],
7
  },
8
],

Local Fonts Example

1
fonts: [
2
  {
3
    name: 'CustomFont',
4
    cssVariable: '--font-custom',
5
    provider: fontProviders.local({
6
      src: './src/fonts/CustomFont.woff2',
7
    }),
8
  },
9
],

Advanced Configuration

Multiple Fonts

1
fonts: [
2
  {
3
    name: 'Inter',
4
    cssVariable: '--font-inter',
5
    provider: fontProviders.fontsource(),
6
    subsets: ['latin'],
7
  },
8
  {
9
    name: 'JetBrains Mono',
10
    cssVariable: '--font-mono',
11
    provider: fontProviders.fontsource(),
12
    subsets: ['latin'],
13
  },
14
],

Then use in CSS:

1
body {
2
  font-family: var(--font-inter);
3
}
4

5
code, pre {
6
  font-family: var(--font-mono);
7
}

Custom Fallbacks

1
fonts: [
2
  {
3
    name: 'Inter',
4
    cssVariable: '--font-inter',
5
    provider: fontProviders.fontsource(),
6
    fallbacks: ['Inter', 'sans-serif'],  // Override default
7
    optimizedFallbacks: false,           // Disable metric matching
8
  },
9
],

Disable Fallbacks Entirely

1
fonts: [
2
  {
3
    name: 'Inter',
4
    cssVariable: '--font-inter',
5
    provider: fontProviders.fontsource(),
6
    fallbacks: [],  // No fallbacks
7
  },
8
],

Migration Checklist: From Old to New

If you’re migrating from Astro 5 or earlier:

Remove @fontsource-variable/xxx from dependencies
Add font config to astro.config.mjs
Replace import '@fontsource/...' with <Font> component
Update CSS from font-family: 'Font Name' to var(--font-*)
Remove manual fallback stacks from CSS

Performance Benefits

Astro 6’s Font API provides:

Feature	Benefit
Subset loading	Only download characters you need (latin, cyrillic, etc.)
Optimized fallbacks	Metric-matched fallbacks prevent layout shift
Self-hosted	Fonts served from your domain (better privacy, faster)
Automatic optimization	No manual `font-display` or preload configuration

Common Mistakes

❌ Wrong: Adding fallbacks in CSS

1
body {
2
  font-family: var(--font-inter), system-ui, sans-serif;
3
}

Fix: Remove fallbacks. They’re configured in astro.config.mjs.

❌ Wrong: Using font family name in `<Font>`

1
<Font family="Inter" cssVariable="--font-inter" />

Fix: Remove family prop. Astro uses config name.

❌ Wrong: Wrong font name

1
fonts: [{
2
  name: 'Inter Variable',  // ❌ Wrong
3
  cssVariable: '--font-inter',
4
}]

Fix: Use exact fontsource package name:

1
fonts: [{
2
  name: 'Inter',  // ✅ Correct
3
  cssVariable: '--font-inter',
4
}]