Add custom fonts to a theme
When developing a theme, you can add custom fonts to enable content creators to use them in font fields and rich text fields when building website content. After adding a custom font to the theme, HubSpot will generate CSS to render the font styling.
At a high level, to add a custom font to a theme you'll need to add the following to your theme files:
- A
fonts
folder that contain the custom font files andfont.json
config file. This folder and its contents can be named and structured in any way. - A
font.json
file within thefonts
folder that defines the font and its variations for use in the theme. - In
theme.json
, acustom_fonts
array containing a list of paths to the font folders within the theme.
Below, learn more about adding fonts to your theme files.
In your theme folder, you'll first add a fonts
folder to store the needed font files if you're hosting them locally. While there's no set way to structure the fonts
folder and its contents, it's important to include several font formats to optimize browser compatibility and to provide content creators with various font weights.
You can include font variations by adding individual files for each variation, or by using a variable font where a single file contains all variations. The method you choose will depend on the font files available to you, and the fonts.json
file will need to be configured to match.

In the fonts
folder, include a font.json
file that defines the font and its variations for use in the theme.
name string
The name of the font. |
default string
The name of the variant to use as the default, as specified in the |
fallback string
Comma-separated fallback fonts to be appended to the end of the custom font CSS. For example:
|
variants array
List of font variants, including the default font, which use the fields below. |
⮑ name string
The name of the variant. |
⮑ files array
An array containing a list of file paths and formats for the variant fonts. Paths can be relative or absolute. You can reference font files stored locally or external URLs, but you cannot reference stylesheets containing |
⮑ styles object
Specifies which CSS styles should be applied to the font variant. If not included, no additional CSS will be applied. Overrides conflicting styles from the top-level |
// font.json
{
"name": "Noah",
"default": "Regular",
"fallback": "arial, sans-serif",
"variants": [
{
"name": "Regular",
"files": [
{
"file": "./TTF/Noah-Regular.ttf",
"format": "truetype"
},
{
"file": "./WEB/Noah-Regular.woff",
"format": "woff"
},
{
"file": "./WEB/Noah-Regular.woff2",
"format": "woff2"
}
],
"styles": {
"font-weight": 400
}
},
{
"name": "Bold",
"files": [
{
"file": "./TTF/Noah-Bold.ttf",
"format": "truetype"
},
{
"file": "./WEB/Noah-Bold.woff",
"format": "woff"
},
{
"file": "./WEB/Noah-Bold.woff2",
"format": "woff2"
}
],
"styles": {
"font-weight": "bold"
}
}
]
}
If your custom font is a variable font, where the main font and its variations are contained in one file, you'll define your font variants in the same way as a non-variable font where each variant is defined separately. Each variant will then reference the same file within the file
property.
For example, if you had a single variable font file, myfont.ttf
, which contained the bold and italic versions, you would format your font.json
file as follows:
To include a variant not contained in the variable font file, you can include a separate font file within the files
array for that variant instead of styles
.
Thank you for your feedback, it means a lot to us.