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:

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:

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.

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:

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.