How to Add Custom Fonts to Astro

Astro has a built-in way to add fonts. You name the font once in your config, add one tag to your layout, and use it in your CSS. Astro downloads the files and serves them from your site.

Step 1: Register the font

Open astro.config.mjs and add a fonts list. This example uses Inter from Fontsource, a free font library:

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

export default defineConfig({
  fonts: [
    {
      provider: fontProviders.fontsource(),
      name: 'Inter',
      cssVariable: '--font-inter',
    },
  ],
});

To use Google Fonts instead, swap in fontProviders.google(). The rest stays the same.

Step 2: Add the Font tag to your layout

Open src/layouts/Layout.astro, import the component, and add it inside <head>:

---
import { Font } from 'astro:assets';
---
<html lang="en">
  <head>
    <Font cssVariable="--font-inter" preload />
  </head>
  <body>
    <slot />
  </body>
</html>

The preload option tells the browser to fetch the font early. Use it for your main text font, and leave it off for fonts that only appear further down the page.

Step 3: Use the font in your CSS

Anywhere your layout’s styles apply, use the variable:

body {
  font-family: var(--font-inter), sans-serif;
}

The sans-serif at the end is a fallback, shown for a moment while the real font loads.

Restart the dev server after changing astro.config.mjs, then look at your site. The text should change to Inter.

Checking it worked

Run npm run build. Your dist/_astro folder will contain a fonts folder with the downloaded files, and your pages will include the @font-face rules that point at them.

Frequently asked questions

Does this load fonts from Google's servers?

No. Astro downloads the font files when your site builds and serves them from your own site. Visitors never connect to Google.

Can I use a font file I already have?

Yes. Use the local provider and point it at your font files. The Astro docs show the exact settings.