> ## Documentation Index
> Fetch the complete documentation index at: https://subframe-59800133-apg-edit-updates.mintlify.site/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.

<Note>Custom fonts require a Pro plan. Free plan includes Google Fonts.</Note>

## Uploading fonts

<img src="https://mintcdn.com/subframe-59800133-apg-edit-updates/h3QkDAiIDKnbbMvD/images/theme/theme-custom-fonts.png?fit=max&auto=format&n=h3QkDAiIDKnbbMvD&q=85&s=83656eebab01a81742585525e313c087" 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 **Upload font**
3. Select or drag font files into the dialog
4. Review and edit font metadata:
   * **Font family name** — Editable per font group
   * **Weight** — Dropdown for static fonts, range display for variable fonts
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](/installation#install-fonts) for instructions.

## Updating fonts

To add weights to an existing custom font:

1. Upload additional font files for each new weight
2. Make sure the font family name matches the original font
3. After adding, additional weights will be available for the font

## 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 slider not showing all weights">
    For static fonts, the slider only shows uploaded weights. Upload additional font files to enable more weight options.

    For variable fonts, the slider shows the full supported range 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>