How to Add Custom Fonts to Astro

Astro has a built-in way to add fonts. It takes three steps. You name the font once in your settings. You add one tag to your layout. A layout is the frame that all your pages share. Then you use the font in your CSS. CSS is the code that styles your pages. Astro downloads the font files. It serves them from your own site.

Step 1: Register the font

Open astro.config.mjs. This is your site’s settings file. Add a fonts list. This example uses Inter. It comes from Fontsource, a free font library:

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

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

Want 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. Then 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. Leave it off for fonts that only show up further down the page.

Step 3: Use the font in your CSS

Use the variable anywhere your layout’s styles apply:

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

The sans-serif at the end is a backup. It shows for a moment while the real font loads.

Did you change astro.config.mjs? Then restart the dev server. Now look at your site. The text should change to Inter.

Checking it worked

Run npm run build. A build makes the finished copy of your site. Look in your dist/_astro folder. It will have a fonts folder with the downloaded files. Your pages will also have 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. It then 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.