HubSpot Custom Modules: What They Are and When You Actually Need One

A custom module is a reusable content block your marketers can drag onto any page and edit without touching code. You need one when no marketplace theme does what you need. You do not need one nearly as often as agencies suggest.

This guide explains what a module actually is, how to tell whether your project needs custom work, and — more usefully — how to tell whether the module you were sold was built well.

What a custom module actually is

Under the hood, a HubSpot module is a small set of files that work together:

• fields.json — defines what your marketing team sees and can edit in the page editor. Text fields, image pickers, colour choices, repeaters.
• module.html — the template that renders those fields into actual page HTML, written in HubL, HubSpot's Jinja-based templating language.
• module.css — styles scoped to this module, loaded only on pages where the module appears.
• module.js — any interactive behaviour, also loaded on demand.
• meta.json — the module's name, description, category, and whether it is global.

The value is in the split. A developer writes it once. Your marketing team then reuses it forever, on any page, without a developer and without breaking the layout. That is the entire point, and it is why the quality of fields.json matters more than the quality of the HTML.

The three-question test

Before commissioning custom work, answer these honestly.

1. Can you point to three websites that already do this? If yes, a marketplace theme almost certainly has something close. Themes have matured enormously; hero sections, pricing tables, logo carousels, testimonial sliders, tabbed content and accordions are all solved problems.

2. Will this be used more than three times? A module is an investment in reuse. If a layout appears on exactly one page and will never appear again, a rich text field and some inline HTML may be the cheaper answer.

3. Does it need to read live data? If the block needs to pull from HubDB, surface CRM properties, or change based on lifecycle stage, you are into custom territory. No theme will cover that.

Two noes out of three usually means you do not need a custom module. You need someone to configure a theme properly.

When custom work is genuinely the right call

• Interactive tools. Pricing calculators, configurators, ROI estimators, quiz-style qualifiers. These generate leads and no theme includes them.
• Data-driven listings. A filterable resource library, a location finder, a product comparison table pulling from HubDB.
• CRM-aware content. Blocks that show different content to a customer than to a first-time visitor.
• Brand-specific layouts. When your design genuinely differs from what themes assume, and the difference matters commercially.
• Editor guardrails. Sometimes the goal is restriction, not capability — a module that makes it impossible for a marketer to break the design system.

What separates a good module from a bad one

This is the part nobody explains to buyers, and it is where most of the money is wasted.

Field discipline

The most common failure is exposing too many fields. A developer, wanting to be helpful, gives editors control over padding, margin, font size, and colour for every element. Six months later every page looks slightly different, your brand consistency is gone, and nobody can work out why the site feels sloppy.

A well-built module exposes the minimum that genuinely needs to vary — usually content, an image, and a link — and locks everything else to the design system. Fewer, better-chosen fields produce more consistent sites.

Grouped, labelled fields

Fields should be grouped logically and labelled in language your marketers use, not in developer shorthand. If your team has to guess what "CTA Wrapper Alignment Override" does, the module has failed regardless of how clean the code is.

Repeaters instead of duplicates

If a module shows a list of similar items — cards, logos, testimonials, FAQs — it should use a repeater field so editors can add and remove items themselves. Building five hardcoded slots and telling the client to call you for a sixth is a red flag.

Dynamic heading levels

A module used in a hero needs an H1; the same module further down a page needs an H2. Hardcoding the heading tag creates SEO problems that surface months later as a confusing heading hierarchy. Good modules expose the heading level as a field.

Scoped assets

Module CSS and JavaScript should live in the module, not in a global stylesheet. That way they load only on pages that actually use the module, which keeps every other page lighter.

Global modules versus section modules

A global module appears identically everywhere it is used, and editing it once updates every instance. Headers, footers and site-wide banners should be global — you do not want to edit a phone number on forty pages.

A standard module is edited independently on each page. Hero sections, content blocks and testimonials should be standard.

Getting this wrong is a common and irritating mistake. A global hero means every page shares one headline. A non-global footer means a legal change becomes a day of tedious work.

What to ask for at handover

Whoever builds your modules, insist on these before you sign off:

• A written list of every module, what it does, and where it is used
• Field labels a non-technical person can understand without training
• Confirmation of which modules are global and which are not
• Commented code, so the next developer is not reverse-engineering yours
• A staging or test page demonstrating each module in use
• Explicit confirmation that you own the code

That last one matters more than people realise. Some agencies retain their module library and licence it to you, which means leaving them means rebuilding. Ask directly, in writing, before work starts.

Cost and timeline

A straightforward content module — a styled section with a few fields — is typically a few days of work. Something interactive, pulling live data or involving custom JavaScript, runs longer and costs proportionally more. The variables are the number of fields, whether it consumes external or CRM data, and how much design polish is required.

A useful heuristic: if the specification fits in a paragraph, it is a small job. If it needs a diagram, it is not.

Frequently asked questions

Do I need a developer to use custom modules?

To build them, yes. To use them, no — that is the whole point. Once built, your marketing team drags them onto pages and edits them in the visual editor without any code.

Can custom modules slow down my site?

Badly built ones can. Well-built ones scope their CSS and JavaScript to the module so assets load only where needed. If your site slowed noticeably after a module build, the assets were probably loaded globally.

Can I edit a marketplace theme's modules?

You can clone and modify them, which is often the cheapest route to something custom — you inherit a tested foundation rather than starting empty. Note that cloned modules no longer receive theme updates.

Will custom modules work if I change themes later?

Usually yes, though styling will need adjustment since modules typically inherit theme variables for colour and typography. Modules built with hardcoded values rather than theme variables are much harder to carry across — another reason to insist on clean construction.

How many modules does a typical site need?

Most marketing sites run well on fifteen to twenty-five well-designed modules. If a proposal lists sixty, ask why. Large module counts usually indicate poor reuse rather than thorough coverage.

The question worth asking

Not "can you build this module," but "does this need to be a module at all?" A developer who occasionally talks you out of custom work is worth considerably more than one who never does.

If you have a module in mind and want a straight answer on whether a theme already covers it, describe what you need and we will tell you — including when the answer is that you do not need us.