How to add a new custom font to your site

In short. Custom Fonts lets you upload licensed font files — the ones not on Google Fonts — and register them as named families your design system can pick. You give the family a name, add one Weight block per weight you have files for, point each block at your WOFF2 file in Media, set status to Published or Draft, and click Create a Font. The platform writes the @font-face CSS for you. After saving Published, the font name appears in every typography picker across your site. That's the whole job — the sections below walk through each step and the edge cases worth knowing.

On this page: What this is for · Before you start · Steps · Field reference · What NOT to use this for · Troubleshooting

What is this for?

Custom Fonts is where you upload font files that are not on a public CDN — licensed faces, proprietary typefaces, or self-hosted fonts you want strict control over — and register them as font families your design system can reference. Once you create a custom font and set it to Published, its name appears in every typography picker on your site: theme typography settings, the block editor, and any other surface where you can choose a font.

A custom font in this area is a font family, not a single file. A family can have many weights — Regular at 400, Bold at 700, Semibold at 600. Each weight gets its own block on this form. The platform stitches them into one family, and browsers pick the right weight automatically from your CSS.

The Add New screen is where you start that process for a brand-new family. It's a simple form: a name, one or more weight blocks (each with up to four font file slots), and a status switch. You don't need to know CSS or what @font-face is — the platform writes that for you the first time a public page requests the font.

Scope

The Add New screen (/sg-admin/custom_fonts/add_new) applies to:

• Licensed fonts you host yourself (WOFF2, WOFF, TTF, EOT)
• Single-weight or multi-weight families
• Fonts that should appear site-wide in Appearance → Typography

It does not apply to Google Fonts, external CDN fonts, or icon fonts. Font files must already exist in your Media Library before you can attach them here.

Examples

Single-weight display serif. Upload yourstore-display-serif-400.woff2 to Media, open Add New, name the font, pick the file in the weight 400 slot, set Status to Published, click Create a Font. The font appears in Appearance → Typography on the next page load.

Five-weight workhorse sans. Upload five WOFF2 files (weights 300, 400, 500, 600, 700) to Media in one session, then create a single font with five Weight blocks each pointing at the matching file. One font entry covers all five weights; the browser picks the right one from CSS. Keep all weights inside one font family — not five separate fonts — so the design system can switch between them automatically.

Staging a rebrand as Draft. Create the new font records with all files attached but set Status to Draft so the public site keeps using old fonts. On launch day, flip each font from Draft to Published from the Fonts list.

@font-face { font-family: "Your Store Display Serif"; font-display: swap; font-weight: 400; src: url("/media/yourstore-display-serif-400.woff2") format("woff2");}@font-face { font-family: "Your Store Display Serif"; font-display: swap; font-weight: 700; src: url("/media/yourstore-display-serif-700.woff2") format("woff2");}

Reference

Good use cases

• Licensed display face. Your brand uses a custom serif not on any public CDN. Upload the WOFF2 (and optionally WOFF) to Media, register it as a custom font, set to Published. Headlines across the site switch to the licensed face on the next page load.
• Multi-weight workhorse sans. Your workhorse sans ships in five weights (300, 400, 500, 600, 700). Create one custom font with five Weight blocks. The design system picks the right weight automatically — no synthetic bolding, no manual swaps.
• Staged rebrand. New identity isn't public yet. Upload all new fonts as Draft. On launch day, flip status to Published across the board — no re-uploads needed.
• Scoped display face. A script font only used on product label pages. Register it as Published; the theme team applies it only on the relevant template. It loads globally but renders only where CSS references it.

What NOT to use this for

• Google Fonts and public CDN fonts. Use the typography picker for that service instead — CDN delivery is faster for first-time visitors, and the legal terms are clearer. Never download Inter, Lato, or Roboto and re-upload them here.
• Site-wide CSS. This area only handles font files that become @font-face rules. For colors, classes, or custom styles, use Custom CSS or your theme settings.
• Icon fonts. Icon fonts (ligature tables, unicode ranges) require a different setup not exposed by this form. Talk to whoever built your theme.
• Variable fonts. This form treats each weight as a static choice (100–900). If you have a variable font file, split it into static instances before uploading, or pick one representative weight per block.
• Fonts you don't have a web-embedding license for. The platform will accept the upload, but deploying without rights is a licensing violation. Check your license before publishing.
• OTF files. The form has slots for WOFF2, WOFF, TTF, and EOT — not OTF. Convert OTF to WOFF2 first (free converters are widely available online).

