HubSpot CMS is a powerful and flexible platform that enables businesses to efficiently build and manage websites. With its user-friendly interface, seamless integrations, and robust customization options, HubSpot is a top choice for both marketers and developers. While HubSpot provides pre-built themes and templates, creating custom themes and modules allows businesses to design unique, fully branded experiences with greater flexibility and improved performance. Developing a custom theme in HubSpot CMS gives complete control over website design, functionality, and branding elements. Custom modules further enhance scalability by enabling reusable components and streamlined content management. Whether you're a developer aiming to build dynamic, feature-rich pages or a marketer focused on enhancing user engagement, understanding how to create custom themes and modules is essential.
Before diving into development, it's crucial to understand how themes and modules work within HubSpot CMS.
A HubSpot CMS theme is a collection of files that define a website’s design and functionality. It includes:
Custom themes provide greater control over branding and user experience compared to pre-built options.
Modules are reusable content blocks that add dynamic functionality to a website. HubSpot offers:
Combining custom themes and modules allows for a flexible, scalable website.
To develop custom themes and modules, set up your local environment with the necessary tools.
Ensure you have:
The CLI enables interaction with your HubSpot account for uploading files and managing themes.
Open your terminal (Mac/Linux) or command prompt (Windows) and run: npm install -g @hubspot/cli
Once installed, connect the CLI to your HubSpot account: hs auth .Generate authentication for a HubSpot account using a personal access key.If you already have a hubspot.config.yml file you can use this command to add credentials for additional accounts.
Follow the on-screen instructions to log in and authorize your account.
After authentication, link your local development environment to your HubSpot account: hs init
This command will prompt you to select your HubSpot account and create a local configuration file (hubspot.config.yml).
Generate a theme boilerplate using: hs create theme my-custom-theme
This will create a folder structure with all the necessary theme files.
Move into your theme folder: cd my-custom-theme
To deploy your theme to HubSpot, use: hs upload my-custom-theme my-hubspot-theme
For real-time changes, enable automatic file syncing: hs watch my-custom-theme
This ensures that any changes you make locally are immediately reflected in your HubSpot account.
Structuring your custom theme is a crucial step in ensuring scalability, flexibility, and ease of maintenance. Here's how you can organize your HubSpot theme efficiently:
A well-organized theme should follow HubSpot’s best practices:
Theme override settings allow users to customize specific design and functionality options without modifying the code. These settings are defined in the fields.json file and appear in the HubSpot Theme Editor.
In HubSpot, fields.json is a configuration file used in custom themes to define styling options that control the look and layout of a website. It allows developers to set up customizable fields—such as colors, fonts, spacing, and more—that appear in the Theme Settings panel. This makes it easy for marketers and content creators to update the design without needing to touch any code.
By using fields.json, developers can create flexible, brand-friendly themes that give non-technical users control over page styling. These fields can be accessed in templates and stylesheets using HubL variables (e.g., ), ensuring a consistent design across the site.
Overall, fields.json helps bridge the gap between code and content, making HubSpot themes more adaptable and easier to manage.
Theme Settings in HubSpot refer to the customizable design options available within a HubSpot theme that allow users to control the overall appearance of their website without editing code. These settings are defined in a file called fields.json and are presented in a user-friendly panel inside the page editor.
Theme Settings typically include options for:
These settings are made available using HubSpot’s design tools and can be dynamically accessed in templates and CSS using HubL variables like .
Theme Settings help maintain visual consistency across all pages and empower marketers and content creators to make style changes without relying on a developer.
themeoverride.css is a special optional CSS file in a HubSpot theme used to override default theme styles with custom or specific styling rules. It allows developers to make adjustments to the theme’s appearance without directly modifying the core CSS files, helping maintain clean code separation and easier theme updates.
When included in a theme, this file is typically loaded after the main theme styles, giving it higher specificity. That means any CSS declared in themeoverride.css can effectively override conflicting styles set earlier.
This file is useful for:
A template in HubSpot is a layout file that defines the structure and design of pages, emails, or blog posts. It can include drag-and-drop areas, modules, global elements (like headers/footers), and uses HubL (HubSpot Markup Language) to render content.
Templates dictate the structure of pages, blogs, and system layouts. Use templateType: "page" to define reusable layouts.
With the CMS boilerplate in your local environment, you'll now create a new module for the theme.
Custom Modules : These are reusable but independent components that can be customized per page.Used for dynamic content such as pricing tables, CTA sections, and testimonials.Users can place multiple testimonial modules on different pages, each with unique content.
After developing your theme and modules:
Branding settings ensure consistency across all website pages and make it easy for users to modify brand-related elements without touching the code.
To enable branding controls, update your fields.json file with the necessary fields for logo, colors, and typography:
Instead of manually adding a logo field in fields.json, use the HubSpot Brand Logo dynamically in your theme:
To ensure the best performance:
This guide equips you with the essential knowledge and step-by-step instructions to build your own custom theme in HubSpot CMS. By leveraging custom themes and modules, you gain full control over your website’s design, functionality, and branding, ensuring a unique and tailored digital experience.
With the right development environment, structured theme setup, override settings, and branding integration, you can create a professional and scalable HubSpot website that aligns perfectly with your business needs. Whether you're a developer aiming to build dynamic pages or a marketer looking to enhance user engagement, this guide helps you take full advantage of HubSpot’s powerful CMS.
By following these steps, you’re not just building a theme—you’re empowering your business with a custom solution that drives growth and engagement. Now, it’s time to bring your vision to life and launch your custom HubSpot theme!
If you plan to submit your theme to the HubSpot Marketplace, ensure it meets these requirements:
hs cms lighthouse-score: This command is used to run a Lighthouse audit on a HubSpot CMS website, either on an entire site or specific pages and templates.
By following this guide, you can build a fully customized HubSpot CMS theme and modules that align with your brand’s needs. A well-structured theme enhances user experience, performance, and scalability. Whether you're a developer creating dynamic pages or a marketer focused on engagement, custom themes and modules empower you to maximize HubSpot CMS’s potential.