How to Build Custom Modules in HubSpot CMS | Developer Guide

If you have worked with HubSpot CMS for some time, you already know that modules are the building blocks of every page. They allow developers to create reusable components that marketers and content editors can easily manage through the drag-and-drop editor.

However, sometimes the default modules are not enough to match a specific design or functionality. That is where custom modules become very useful.

Custom modules allow developers to create flexible components tailored to a website’s needs. Whether it is a custom hero section, testimonial slider, pricing table, feature grid, or any interactive element, custom modules give full control over layout, styling, and functionality.

In this guide, I will explain how custom modules work in HubSpot CMS and how developers can build them efficiently.

Understanding Custom Modules in HubSpot CMS

A custom module in HubSpot is essentially a reusable component built using HTML, HubL, CSS, and JavaScript.

Typically, a module contains the following files:

module.html
module.css
module.js

The HTML file defines the structure of the module, CSS controls the styling, and JavaScript adds any interactive behavior.

When a module is added to a page, HubSpot automatically loads these files to render the component properly. This modular approach keeps the website structure organized and makes development more scalable.

Why Custom Modules Are Powerful

Custom modules offer many benefits for both developers and marketing teams.

Instead of hardcoding layouts directly into templates, developers can create reusable components that can be used across multiple pages.

Some of the main advantages include:

Reusability
You can build a component once and reuse it across multiple templates or pages.

Editor Friendly Controls
Content editors can update text, images, and settings without touching any code.

Design Consistency
Using modules helps maintain consistent design elements across the entire website.

Faster Development
Developers can work faster by reusing modules instead of rebuilding sections again and again.

This makes HubSpot CMS especially effective for teams where developers and marketers work together.

How Custom Modules Work Behind the Scenes

When developing modules using HubSpot CLI or inside the Design Manager, each module is stored inside a folder with the .module extension.

Inside the module folder, you will usually find configuration files like:

meta.json
fields.json

The meta.json file controls module settings such as whether it can be used in pages, blog posts, or emails.

The fields.json file defines the editable fields that appear in the HubSpot page editor.

These fields allow marketers to customize module content easily. Some common field types include text fields, image uploads, rich text editors, choice fields, and color pickers.

Because of this system, developers can build flexible modules while giving marketers complete control over content updates.

Step-by-Step Process to Build a Custom Module

Here is a typical workflow developers follow when building custom modules.

Step 1: Create the Module

You can create a module in two ways.

First, directly inside the HubSpot Design Manager.

Second, by using the HubSpot CLI for local development.

Most professional developers prefer the CLI because it allows better development workflows, version control, and easier collaboration.

Step 2: Define Module Fields

Fields are what make modules dynamic.

For example, you might add fields such as:

Heading
Description
Image
Button Text
Button Link

These fields appear inside the HubSpot page editor so content editors can easily update them without editing code.

Step 3: Build the HTML Structure

Inside the module.html file, you create the layout using HTML and HubL.

HubL allows you to dynamically output field values.

Example:

<h2></h2>
<p></p>

This connects the editable fields from the editor to the frontend display.

Step 4: Add Styling

The module.css file contains all styling related to the module.

It is a good practice to keep styles scoped to the module so they do not affect other parts of the website.

Many developers also follow naming conventions like BEM to keep CSS organized and maintainable.

Step 5: Add JavaScript Functionality

If your module requires interactive behavior such as sliders, tabs, accordions, or animations, you can add JavaScript inside module.js.

HubSpot automatically ensures that module JavaScript files are only loaded once per page, even if the module appears multiple times. This helps improve website performance.

Best Practices When Building HubSpot Modules

After working with HubSpot CMS across multiple projects, here are a few best practices developers should follow.

Use clear naming conventions for modules and fields so other developers can easily understand the code.

Follow structured CSS methodologies such as BEM to avoid styling conflicts.

Avoid hardcoding values whenever possible. Instead, expose configuration options through module fields.

Keep modules focused on a single purpose rather than adding too many features into one component.

Always consider the experience of the content editor who will use the module in the page builder.

When Should You Use Custom Modules

Custom modules are especially useful when you need reusable components or when the default HubSpot modules do not match the design requirements.

You should consider using custom modules when:

You need reusable design sections across multiple pages
Marketers need editable content blocks
You are building a scalable HubSpot theme
The project requires custom layouts or interactive components

In most professional HubSpot projects, custom modules become the foundation of the website architecture.

Final Thoughts

Custom modules are one of the most powerful features of HubSpot CMS.

They allow developers to create flexible and reusable components while giving marketers full control over content updates through an easy visual editor.

Once you start building websites with a modular approach, development becomes more efficient and maintaining large websites becomes much easier.

If you regularly work with HubSpot CMS, learning how to build custom modules properly can significantly improve your development workflow and help you deliver better websites for clients.