How this connects to other features

• Media library — every file slot points at a media file. Upload font files to Media first, then reference them here. If you delete a font file from Media without removing the reference, the font silently breaks on the public site.
• Typography settings (Appearance / Theme) — once Published, the font name appears in every typography picker your theme exposes. Pick it as your headline or body font and the design system uses your custom files instead of defaults.
• Custom CSS — if your theme has no picker for the place you want to use the font, reference it directly: font-family: "Your Store Display Serif". The font name on this form is the exact CSS string.
• Block editor / Page builder — components with a font selector list your custom fonts alongside system fonts and Google Fonts. No special setup needed beyond Publishing.
• Custom Fonts list — after saving, your font appears on the main list. Edit, swap files, add or remove weights, change status, or trash from there.
• Trash and restore — sending a font to Trash removes it from public delivery but keeps the row for recovery. Full detail: Trash and restore a custom font.

Before you start

• Have WOFF2 files ready. WOFF2 is what every modern browser uses. If your foundry delivered only TTF, convert to WOFF2 first (free tools online), then upload to Media.
• Know how many weights you have files for. You need one Weight block per weight. Two files (Regular + Bold) = two blocks. Nine weights × two styles = eighteen files — plan the session time accordingly.
• Decide the font name before you start. The Title field is the exact string your design system uses. A typo here means the design system references a name that doesn't match what CSS expects. Set a real, descriptive name on first save.
• Confirm your license allows web hosting. Most font licenses distinguish desktop use from web embedding. If unsure, email the foundry.
• Decide Published vs Draft up front. Published means the font goes live the moment you save. Draft lets you preview it before it reaches visitors. Most teams stage as Draft, preview, then publish.

Where to go

Sidebar → Fonts → Add New

Or: open Sidebar → Fonts, then click Add New at the top right of the Fonts list page.

The Add New button sits at the top right, next to the search box. Clicking it opens the blank form.

Steps — Add your first custom font

1. Open the Add New form

Click Fonts in the sidebar. On the Fonts list page, click Add New at the top right. You land on a blank form titled Add a new font, with one Weight block ready. The breadcrumb reads Dashboard / Fonts / New and the submit button reads Create a Font — both confirm you're creating, not editing.

2. Name the font

The Title field is pre-filled with My Font as a placeholder — replace it immediately with the real font name. This name is the exact string the design system uses, so spelling and capitalization matter.

Names that work: "Your Store Display Serif", "Your Store Text", "Inter (self-hosted)". Names to avoid: "My Font", "Font 1", "Display" — too vague to scan once you have more than one font. A good name answers "what is this?" for a teammate six months from now.

3. Add a Weight block for each weight you have files for

Each Weight block has five inputs: Weight (dropdown: 100–900), WOFF2 (strongly recommended), WOFF (optional fallback), TTF (optional legacy), EOT (optional, old IE only). Click Add Another to add a block for the next weight.

Only add blocks for weights you actually have files for. If your font ships in Regular and Bold but not Light, leave Light out — empty blocks contribute nothing.

4. Pick file paths from your Media library

For each Weight block, click into a slot (WOFF2, WOFF, TTF, or EOT). The Media picker opens. Find the file by name and select it — or click Upload inside the picker to add a new file. After selection, the picker closes and the slot shows the filename.

At a minimum, fill the WOFF2 slot for every weight. WOFF, TTF, and EOT are optional.

5. Pick a status — Published or Draft

The Status dropdown defaults to Published.

• Published — the font goes live the moment you click Save. It becomes available in typography pickers across the design system.
• Draft — saved but hidden. The public site doesn't request it. The Fonts list shows a Draft badge.

On a live production site, save as Draft first, preview in a staging page, then flip to Published. On a dev site or when you're confident the font is ready, save as Published directly.

6. Click "Create a Font"

