> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subframe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<img src="https://mintcdn.com/subframe-59800133/7Ln4MiKMuNPz2Ss7/images/theme/theme-custom-fonts.png?fit=max&auto=format&n=7Ln4MiKMuNPz2Ss7&q=85&s=082c28df1c5d6ab3ce7246a1d8857c50" alt="Dialog showing a list of fonts uploaded for review" width="1920" height="1440" data-path="images/theme/theme-custom-fonts.png" />

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](/develop/installation#install-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

<AccordionGroup>
  <Accordion title="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)
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


## Related topics

- [Adding custom fonts](/learn/theme/adding-custom-fonts.md)
- [Customizing theme](/learn/theme/customizing-theme.md)
- [Custom CSS](/learn/design-mode/custom-css.md)