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.

Theme settings edit UI animation showing selecting a color for elements of a theme.

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

If this is your first experience with CMS Hub development we recommend:

Quick start to CMS Hub development

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.

Screen grab of the page creation experience for a template in a theme

4. Edit theme fields

Now that you’re on your page, navigate to the theme editor. On the left-hand 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. 

Open theme settings from page editor

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 uploads 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 height of the footer.

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

Near the bottom of your fields.json file is a group with the name "footer". Inside of the children array, we're going to add our field.

Copy (excluding the comment) and paste the JSON below into your file above the first item in the children array for the footer group. 

// fields.json 
      "id" : "",
      "name" : "height",
      "label" : "Footer height",
      "required" : false,
      "locked" : false,
      "display" : "text",
      "step" : 1,
      "type" : "number",
      "min" : 10,
      "max" : 900,
      "help_text":"This footer will expand in height to accomodate any content added to the footer. You are setting the minimum height in px",
      "default" : 100

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

7. Reference the field in your CSS

Now, open the theme-overrides.css file. Find the css selector for .footer.

We're now going to add a min-height to this selector.

To access a value in a theme, use the “theme” object. For example, you would use {{ theme.footer.height }} to access the height value set in our height field.

Replace the .footer declaration in theme-overrides.css with the following:

.footer {
  background-color: {{ footer_bg_color }};
  min-height: {{theme.footer.height}}px;

Save theme-overrides.css to upload it to your HubSpot account.

8. Test changes

Return to the theme editor, and refresh the page to see your new field appear under footer. Update the height value to have it reflected immediately in the preview. May be helpful to set a background color for the footer so you can see the change more easily.

Next Steps

Congratulations on getting your theme set up. You can now create more theme fields and customize them for your projects. Theme fields are only one of many features that themes support. View the themes overview for more.

In this tutorial you created a basic theme using the HubSpot Theme Boilerplate. This boilerplate is open source and filled with all of the best practices for building performant websites on HubSpot CMS.

HubSpot has several default themes that come with CMS Hub. These themes are available for you to view, clone and tinker with, to learn how you might use a theme in a real world scenario.

Once you've got a handle on themes, learn how to build your first custom module.

Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.