Click the Create a Font button. On success, a green flash says "A font has been successfully created!" and you're redirected to the font's edit page (same form, submit now reads Update a Font). From there you can refine, add weights, or move on.

If the form reloads with an error, the most common cause is a missing or too-short Title (minimum 2 characters). Fix the highlighted issue and click Save again.

What success looks like

After saving with status Published, three things change:

1. The font appears on the Fonts list with its name, created timestamp, and a Published badge.
2. Every public page includes a <style> block in <head> with @font-face rules for your font. Visitors' browsers download the files and render text in your font wherever your design system calls for it.
3. The font name appears in every typography picker your theme exposes — block editor selectors, theme typography settings, and other surfaces.

If you saved as Draft, the font appears on the Fonts list with a Draft badge and the public site does not load it.

The font-display: swap rule means visitors see fallback text immediately, then swap to your font once it loads — no blank page while the font downloads.

Worked example: launching a single-weight display serif

Your Store licensed a custom display serif with web embedding rights for one domain. The foundry shipped one WOFF2 file.

1. Upload yourstore-display-serif-400.woff2 to Media → Add Media.
2. Go to Fonts → Add New.
3. Title: Your Store Display Serif.
4. Weight block: Weight 400 (Regular), WOFF2: pick the file from Media.
5. Status: Published.
6. Click Create a Font.

Result: every public page now includes one @font-face rule for the new font. The theme — already configured to use it as its headline font — renders headlines in the licensed face on every visit. The font appears as a pickable option in the block editor and theme typography settings.

Subtle catch: because only Regular (400) is loaded, any CSS that asks for Bold (700) will get a synthetic-bold rendering of 400, which often looks wrong. Either tell your theme not to bold headline text, or license a Bold weight and add a second Weight block.

What to do if it does not work

• The Add New page won't load. Refresh. If you land on a login screen, your session timed out — log back in and try again.
• You clicked Save and nothing happened. Look for a red error banner at the top. The most common cause is a missing or too-short Title (minimum 2 characters). Fix and click Save again.
• "Successfully created" but the font doesn't show on the public site. Confirm status is Published, not Draft. If it is Published, refresh the public page in a private/incognito window — browsers sometimes cache the previous page for a few minutes.
• The font shows in pickers but pages still render a fallback font. The file path is likely wrong. Open the font's edit page, confirm each Weight block's WOFF2 slot points at a real file in Media, and re-save. View the page source and search for @font-face — the src: url(..) should point at a real file, not an empty string.
• Only Regular (400) renders; Bold looks synthetic. You only added a 400 Weight block but CSS is requesting 700. Open the font's edit page, add a Weight block for 700 with the correct WOFF2 file, save.
• You uploaded the wrong file. Open the font's edit page, click the slot, pick the right file from Media, save. The old file stays in Media and can be deleted later.
• You can't find your font file in the Media picker. Go to Media and search for the filename to confirm the upload succeeded. If it's missing, re-upload. If it's there, search the picker by filename.
• The Add Another button isn't responding. JavaScript may be disabled or an extension is blocking form scripts. Disable extensions and refresh, or try a different browser.

Common pitfalls

• Saving with the placeholder name "My Font". Fix: open the font, change the Title, save. Any CSS hardcoding the old name will need a one-time update.
• Marking all weights as 400. The browser only uses the first match — the others are wasted. Fix: set each block's weight dropdown to its true numeric value.
• Uploading TTF instead of WOFF2. TTF files are 2–4× larger. Convert to WOFF2, upload to Media, re-pick in the font form.
• Deleting a font file from Media without removing the reference here. The @font-face rule survives but its src points at a missing file — visitors see fallback text. Fix: re-pick a valid file on the font's edit page, or delete the font row entirely.

Next steps

• Head to your theme typography settings to pick the new font as your headline or body font. Saving the font here makes it available; the theme picker is where it gets applied.
• Read Edit an existing custom font to learn how to update weights, swap files, rename, or change status.
• Read Find and review all custom fonts to learn how to filter, search, and manage your font list.
• If you're staging a rebrand, read the Bulk actions on the Fonts list doc to flip many fonts from Draft to Published in one operation.
• If you deleted a font by mistake, read Trash and restore a custom font — most deletes are recoverable.