📝 NOTE: If you're already using a custom font and are having trouble with it, check the troubleshooting section of this article.
Configuring the font
Set Body font family
global.fonts.families.body
This will be globally applied. However, it might still be possible to apply a different font to some sections, e.g., banner.title.font.family
Note that this is an array.
Set font sizes
global.fonts.size.largeglobal.fonts.size.mediumglobal.fonts.size.small
Set font weights
If you load a custom font, you must be sure to load the desired font weights and set these variables accordingly if they do not match your font.
global.fonts.weights.normalglobal.fonts.weights.semiBoldglobal.fonts.weights.bold
Custom fonts through UI vars
The custom fonts through the UI are loaded differently. This is what happens under the hood. Note, however, the above configurations still apply, but it's loading the data a different way.
Force Google font (if using build in Google fonts)
global.fonts.googleFontFamily
Font Family Name (must match CSS font family name)
global.fonts.customFont.name
Font URL
This should be an external URL to a CSS file that imports your fonts.
📝 NOTE: This is not the URL to the font, but to a CSS file that calls in fonts; it is hosted somewhere other than on Vanilla infrastructure.
global.fonts.customFont.url
Font CSS file
The global.fonts.customFont.url variable calls a CSS file that will have one or more font-face rules. ✔️ TIP: For more information, see this article about @font-face rules.
For example, global.fonts.customFont.url could call the CSS file https://assets.mysite.com/css/webfonts.css, which might contain code similar to that shown in the following example:
⚠️ IMPORTANT: Vanilla does not have a mechanism for hosting your font CSS or your fonts.
Another option for including custom fonts
If you do not have the ability to generate a font CSS file, you can use JavaScript in your Theme to embed custom fonts CSS directly into your page.
1. Go to the JavaScript tab of the theme.
2. Create a function to embed CSS into the head of every page:
sconst injectCSS = (styles) => { const head = document.querySelector('head'); const styleTag = document.createElement('style'); styleTag.innerHTML = (styles) ? styles : ''; head.appendChild(styleTag); }
3. Create a variable that is valid CSS that call imports your font from a remote location:
Const fontStyles = '@font-face {
font-family: "Trickster Bold";
src:
url("https://cdn.myfonts.com/webfonts/trickster-bold.otf") format("opentype"),
url("https://cdn.myfonts.com/webfonts/trickster-bold.woff") format("woff"),
url("https://cdn.myfonts.com/webfonts/trickster-bold.woff2") format("woff2");
font-weight: bold;
}
@font-face {
font-family: "Trickster Outline";
src:
url("https://cdn.myfonts.com/webfonts/trickster-outline.otf") format("opentype"),
url("https://cdn.myfonts.com/webfonts/trickster-outline.woff") format("woff");
}
'
4. Execute the injectCSS function onVanillaReady, passing the fonts:
OnVanillaReady(() => {
InjectCSS(fontStyles);
});
Now, any of the font family names in the injected CSS can be used as valid font-family variables in your Theme, your Header, and your Footer.
Whitelist the font's hosted domain
For security reasons, the browser may block the custom font that you set, or the font CSS file, because it comes from a third party.
To prevent this, add the domain of your font URL to the trusted domains in your Vanilla Dashboard in Settings > Security > Content Security Domains.
📝 NOTE: Add only the domain. You can use an asterisk (*) as a wildcard character to whitelist sub-domains of your font URL domain.
⭐️ EXAMPLE: Specify *.mycompany.com to allow fonts to be imported from www.myfonts.com, myfonts.com, and cdn.myfonts.com as well.
Fallback fonts (options)
Vanilla has in place a good set of standard font family fallbacks; but you can optionally set others.
global.fonts.customFont.fallbacks
Advanced options
Often, the line height of a font is much bigger than the font ascenders and/or descenders. This can make the top of texts seem off and not aligned with adjacent elements. The heading alignment is the most common problem, so we have some variables for that.
global.fonts.alignment.headings.capitalLetterRadio // What percentage of the line height does the font take (test with highest ascenders/decenders. Example text: "TgylyH" <- (has both ascenders and decenders)
global.fonts.alignment.headings.verticalOffset // If the font is not centered, use to adjust text vertically
global.fonts.alignment.headings.horizontalOffset // If the font is not aligned with the left edge of the container, use to adjust it
Troubleshooting
My custom font isn't loading
There are a few things that could prevent your font from loading.
- Make sure that the custom font name you are using matches the one in the CSS file you added.
- You may be having an issue with CORS headers on the font you are loading. The server from which you load the font must set headers in order to allow access to your site's domain.
You have a CORS error if your JavaScript console displays a message similar to the following. See Cross-Origin Resource Sharing (CORS) for helpful information.
Access to font at 'https://some-domain.com/path/to/font.ttf'
from origin 'https://forum.mysite.com'has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.
Google Fonts allows any domains in their CORS policy so you should generally never see this message.
Services like Adobe TypeKit and Fontsquirrel generally have some user interface where you are required to whitelist a domain (or domains) for your font.
✔️ TIP: If you are hosting custom fonts, see this article on how to enable CORS support on your server.
Legacy custom fonts
In our first iteration of custom fonts, we used customFontUrl, which will be removed in a future iteration, so do not use it. It's still here for compatibility until we refactor it out in a future update.
