---
title: "Custom Fonts"
description: "Add Google Fonts or self-hosted fonts to the Topol email Editor. Override default fonts or merge your fonts with existing fonts."
url: https://docs.topol.io/email-editor/guide/custom-fonts.html
---

# Custom Fonts

**The `customFonts` option controls the font dropdown in the editor.** Fonts can be added alongside the built-in list or replace it entirely, whether they come from Google Fonts, your own server, or the operating system.

## How to set custom fonts in the plugin

Add a `customFonts` configuration to your `TOPOL_OPTIONS` object:

```ts
const TOPOL_OPTIONS = {
  // ... other options ...
  customFonts: {
    override: false, // If true, it replaces default fonts. If false, it appends.
    fonts: [
      {
        label: "Mukta", // Name shown in the font selector
        style: "Mukta, sans-serif", // Font stack (MUST include fallback)
        url: "https://fonts.googleapis.com/css2?family=Mukta:wght@400;700", // URL to the font CSS
      },
      {
        label: "Lora",
        style: "'Lora', serif",
        url: "https://fonts.googleapis.com/css2?family=Lora:wght@400;700",
      },
    ],
  },
};
```

> **INFO**
>
> Please keep in mind that font names with space (two or more words), needs to be inside brackets, e.g. `'"Verdana Pro", sans-serif'` or `"'Verdana Pro', sans-serif"`

> **WARNING**
>
> An invalid `fonts` array fails validation as a whole. The editor keeps its default fonts and shows an error notification, so a single malformed entry discards the rest. Fonts are also not stored in the saved template, which means `customFonts` has to be supplied on every initialization.

## Key properties explained

-   `label`: The name users will see in the font dropdown in the editor. Matching it to the first family in `style` keeps the dropdown readable, though the two are independent and nothing enforces the match.

-   `style`: The full CSS font stack (make sure to include fallback fonts like sans-serif, serif, etc.). This is the value written into the template.

-   `url`: The external link to the CSS file for the font, either Google Fonts or a self-hosted stylesheet. **Optional**, and left out for fonts already present on the recipient's system.


## System fonts

Fonts installed on the recipient's device need no stylesheet, so omit `url` entirely:

```ts
customFonts: {
  override: false,
  fonts: [
    {
      label: "Tahoma",
      style: "Tahoma, Geneva, sans-serif",
    },
  ],
},
```

The built-in list works the same way. It holds 15 fonts, of which Arial, Georgia, Helvetica, and Verdana are system fonts with no URL, while Bitter, Cabin, Lato, Merriweather, Open Sans, PT Sans, PT Serif, Roboto, Ubuntu, Poppins, and Oswald load from Google Fonts. Setting `override: true` removes all 15, so include any of them you still want.

## Google Fonts integration

If you're using Google Fonts, just copy the link from the Google Fonts website and paste it into the url field. No need to install anything separately.

If you're also using the image editor, you'll need to provide a separate `googleApiKey` to enable Google Fonts inside images. This is separate from the customFonts setting.

For more information, visit [this article](https://docs.topol.io/email-editor/guide/image-editor.html).

## Self-hosted fonts

> **DANGER**
>
> When working with fonts, always ensure you set suitable web-safe fonts and operating system fonts as fallback options. Custom fonts are significantly limited across various email clients.

If you're using your own font files, you can host the font CSS (using `@font-face` declarations) on your own server and reference it just like you would with a Google Font. Be sure to serve `.woff` or `.woff2` formats for the best compatibility with the few email clients that support custom web fonts.

## Font sizes

The `fontSizes` option sets the sizes offered in the editor's size dropdown, as unitless pixel numbers:

```ts
fontSizes: [12, 14, 16, 18, 24, 32],
```

**This list always replaces the default one**, which is `[11, 12, 13, 14, 15, 16, 17, 18, 20, 22, 24, 30, 36, 48, 64]`. There is no `override` flag. Users can still type any size manually; this only changes the offered presets.