Creating a Child Theme

Last updated:
APPLICABLE PRODUCTS
  • Marketing Hub
    • Professional or Enterprise
  • CMS Hub
    • Professional or Enterprise

A child theme is a copy of an original parent theme. You can edit the child theme without altering the parent theme. You can create child themes from HubSpot themes, marketplace themes, as well as custom themes.

Create a Child Theme for a Marketplace or HubSpot Default Theme via the Design Manager

You can create a child theme for your marketplace purchased theme or a default HubSpot theme in the Design Manager. When creating a child theme from these assets inside the Design Manager, the following files will be added to your child theme:

  • theme.json - this will include the proper extends statement for linking to the parent theme.
  • child.css and child.js - this is an empty CSS and JS file. Code added to these files will only affect the child theme. You can customize the name of these files in the advanced options section of the child theme creation wizard.
  • Any files that contain the standard_header_includes HubL variable. This usually includes a "base" or "main" template file. You can view an example of this on our boilerplate.

You will be able to edit the child theme even if the original theme is not editable.

To create a child theme for a Marketplace or HubSpot Default theme in the Design Manager:

  • In your HubSpot account, navigate to Marketing > Files and Templates > Design Tools.
  • In the left sidebar, right-click on your Marketplace (located in the @marketplace folder) or HubSpot default theme (located in the @hubspot folder) and choose Create child theme.
  • Enter a name for your child theme, choose the location of the theme, and click Create Child Theme.
    • If you open the advanced options, you can also customize the name of the child CSS and JS files that are created with your child theme. 
  • Once your child theme is created, a success message will appear telling your child theme is ready to go. You can now Click Close.
  • You should now see your child theme and its contents in the left sidebar.

Create a Child Theme for a non-marketplace theme in the Design Manager

You can create a child theme in the Design Manager. Your child theme will inherit the assets and files from the parent theme. You will be able to edit the child theme even if the original theme is not editable.

To create a child theme in the Design Manager:

  • In your HubSpot account, navigate to Marketing > Files and Templates > Design Tools.
  • In the left sidebar, click file and then choose New theme.
  • For the Theme Starting Point, choose Blank Theme.
  • Enter a name for your theme and click Create.
  • The theme.json file for the new theme will open. Edit the theme.json file and add a new line below line 5. Be sure to add a comma to the end of line 5.
  • Add an extends statement to line 6. The value is the path of your desired parent theme. For instance, to create a child theme from the Barricade theme:
JSON
"extends": "path/to/theme"
  • Your new theme will have a blank fields.json file. Copy over the content of the original fields.json file from the parent theme or update the file as desired.

Create a Child Theme with the CLI

You can create a child theme with the CLI. You must complete the setup process for the CLI before creating a child theme. Your child theme will inherit the templates and files from the parent theme. You will be able to edit the new theme within the CLI and in the Design Manager.

To extend a theme in the CLI:

  • Create a new directory for your theme. For example:
Shell script
mkdir cms-project
  • In the new directory, create a copy of the theme.json file of the parent theme. For example:
Shell script
cd cms-project
cp ~/src/cms-sprout-theme/src/theme.json
  • Edit the copied theme.json file and add a new line below line 5 (or below the final line of the responsive_breakpoints, if they are present). Be sure to add a comma to the end of line 5.
  • Add an extends statement to line 6 (or 14, or the appropriate line for your theme). The value is the path of your desired parent theme. For instance, to create a child theme from the Barricade theme:
JSON
"extends": "@hubspot/barricade"
  • Your new theme will have a blank fields.json file. Copy over the content of the original fields.json file from the parent theme or update the file as desired.
  • Upload your new theme and files to your portal. For example:
Shell script
hs upload cms-project cms-project

Limitations

The total number of child themes you can have is limited based on your CMS Hub subscription. These limits are as follows:

  • Marketing/CMS Hub Pro: 5 Child Themes
  • Marketing/CMS Hub Enterprise: 10 Child Themes

FAQs

  1. Can I copy a child theme to another portal if the parent theme is from the Marketplace?
    Yes, as long as the “extends” path is the same in the new portal.
  2. What assets are inherited from the parent theme?
    All files are inherited from the parent theme unless they are overwritten in the child theme.
  3. How can I override a particular asset from the parent theme?
    A file in the same relative path of a child theme will overwrite the equivalent file from the parent theme. So, for instance, to overwrite @marketplace/parent/theme/templates/about.html you can create /child/theme/templates/about.html and make your edits to the new file. The new file will take effect instead of the inherited file. Note that this applies to your fields.json file as well as other files in the theme.
  4. How can I create new pages using the child theme?
    When you create a new page, your child theme will appear as an option under Your Themes in the page creation modal. See the Knowledge Base for more information on creating a page using your theme.
  5. How can I edit an existing page to use a child theme instead of the parent theme?
    You can replace your page template with the equivalent template from the new theme. For instance, replace the template landing-page.html (in the parent theme) with the template landing-page.html (in the new theme).
  6. How can I edit a template’s label in the page-creation interface?
    You can change the label of your template by editing the HTML file. The label is located in a comment at the top of your theme file.
  7. Can I create a child theme from a child theme?
    Currently you cannot create a child theme from a child theme.

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.