How to Change the Font in Your Weaverse Theme

Weaverse themes use modern font loading techniques for performance and flexibility. The default Pilot theme uses Fontsource for Google Fonts, but you can use any web font provider or upload custom fonts. This guide covers all approaches with practical examples.

Pilot uses Tailwind CSS v4, which is configured CSS-first through the @theme directive. There is no tailwind.config.js file — the Tailwind plugin is registered in vite.config.ts and all design tokens live in app/styles/theme.css.

1. Using Fontsource (Recommended)

Fontsource provides npm packages for hundreds of Google Fonts and more, including support for variable fonts.

a. Install the Fontsource Package

Pilot ships with two variable fonts:

"@fontsource-variable/cabin": "^5.2.8",
"@fontsource-variable/newsreader": "^5.2.10"

To use a different font (for example the variable font Nunito Sans):

npm install @fontsource-variable/nunito-sans
# or a static-weight font
npm install @fontsource/inter

Find the package for your font at fontsource.org.

b. Import Font Files in root.tsx

Pilot imports its fonts at the very top of app/root.tsx:

import "@fontsource-variable/cabin"; // Supports weights 400-700
import "@fontsource-variable/newsreader"; // Supports weights 200-900

Replace those imports with your own:

import "@fontsource-variable/nunito-sans";

For static-weight packages, import only the weights you actually use:

import "@fontsource/inter/400.css";
import "@fontsource/inter/500.css";
import "@fontsource/inter/700.css";

c. Update the `@theme` Font Variables

Tailwind v4 derives font-sans, font-serif, and font-mono utilities from CSS variables. Pilot declares them at the top of app/styles/theme.css:

@theme {
  --font-sans: Cabin Variable, ui-sans-serif, system-ui, sans-serif;
  --font-serif: Newsreader Variable, ui-serif, Georgia, serif;
}

Point them at your new font:

@theme {
  --font-sans: Nunito Sans Variable, ui-sans-serif, system-ui, sans-serif;
  --font-serif: Newsreader Variable, ui-serif, Georgia, serif;
}

Tip: The first value must match the font-family name published by the font provider (Fontsource variable packages append Variable to the family name) or the name in your own @font-face declaration. app/styles/theme.css is pulled in by app/styles/app.css, which is where Tailwind itself is imported:

@import "tailwindcss" source("../../app");
@plugin "@tailwindcss/typography";

@import "./theme.css";

d. Set a Base Font in Global CSS (if needed)

Utilities such as font-sans already resolve to your @theme value, so this is only needed if you want a default outside of Tailwind utilities:

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

For variable fonts you can also pin a default weight axis:

body {
  font-variation-settings: "wght" 400;
}

2. Using Google Fonts CDN

For a quick setup, add a <link> to the document head in app/root.tsx (or through the links export):

<link href="https://fonts.googleapis.com/css?family=Roboto:400,700&display=swap" rel="stylesheet" />

Then point the theme variable at it in app/styles/theme.css:

@theme {
  --font-sans: Roboto, ui-sans-serif, system-ui, sans-serif;
}

CSP Reminder: If you load fonts from an external CDN (such as Google Fonts), make sure to update your Content Security Policy (CSP) to allow the font and stylesheet sources. See the CSP guide for details and examples.

3. Uploading a Custom Font

a. Add Font Files to the Public Folder

Place .woff2, .woff, or .ttf files in public/fonts/.

b. Declare @font-face in CSS

@font-face {
  font-family: "MyCustomFont";
  src: url("/fonts/MyCustomFont.woff2") format("woff2"),
       url("/fonts/MyCustomFont.woff") format("woff");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

c. Register It in `@theme`

@theme {
  --font-sans: MyCustomFont, ui-sans-serif, system-ui, sans-serif;
}

4. Switching Fonts Dynamically (Optional)

To let merchants select fonts in Weaverse Studio:

Add a font selector input in your theme schema (see app/weaverse/schema.server.ts).
Use the selected value to set the font-family dynamically in your global style component, which writes CSS custom properties into the document.

See Styling & Theming for how Pilot injects theme settings as CSS variables.

5. Best Practices

Only load the weights/styles you use.
Use font-display: swap for performance.
Prefer .woff2 for custom fonts.
Test on all devices and browsers.
Respect font licensing for custom fonts.

6. Example: Changing to Inter Using Fontsource

// 1. Install: npm install @fontsource/inter
// 2. app/root.tsx — replace Pilot's font imports:
import "@fontsource/inter/400.css";
import "@fontsource/inter/500.css";
import "@fontsource/inter/700.css";

/* 3. app/styles/theme.css */
@theme {
  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
}

7. Example: Using a Variable Font

// 1. Install: npm install @fontsource-variable/nunito-sans
// 2. app/root.tsx
import "@fontsource-variable/nunito-sans";

/* 3. app/styles/theme.css */
@theme {
  --font-sans: Nunito Sans Variable, ui-sans-serif, system-ui, sans-serif;
}

Overview

Developer Tools

APIs

Hydrogen Themes

Hydrogen Integrations

Migration

How to Change the Font in Your Weaverse Theme

How to Change the Font in Your Weaverse Theme

1. Using Fontsource (Recommended)

a. Install the Fontsource Package

b. Import Font Files in root.tsx

c. Update the `@theme` Font Variables

d. Set a Base Font in Global CSS (if needed)

2. Using Google Fonts CDN

3. Uploading a Custom Font

a. Add Font Files to the Public Folder

b. Declare @font-face in CSS

c. Register It in `@theme`

4. Switching Fonts Dynamically (Optional)

5. Best Practices

6. Example: Changing to Inter Using Fontsource

7. Example: Using a Variable Font

8. Further Reading

​How to Change the Font in Your Weaverse Theme

​1. Using Fontsource (Recommended)

​a. Install the Fontsource Package

​b. Import Font Files in root.tsx

​c. Update the @theme Font Variables

​d. Set a Base Font in Global CSS (if needed)

​2. Using Google Fonts CDN

​3. Uploading a Custom Font

​a. Add Font Files to the Public Folder

​b. Declare @font-face in CSS

​c. Register It in @theme

​4. Switching Fonts Dynamically (Optional)

​5. Best Practices

​6. Example: Changing to Inter Using Fontsource

​7. Example: Using a Variable Font

​8. Further Reading

How to Change the Font in Your Weaverse Theme

1. Using Fontsource (Recommended)

a. Install the Fontsource Package

b. Import Font Files in root.tsx

c. Update the `@theme` Font Variables

d. Set a Base Font in Global CSS (if needed)

2. Using Google Fonts CDN

3. Uploading a Custom Font

a. Add Font Files to the Public Folder

b. Declare @font-face in CSS

c. Register It in `@theme`

4. Switching Fonts Dynamically (Optional)

5. Best Practices

6. Example: Changing to Inter Using Fontsource

7. Example: Using a Variable Font

8. Further Reading