HubSpot CMS Theme Development Tutorial: How to Build HubSpot Custom Modules Using HTML + HubL

Get FREE HubSpot Tutorial for Beginners PDF
HubSpot CMS Theme Development Tutorial: How to Build HubSpot Custom Modules Using HTML + HubL

Have you heard of HubSpot modules but are not sure what they are or how to use them in your pages? Have you wondered how to make a HubSpot custom module?

This HubSpot CMS theme development tutorial will show you how to build HubSpot custom modules that you can use to experiment and test how modules can make your website tailored to your needs.

HubSpot Development Tutorial

What is a HubSpot Module?

Modules are reusable components that page editors can use when adding content to a web page. Picture this scenario, let’s say you want to have a landing page that has form on the right and rich text on the left. So you use the basic page builder and create a section, and drag and drop a rich text module and form module into the page. So another way of thinking of modules is “things” that make up your page. The sections and columns are the page structure that holds and position these things.

You can create your own custom modules for anything you can think of. Want a listing of videos that open a pop-up when you click on them? Or how about a FAQ accordion that can change colors and fonts depending on the business unit? All of these things can be created, using input data fields and some HTML CSS JS to style this content.

What is a HubSpot Module? YouTube Video

Step 1 – Create New HubSpot Custom Module

First, in the top header navigation, go to Marketing > Design Tools. Then right-click on a folder in the left sidebar for the location you would like your module to be saved at. Click on “New file in [your folder name]”

Then Choose Module from the file type dropdown menu

Step 2 – Edit HubSpot Module Settings

Next, you will see a settings panel appear with various options. below is a short description of each of these options.

Where would you like to use this HubSpot module?

Most often you are going to want your module available in pages. But here, you can specify other places to use your module like in blog posts or even quotes.

HubSpot Module content scope

If someone edits the module, do you want it to apply to all instances of the module being used across your entire site? If so, choose the global option. If not, choose the local option that makes each module instance unique and independent of other pages.

File Name

This is the name of the module used in the file system. You can use spaces but I often use a developer style naming convention of lowercase and hyphens for spaces. This just helps keep things consistent.

hubspot cms module editor

  • A: This is the HTML structure box and is the place you will add your module field data snippets in. This tells the system where and how to display the content.
  • B: If your module has unique CSS styles they will go here
  • C: If your module has unique JS styles they will go here
  • D: When you are building a new module, I recommend unchecking this box to prevent another user from using your module before it is complete. When this is checked, it will be visible in the page editor in the left sidebar menu.
  • E: After you make edits to your module, you will be given the option to preview or publish your menu. I recommend publishing your module after each major change you make to prevent losing any of your work.
  • F: As you build your module and edit field settings you will be taken to different tabs, this is module breadcrumbs and when clicked, can take you back to the main screen.
  • G: This text label is what is shown in the page editor. Update this if you would like this to be different from your original module name. When I create modules, I use lowercase letters and hyphens for spaces. Then in the label I make it more readable by using title case and spaces.
  • H: This is where you will be doing most of your work by adding the input fields for your module. Also think about how you might want to group these fields. A way to think about these groups is to think of things as objects. For example, if I wanted to create a module for an image gallery I would have multiple “Slide Items” that all contain an image and a caption. “Slide Items” would be the group name and the fields would be an image field and a rich text field for the caption.
  • I: Do you want the content editor to be able to modify the default styling of the module? If so, you can add a styles tab to your module to allow them to do so.

Step 3 – Add Data Input Fields

Click on the “Add Field” to open up a dialog box for all of the field types available. Visit this page to learn more about all of the HubSpot module fields available.

For this example, I am adding a rich text field. By default, your field name will be automatically created using your label text. This can be changed after you have written your label if you would like. I often make my field names more concise.

Step 4 – Copy Field Snippets to HTML

In my example below, I created two fields. A rich text and a plain text field by clicking on Actions and then Copy Value Only (B). I then pasted each field value code snippet inside some empty divs. If this all seems new to you, thats ok ignore the code for now and just see how I am creating a data input and then specifying a data output in my module HTML box.

Step 5 – Publish and Preview the HubSpot Custom Module

In the top right corner, you click the “Preview” button to test your module. Rich text supports common text formatting options like bold, italic, bullets, and images. Plain text is just without any of those formatting options available.

A List of HubSpot Module Ideas You Could Create

  • Cards listing module
  • Sales territory map module
  • Resource library module
  • Testimonial Slider module
  • Color swatch Picker module
  • Video player module
  • Upcoming Events Listing module
  • Linked Image Row module
  • Accordion module
  • Hero module
  • Menu module
  • HubSpot video player
  • Breadcrumbs module
  • Rich text in columns module
  • Product feature callout module
  • Product Attributes List module
  • Products Details List module

Common Questions

How can I set repeater options for a module field?

To set repeater options for a module field, you can follow these steps. First, locate the Repeater options section in the module settings. Within this section, you have the ability to specify a minimum and/or maximum number of instances required for the field.

Additionally, you can set a default object count, which determines the number of instances that will initially appear in the module. For example, if you set a default object count of 4, the module will display four instances of the field by default.

To provide more flexibility to the user, you can define both minimum and maximum limits. Using the example of an image field set up as an image slider, you might choose a minimum of 3 image fields and a maximum of 5. This means that the module will always display at least three image fields, but the user has the option to add up to two more or remove existing ones.

Once you’ve made adjustments to the repeater options, they will be automatically enabled. To disable the repeater options, you can simply click the toggle switch located on the right side of the Repeater Options section. This allows you to quickly toggle between having the repeater options active or inactive based on your needs.

What editor options are available for module fields?

The editor options available for module fields include:

1. “Make this field required” – Enabling this option ensures that users cannot leave the field blank in the content editor. They will be prompted to fill in the field before saving.

2. “Prevent editing in content editors” – This option restricts the editing capability of the field within the content editor. However, it is still editable at the template level. Please note that this option is not applicable to global modules since they cannot be edited at the page level.

3. “Tooltip help text” – With this option, you can add contextual or instructional help text to the field. When a user hovers over the field while editing, a tooltip will appear displaying the provided help text.

4. “Inline help text” – This option allows you to include help text below the field in order to provide users with additional context or instructions. The help text will be visible to users while they are editing the module.

These editor options aim to provide flexibility and guidance to users when working with module fields in the content editor.

Can custom modules be used in email templates?

Custom modules cannot be used in email templates, as modules used in email templates cannot include CSS or JavaScript. It is important to note that the ability to create custom modules for use in emails is available only in accounts with a Marketing Hub Professional or Enterprise subscription.

What subscriptions are required to create custom coded modules?

To create custom coded modules, you will need any of the available subscriptions, regardless of the specific product or plan you have. However, it is important to note that creating modules requires expertise in HTML, CSS, HubL, and the HubSpot design manager. HubSpot highly recommends working with a developer who has the necessary knowledge and skills to assist you in creating these coded modules.


This HubSpot CMS modules tutorial is just a basic introduction to creating and editing modules. I suggest building a test module and experimenting with the different fields and options. Also, visit the developer documentation on modules for more detail on how to edit and display your module field data.

Written by: Jake Lett
I share digital marketing tips and HubSpot tutorials to help marketers and business owners grow their business.

Related posts

Tags: , , ,

Want to Get Email Updates of New Articles?

Join My Email Newsletter