Hupspot custom modules guide

Custom modules in Hubspot let developers and marketers build reusable, configurable components for pages, blogs, and emails. Using the design manager, you can create modules that are easy to update, share across templates, and control directly in the content editor.

What are custom modules in Hubspot?

In the Hubspot design tools, a custom module is a reusable block of content or functionality that you define once and insert into many templates. Each module can expose fields that content creators edit without touching code.

Custom modules are ideal when you need:

• Consistent layout or functionality across many pages.
• Non-developers to edit content safely.
• Version control and centralized updates.
• Advanced behavior using HTML, CSS, and JavaScript.

Modules can be used in:

• Website and landing page templates.
• Blog templates.
• Email templates (with some field limitations).

How to create a new Hubspot module

Follow these steps in the design manager to create a new custom module.

Step 1: Open the Hubspot design manager

1. In your Hubspot account, go to Marketing > Files and Templates > Design Tools.
2. The design manager file tree opens on the left, and the main editor panel appears on the right.

Step 2: Add a new module file

1. In the left sidebar, click the File menu.
2. Select New file.
3. In the dialog, choose Module as the file type.
4. Choose whether the module will be used in:

• Pages (website and landing pages)
• Blogs
• Emails
• All supported content types if offered

5. Select the folder where the module will live in your Hubspot file structure.
6. Give the module a clear, descriptive name, such as Homepage hero banner or Feature grid.
7. Click Create.

Hubspot generates a new module file and opens it in the layout editor.

Step 3: Choose the module type

Depending on your needs, you can build your module in different ways:

• Drag and drop module: Use the visual layout editor to place fields and groups without writing template code.
• HTML + HubL module: Write custom markup and HubL tags for full control over structure and rendering.
• Hybrid approach: Combine the drag-and-drop interface with code for more advanced layouts.

In many Hubspot projects, developers start with HTML + HubL modules for maximum flexibility, then expose only the most important options to editors.

Configuring fields in a Hubspot module

The power of a module comes from its fields. Fields define what content editors can change from the page, blog, or email editor.

Supported field types

In the right sidebar of the module editor, you can add a wide range of field types, including:

• Text (single-line, multi-line, rich text)
• Image and Image group
• Boolean (true/false, checkboxes)
• Choice (radio buttons, dropdowns)
• Number and Range
• Date and Date-time
• Color picker
• Link or URL
• Repeater fields for dynamic lists

Editing field options and labels

For each field you add, Hubspot lets you configure:

• Label: What editors see in the content editor.
• Name: The internal reference used in code.
• Help text: Guidance for editors on how to use the field.
• Default value: Pre-filled content when the module is first added.
• Required state: Whether filling the field is mandatory.
• Visibility settings: Whether the field appears in the content editor.

Good labeling and help text are critical to keep non-technical users productive inside Hubspot.

Adding layout and logic to a Hubspot module

After defining fields, you connect them to your layout markup and any conditional logic.

Using the layout editor

For drag-and-drop modules, you can:

• Arrange fields and groups visually.
• Group related fields together for better organization.
• Set responsive behavior using built-in layout options.

This is useful for simpler structures that do not require custom HTML.

Using HTML and HubL

For more advanced modules, you can use the code editor:

• Write HTML structure for the module output.
• Insert HubL expressions to render field values, such as {{ module.text_field }}.
• Add conditional logic with {% if %} and {% for %} tags.
• Include partials or macros for repeated patterns.

This approach gives full control over how the module appears on Hubspot pages, blogs, and emails.

Styling and scripts in Hubspot modules

Modules can include their own styles and scripts so they behave consistently wherever they are used.

Adding CSS

In the module editor, you can add CSS directly in the CSS section:

• Target the module using automatically generated wrapper classes.
• Add responsive rules for different screen sizes.
• Limit styles to the module scope to avoid conflicts.

Alternatively, reference external stylesheets managed elsewhere in your Hubspot theme.

Adding JavaScript

To add interactive behavior:

• Use the JS section to write module-specific scripts.
• Initialize components when the module loads.
• Avoid polluting the global namespace; wrap code in closures when possible.

Consider performance and only load scripts that the module truly needs.

Using a Hubspot module in templates and content

Once your module is built, you can make it available to editors and templates.

Adding the module to a template

1. Open your page, blog, or email template in the design manager.
2. In the left sidebar, search for your module by name.
3. Drag the module into the desired spot in the template layout.
4. Save and publish the template.

Any content built with that template now includes your module area.

Editing module content in the page editor

1. Open a page or blog post that uses a template containing the module.
2. Click on the module area in the page editor.
3. Update the fields exposed by the module.
4. Preview the page and publish changes when ready.

Hubspot ensures that changes made at the page level affect only that instance, while structural changes to the module file propagate to all instances.

Managing Hubspot modules over time

As your site evolves, you may need to update, clone, or restrict modules.

Editing existing modules

To update a module:

1. Open the module file in the design manager.
2. Adjust fields, layout, logic, CSS, or JavaScript as needed.
3. Click Publish changes.

After publishing, all templates and pages using the module will reflect the new behavior, while preserving instance-level field values where possible.

Cloning and versioning

Hubspot lets you clone modules for experimentation:

• Right-click the module file in the file tree.
• Select Clone to create a copy.
• Rename and modify the clone safely without impacting the original.

This is useful when rolling out new designs gradually or testing new functionality.

Best practices for scalable Hubspot modules

To keep your implementation maintainable:

• Use clear naming conventions for modules and fields.
• Limit the number of fields exposed to editors to what they actually need.
• Group related settings (e.g., typography or spacing) in organized sections.
• Keep logic in the module, not in every template, so updates are centralized.
• Document complex modules in your internal Hubspot playbook or style guide.

More resources for Hubspot module development

To go deeper into every setting and capability, review the official documentation on creating and editing modules in the design manager here: Hubspot module docs.

If you need strategic help planning a scalable system of templates, themes, and modules, you can also consult a specialized agency such as Consultevo for guidance on structure, performance, and governance.

By building well-planned custom modules in Hubspot, your team gains a flexible foundation that supports rapid content updates, consistent design, and long-term maintainability.

Need Help With Hubspot?

If you want expert help building, automating, or scaling your Hubspot , work with ConsultEvo, a team who has a decade of Hubspot experience.

Scale Hubspot

“`