Using custom fonts

Astro supports all common strategies for adding custom typefaces to your site design. This guide will show you two different options for including web fonts in your project.

If you want to add font files to your project, we recommend adding them to your public/ directory. In your CSS you can then register fonts with an @font-face statement and use the font-family property to style your site.

Let’s imagine you have a DistantGalaxy.woff font file.

1. Add your font file to public/fonts/.

2. Add an @font-face statement to your CSS. This could be in a global .css file you import or in a <style> block in the layout or component where you want to use this font.

   /* Register our custom font family and tell the browser where to find it. */
   @font-face {
     font-family: 'DistantGalaxy';
     src: url('/fonts/DistantGalaxy.woff') format('woff');
     font-weight: normal;
     font-style: normal;
     font-display: swap;
   }

3. Use the font-family from the @font-face statement to style elements in your component or layout. In this example, the <h1> heading will have the custom font applied, while the paragraph <p> will not.

   ---
   ---
   
   <h1>In a galaxy far, far away...</h1>
   
   <p>Custom fonts make my headings much cooler!</p>
   
   <style>
   h1 {
     font-family: 'DistantGalaxy', sans-serif;
   }
   </style>

The Fontsource project simplifies using Google Fonts and other open source fonts. It provides npm modules you can install for the fonts you want to use.

1. Find the font you want to use in Fontsource’s catalog. For this example, we’ll use Twinkle Star.

2. Install the package for your chosen font.

   npmpnpmYarn

   npm install @fontsource/twinkle-star

3. Import the font package in the layout or component where you want to use the font. Usually, you will want to do this in a common layout component to make sure the font is available across your site.

   The import will automatically add the necessary @font-face rules needed to set up the font.

   ---
   import '@fontsource/twinkle-star';
   ---

4. Use the font-family as shown on that font’s Fontsource page. This will work anywhere you can write CSS in your Astro project.

   h1 {
     font-family: "Twinkle Star", cursive;
   }

If you are using the Tailwind integration, you can either add an @font-face statement for a local font or use Fontsource’s import strategy to register your font.

1. Follow either of the guides above, but skip the final step of adding font-family to your CSS.

2. Add the typeface name to tailwind.config.cjs.

   This example adds InterVariable and Inter to the sans-serif font stack, with default fallback fonts from Tailwind CSS.

   const defaultTheme = require("tailwindcss/defaultTheme");
   
   module.exports = {
     // ...
     theme: {
       extend: {
         fontFamily: {
           sans: ["InterVariable", "Inter", ...defaultTheme.fontFamily.sans],
         },
       },
     },
     // ...
   };

   Now, all sans-serif text (the default with Tailwind) in your project will use your chosen font and the font-sans class will also apply the Inter font.

See Tailwind’s docs on adding custom font families for more information.

MDN’s web fonts guide introduces the topic.

Font Squirrel’s Webfont Generator can help prepare your font files for you.