Getting started with themes

Last updated:

A Theme is a portable and self-contained package of developer assets designed to work together to enable a marketer-friendly content-editing experience. These assets might include templates, modules, CSS files, JavaScript files, images, and more.

Themes allow developers to create a set of Theme Fields, similar to Module Fields, which allow content creators to tweak various knobs and dials specified by a developer to allow global stylistic control over a website without having to edit CSS. Developers use HubL to access the values of Theme Fields throughout their CSS. Content creators use the Theme Editor to modify Theme Fields, preview those changes against existing templates within a Theme, and publish their changes.


This document walks through creating your first theme based on the HubSpot CMS Boilerplate. For more on Themes, see the Themes Reference documentation.

Before you begin

1. Start a boilerplate theme project

Run hs create website-theme my-website-theme to create a my-website-theme directory populated with files from the CMS theme boilerplate.

2. Upload the CMS Boilerplate to your HubSpot account

Run hs upload my-website-theme my-website-theme. This will upload the boilerplate to your account’s Design Manager, in a folder titled “my-website-theme”.

The files for the theme that end up getting uploaded to HubSpot live within the root directory. All other files in the boilerplate are supporting files. 

3. Create a page

In HubSpot, navigate to Marketing > Website > Website Pages, then select "Create". Choose a template from your newly uploaded theme by selecting the CMS Theme Boilerplate you uploaded from the "Your Themes" section, and then one of the templates within it

Theme Content Creator

4. Edit theme fields

Now that you’re on your page, navigate to the theme editor. On the lefthand side of the editor, go to “Design”, then “Edit Theme Settings”. This is where you can modify your existing theme settings. Publishing changes to theme settings will update the styles across your pages using this theme that was updated. 

5. Prepare to make local changes

Return to your terminal. Run hs watch my-website-theme my-website-theme. This command watches your local directory and automatically upload the following changes to your HubSpot account on file saves.

6. Add a theme field

Now that we're listening for local changes, open fields.json in your local cms boilerplate. The fields.json file will control the available fields in the theme editor sidebar. We’ll be adding a new field to specify the H1 options. 

To learn more about theme fields, see the Theme Reference documentation.

Add the following to the typography group:

// fields.json 
    "type": "font",
    "name": "h1_font",
    "label": "Heading 1",
    "load_external_fonts": true,
    "default": {
        "color": "#494A52",
        "font": "Merriweather",
        "font_set": "GOOGLE",
        "variant": "700",
        "size": {
        "units": "px",
        "value": 48

 Save fields.json, and refresh the theme previewer. Your new field should display in the lefthand sidebar.

7. Reference the field in your CSS

Now, modify the boilerplate CSS so that changes to this field are reflected on the page. Open _typography.css in the boilerplate.

To access a value in a theme, use the “theme” object. For example, you would use {{ theme.typography.h1_font.font }} to access the font-family set in our H1 font field.

Replace the H1 declaration in typography.css with the following:

h1 {
 	font-size: {{ theme.typography.h1_font.size.value }}{{ theme.typography.h1_font.size.units }};
 	font-style: {{ theme.typography.h1_font.styles|attr('font-style') }};
 	font-weight: {{ theme.typography.h1_font.styles|attr('font-weight')  }};
 	font-family: {{ theme.typography.h1_font.font }};
 	color: {{ theme.typography.h1_font.color }};
 	text-decoration: {{ theme.typography.h1_font.styles|attr('text-decoration') }};
    line-height: 1.3;

Save typography.css to upload it to your HubSpot account.

8. Test changes

Return to the theme editor to confirm changes. Try changing settings to have them reflected immediately in the preview.