Understanding Custom Modules in HubSpot React + HubL Themes

The true power comes from custom modules when building a HubSpot CMS React theme. These modules let you create reusable, dynamic, and interactive components that blend HubSpot’s HubL templating language with modern React.

Where Custom Modules Live

Inside your theme project, HubSpot automatically organizes modules under:

src/theme/my-theme/components/modules

Example structure:

modules/
 └── getting-started/
      ├── fields.json
      ├── index.tsx
      ├── getting-started.module.css

Anatomy of a Custom Module

1. fields.json – Define Content Fields

This file tells HubSpot what inputs content creators can configure in the page editor.

{
  "label": "Hero Banner",
  "global": false,
  "icon": "image",
  "host_template_types": ["PAGE"],
  "is_available_for_new_content": true,
  "fields": [
    {
      "name": "title",
      "label": "Banner Title",
      "type": "text",
      "default": "Welcome to HubSpot React Theme"
    },
    {
      "name": "backgroundImage",
      "label": "Background Image",
      "type": "image"
    }
  ]
}

2. index.tsx – React Component

import React from "react";
import styles from "./getting-started.module.css";

const HeroBanner = ({ title, backgroundImage }) => {
  return ({title});
};
export default HeroBanner;

3. getting-started.module.css – Styling

:root {
  --hero-bg: #5e6ab8;
}
.wrapper {
  padding: 80px;
  background-color: var(--hero-bg);
  color: #fff;
  text-align: center;
}

Local Development Workflow

• Start the dev server: npm run start
• Open http://hslocal.net:3000
• Edit your module → save → instant auto-refresh in browser

SEO Benefits of Custom Modules

• Faster page loads – React + HubL hybrid builds clean, optimized HTML
• Structured fields – Consistent, SEO-friendly layouts
• Schema-ready – Extend modules with JSON-LD for rich snippets
• Scalability – Build once, reuse everywhere, avoid duplicate content issues

Key Takeaway

Custom modules in a HubSpot React + HubL theme are not just “fancy widgets.” They’re scalable, marketer-friendly, SEO-optimized building blocks that make development and content management seamless. Whether it’s a hero banner, testimonial slider, or pricing table, building modules with React unlocks the best of modern front-end while keeping HubSpot’s CMS flexibility.

As you explore the capabilities of custom modules, know that creating, optimizing, and maintaining these components in HubSpot’s ever-evolving CMS environment requires both experience and precision. With extensive hands-on expertise in HubSpot CMS and familiarity across its CRM ecosystem, I empower HubSpot Portal to turn these advanced capabilities into fully functional, high-performing websites that drive results.