Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Styling and Assets

Fonts, Icons and Static Assets in Astro

Load web fonts without layout jumps, use SVG icons as components, understand the public folder, hashed asset names and the build output in Astro.

Beyond CSS and photos, every site ships fonts, icons, downloads and favicons. Astro gives you several ways to handle them. This lesson explains how to load fonts quickly, how to use SVG icons, what the public/ folder is for, and why built files get names like hero.a1b2c3d4.js.

Self-hosting fonts

Fonts from a third-party CDN need an extra DNS lookup and connection. Self-hosting is faster, more private, and works with strict content security policies. The simplest route is a Fontsource package:

Terminal
npm install @fontsource-variable/inter
ASTRO
---
// src/layouts/Base.astro
import '@fontsource-variable/inter';
---
<style is:global>
  body { font-family: 'Inter Variable', system-ui, sans-serif; }
</style>

The import adds @font-face rules and Vite bundles the font files with hashed names. A variable font holds many weights in one file, which usually beats loading separate files for 400, 500 and 700.

Astro also offers a built-in Fonts API (check the docs for the status in your version) that configures providers in astro.config.mjs, generates the @font-face rules, and can add preload hints and metrics-matched fallbacks for you.

Avoiding layout shift from fonts

When a web font arrives late, text can jump. Three tools keep it calm:

  1. font-display: swap shows fallback text immediately (Fontsource uses it).
  2. A fallback font adjusted to the same metrics, with size-adjust, ascent-override and friends.
  3. A preload for the one font that matters above the fold:
ASTRO
---
import interUrl from '@fontsource-variable/inter/files/inter-latin-wght-normal.woff2?url';
---
<link rel="preload" href={interUrl} as="font" type="font/woff2" crossorigin />

Preload only one or two fonts; preloading everything delays the rest of the page. Use WOFF2 only, and subset to the character sets you need (Latin, for example).

System font stacks

The fastest font is the one you do not download. A modern system stack looks good on every platform:

CSS
body {
  font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
}
code {
  font-family: ui-monospace, 'Cascadia Code', Menlo, monospace;
}

SVG icons

There are three good ways to show icons.

1. Inline SVG in a component. You own the markup, you can colour it with currentColor, and there is no request:

ASTRO
---
// src/components/IconArrow.astro
const { size = 20 } = Astro.props;
---
<svg width={size} height={size} viewBox="0 0 24 24" fill="none"
     stroke="currentColor" stroke-width="2" aria-hidden="true">
  <path d="M5 12h14M13 6l6 6-6 6" />
</svg>

2. An icon package. Packages such as astro-icon or unplugin-icons turn icon sets into components. Only the icons you use are bundled.

3. An image. <img src="/logo.svg"> works, but you cannot recolour it with CSS.

Rules that apply to all of them: decorative icons get aria-hidden="true"; an icon that is the only content of a button needs an accessible name (aria-label or visually hidden text).

The public folder

Everything in public/ is copied to the output root untouched:

TEXT
public/
  favicon.svg      -> /favicon.svg
  robots.txt       -> /robots.txt
  downloads/
    guide.pdf      -> /downloads/guide.pdf

Use it for files that need a fixed URL or that you do not want processed. Reference them with absolute paths from the site root (/favicon.svg), never with ../public/. If the site is hosted under a subpath, use import.meta.env.BASE_URL to prefix them.

Files in public/ do not get content hashes, so if you replace a file, browsers and CDNs can serve the old copy until the cache expires. That is why processed assets are better when you can use them.

Hashed assets and the build output

Run astro build and look at dist/:

TEXT
dist/
  index.html
  _astro/
    hero.Bv3k9qLc_Z1xT2a.webp
    index.DfX8m1Qp.css
    Counter.Cz91kd0w.js

Everything under _astro/ has a hash in its name derived from the content. Content changes, the name changes; content is the same, the name is the same. That lets servers send Cache-Control: public, max-age=31536000, immutable for /_astro/*, so repeat visitors never re-download unchanged files, and deploys never serve a stale one.

You can change the folder name with build.assets.

Linking assets from content

  • In .astro files, import to get the hashed URL: import pdf from '../assets/guide.pdf'.
  • In Markdown, relative image paths are processed; links to /downloads/... point at public/.
  • In CSS, url(./bg.png) is resolved by Vite and hashed.

Try it: content hashing

This stand-in computes a short hash of file contents, like the build does, so you can see why a changed file gets a new name and an unchanged one keeps it.

JS Hashed file names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first two lines are identical; the third differs.

Try it: a cache policy by path

Hashed files can be cached forever, HTML must not be. This stand-in turns that rule into code, the same logic you would put in a _headers file or server config.

JS Cache-Control by URL

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is an advantage of a variable font?

    A variable font stores a range of weights (and sometimes widths) in a single file, which can replace several static files.
  2. 2. Which URL is correct for public/favicon.svg?

    public/ is copied to the output root, so the folder name disappears from the URL.
  3. 3. Why can files in /_astro/ be cached for a year?

    A new build with different content yields a different file name, so a long immutable cache never serves a stale file.
  4. 4. An icon-only button needs what for accessibility?

    Screen readers need text for the button. The decorative icon itself should be hidden with aria-hidden.

Summary

  • Self-host fonts (Fontsource or the Fonts API), prefer WOFF2 and variable fonts, preload at most one or two.
  • System font stacks cost nothing.
  • Inline SVG components give recolourable, request-free icons; mind accessibility.
  • public/ is copied as is and not hashed; src/ assets get content-hashed names under _astro/.
  • Hashed files can use immutable one-year caching; HTML should revalidate.

Next: Adding Integrations