Custom Fonts

Customize your app’s typography with custom fonts.

Google Fonts

The easiest way to add fonts:

"Change the heading font to Inter and body font to Roboto
using Google Fonts"

Implementation

Add the Google Fonts <link> tags in the <head> of your base layout:

---
// src/layouts/Base.astro
---
<html lang="en">
  <head>
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link
      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;700&family=Roboto:wght@400;500;700&display=swap"
      rel="stylesheet"
    />
  </head>
  <body>
    <slot />
  </body>
</html>

Using in Tailwind

Map the fonts to Tailwind font families so you can use utility classes:

/* src/styles/global.css */
@theme {
  --font-sans: "Inter", system-ui, sans-serif;
  --font-heading: "Roboto", system-ui, sans-serif;
}

Then use in components:

<h1 class="font-heading">Heading</h1>
<p class="font-sans">Body text</p>

Popular Font Combinations

Modern & Clean

Headings: Inter
Body: Inter

Professional

Headings: Poppins
Body: Open Sans

Creative

Headings: Playfair Display
Body: Lato

Tech/Startup

Headings: Space Grotesk
Body: DM Sans

Local Fonts

For fonts not on Google Fonts:

Add Font Files

Place in public/fonts/:

public/
  fonts/
    MyFont-Regular.woff2
    MyFont-Bold.woff2

Configure

Declare the font with @font-face in your global stylesheet, pointing at the files in public/ (served from the site root):

/* src/styles/global.css */
@font-face {
  font-family: "MyFont";
  src: url("/fonts/MyFont-Regular.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: "MyFont";
  src: url("/fonts/MyFont-Bold.woff2") format("woff2");
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}

@theme {
  --font-brand: "MyFont", system-ui, sans-serif;
}

Then use class="font-brand" on your headings or body text.

Font Weights

Common weight names:

Weight	Name
100	Thin
200	Extra Light
300	Light
400	Regular
500	Medium
600	Semi Bold
700	Bold
800	Extra Bold
900	Black

Loading Specific Weights

Only load what you need for better performance. Request just those weights in your Google Fonts <link> URL:

https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap

Font Performance

Optimization Tips

Load only needed weights - Don’t load all weights
Limit font families - 2-3 max
Use font-display: swap - Shows fallback while loading
Subset fonts - Only latin if that’s all you need

Reduce Layout Shift

To keep fonts fast and avoid layout shift:

Self-host the .woff2 files in public/fonts/ (no external request) when you want zero third-party calls
Preconnect / preload the font in your base layout’s <head>
Use font-display: swap so text shows in a fallback while the font loads
Set a matching fallback font family so the swap is barely noticeable

Typography Scale

Consistent Sizing

Use Tailwind’s typography scale:

Class	Size
`text-xs`	12px
`text-sm`	14px
`text-base`	16px
`text-lg`	18px
`text-xl`	20px
`text-2xl`	24px
`text-3xl`	30px
`text-4xl`	36px
`text-5xl`	48px

Custom Scale

/* src/styles/global.css */
@theme {
  --text-hero: 4.5rem;
  --text-hero--line-height: 1.1;
  --text-subtitle: 1.25rem;
  --text-subtitle--line-height: 1.6;
}

Line Height & Spacing

Line Height

<p class="leading-relaxed">Comfortable reading</p>
<p class="leading-tight">Compact text</p>

Letter Spacing

<h1 class="tracking-tight">Tight headings</h1>
<span class="tracking-wide uppercase">Labels</span>

Common Font Tasks

Change All Fonts

"Change the app's primary font to Poppins for headings
and Inter for body text"

Consistent Typography

"Create a consistent typography system with h1-h6 styles,
body text, and small text"

Brand Font

"I have a brand font file (BrandFont.woff2). Add it as
the primary heading font."

Font Fallbacks

Always specify fallbacks in your Tailwind theme:

/* src/styles/global.css */
@theme {
  --font-sans: "Inter", system-ui, sans-serif;
  --font-serif: Georgia, serif;
  --font-mono: "Fira Code", monospace;
}

Variable Fonts

Modern fonts with adjustable properties. Load the single variable .woff2 and declare a weight range with @font-face:

/* src/styles/global.css */
@font-face {
  font-family: "Inter";
  src: url("/fonts/Inter-Variable.woff2") format("woff2");
  font-weight: 100 900; /* full range in one file */
  font-display: swap;
}

Benefits:

Smaller file size
All weights in one file
Smooth weight transitions

Troubleshooting

Font not loading

Check font name spelling (must match the @font-face/<link> exactly)
Verify the weight exists for that font
Check the browser console for errors
Ensure the <link> is in the base layout <head>, or the font file exists in public/fonts/

Flash of unstyled text

Make sure font-display: swap is set (in the Google Fonts URL or your @font-face)
Preconnect/preload the font in the base layout <head>
Set a matching fallback font family so the swap is barely noticeable

Font looks different than expected

Verify you loaded the correct weight
Check CSS isn’t overriding font settings
Ensure the Tailwind font family (e.g. font-heading) is applied to your element

Styling Best Practices

More design tips

Prompt Engineering

Best Practices

Advanced

Migration & Hosting

Resources

Google Fonts

Implementation

Using in Tailwind

Popular Font Combinations

Modern & Clean

Professional

Creative

Tech/Startup

Local Fonts

Add Font Files

Configure

Font Weights

Loading Specific Weights

Font Performance

Optimization Tips

Reduce Layout Shift

Typography Scale

Consistent Sizing

Custom Scale

Line Height & Spacing

Line Height

Letter Spacing

Common Font Tasks

Change All Fonts

Consistent Typography

Brand Font

Font Fallbacks

Variable Fonts

Troubleshooting

Styling Best Practices

​Google Fonts

​Implementation

​Using in Tailwind

​Popular Font Combinations

​Modern & Clean

​Professional

​Creative

​Tech/Startup

​Local Fonts

​Add Font Files

​Configure

​Font Weights

​Loading Specific Weights

​Font Performance

​Optimization Tips

​Reduce Layout Shift

​Typography Scale

​Consistent Sizing

​Custom Scale

​Line Height & Spacing

​Line Height

​Letter Spacing

​Common Font Tasks

​Change All Fonts

​Consistent Typography

​Brand Font

​Font Fallbacks

​Variable Fonts

​Troubleshooting

Styling Best Practices

Google Fonts

Implementation

Using in Tailwind

Popular Font Combinations

Modern & Clean

Professional

Creative

Tech/Startup

Local Fonts

Add Font Files

Configure

Font Weights

Loading Specific Weights

Font Performance

Optimization Tips

Reduce Layout Shift

Typography Scale

Consistent Sizing

Custom Scale

Line Height & Spacing

Line Height

Letter Spacing

Common Font Tasks

Change All Fonts

Consistent Typography

Brand Font

Font Fallbacks

Variable Fonts

Troubleshooting