Adding custom fonts

Upload custom font files to use in your theme.

Upload custom font files to use proprietary or licensed fonts in your project.

Uploading fonts

1. Navigate to Theme > Typography
2. Click Custom fonts. If you haven’t added any fonts yet, the upload dialog opens right away. If you already have custom fonts, the manager opens instead. Click Upload fonts to add more.
3. Select or drag font files into the dialog
4. Review each file in the upload table:
   • Font Family — Editable per file; files that share a name become one family
   • Weight — Dropdown for static fonts, range display for variable fonts
   • Style — Detected as Normal or Italic from the file
5. Click Add fonts

Supported formats

File formats: WOFF, WOFF2, TTF, OTF

Font types:

• Static fonts — One file per weight (e.g., MyFont-Regular.woff2, MyFont-Bold.woff2)
• Variable fonts — Single file with weight range support

Font validation

Subframe groups uploaded files by font family. Follow these rules when uploading:

• Same file format — All files in a family must use the same format (don’t mix WOFF and TTF)
• Same font type — Static and variable fonts cannot be mixed in one family
• Unique weights — Each weight must be unique within the family
• No Google Font conflicts — Custom font names cannot match existing Google Font names

If validation fails, edit the font family name or remove conflicting files.

Installing fonts in your codebase

Custom fonts require additional setup in your project to load correctly. See Loading fonts for instructions.

Editing fonts

To change a custom font after adding it:

1. Navigate to Theme > Typography and click Custom fonts
2. Click the edit icon on the font you want to change
3. Add files for new weights or styles, or remove existing ones
4. Save your changes

Removing fonts

1. Navigate to Theme > Typography and click Custom fonts
2. Click the delete icon on the font you want to remove
3. If the font is used anywhere in your theme, pick a replacement before deleting so those styles switch to it

Troubleshooting

Font not appearing in picker

Check that:

• Upload completed successfully (toast notification appeared)
• Font family name doesn’t conflict with Google Fonts
• File format is supported (WOFF, WOFF2, TTF, OTF)

Font not loading in codebase

Verify:

• Font files synced via npx @subframe/cli@latest sync --all
• @font-face declarations are in your CSS
• File paths match actual font file locations
• No CORS errors in browser console

Weight dropdown not showing all weights

For static fonts, the weight dropdown only shows uploaded weights. Upload additional font files to enable more weight options.

For variable fonts, the range comes from the font file metadata.

Can't mix fonts in same family

Remove existing font files or use a different family name. Subframe requires consistent format and type (static vs variable) within each font family.