HubSpot Theme Customization: The Complete Beginner’s Guide (2026)

HubSpot CMS is a powerful content management system that enables developers to create flexible, responsive, and reusable websites. One of its biggest advantages is the ability to build custom themes that marketers can easily edit using the drag-and-drop page editor.

In this guide, you’ll learn the fundamentals of HubSpot theme customization, understand the folder structure, customize templates, create reusable modules, and follow best practices for building professional HubSpot websites.

What is a HubSpot Theme?

A HubSpot theme is a collection of files that define the appearance, layout, and functionality of a website.

A theme typically includes:

• HTML templates

• HubL files

• CSS stylesheets

• JavaScript files

• Images

• Custom modules

• Theme settings

• Global content

Unlike traditional websites, HubSpot themes allow marketers to customize pages without touching code.

Typical Theme Folder Structure

my-theme/
│
├── css/
│   ├── main.css
│   └── responsive.css
│
├── js/
│   └── main.js
│
├── templates/
│   ├── home.html
│   ├── about.html
│   ├── blog.html
│   └── landing-page.html
│
├── modules/
│   ├── hero/
│   ├── faq/
│   ├── services/
│   └── testimonial/
│
├── partials/
│   ├── header.html
│   └── footer.html
│
├── images/
│
├── fields.json
├── theme.json
└── README.md

Keeping your files organized makes future maintenance much easier.

Understanding Theme.json

The theme.json file contains information about your theme.

Example:

{
  "label": "Business Theme",
  "preview_path": "./templates/home.html"
}

This file helps HubSpot identify and display your custom theme.

Theme Settings

Theme settings let marketers update colors, fonts, spacing, and branding without editing code.

Example settings include:

• Primary Color

• Secondary Color

• Font Family

• Button Radius

• Container Width

• Header Style

• Footer Background

Using theme settings makes themes reusable across multiple websites.

Customizing the Header

Most themes include a reusable header partial.

Example:

<header class="site-header">

{% module "navigation"
path="@hubspot/menu" %}

</header>

Benefits:

• Reusable across every page

• Easier maintenance

• Centralized navigation updates

Customizing the Footer

Example:

<footer class="site-footer">

<p>
© {{ local_dt|datetimeformat("%Y") }}
My Company
</p>

</footer>

Using dynamic dates ensures the copyright year updates automatically.

Loading CSS

Instead of inline styles, load external stylesheets.

{{ require_css(get_asset_url("../css/main.css")) }}

Advantages:

• Faster maintenance

• Better caching

• Cleaner templates

Loading JavaScript

{{ require_js(get_asset_url("../js/main.js")) }}

Keep JavaScript separate from templates for better organization.

Adding Custom Modules

Modules are reusable building blocks.

Example:

{% module
"path"="../modules/hero"
label="Hero Section"
%}

Examples of reusable modules:

• Hero Banner

• Services

• FAQ

• Team

• Pricing

• Contact Form

• Testimonials

• Call to Action

Using Drag and Drop Areas

Drag-and-drop areas let marketers rearrange page sections visually.

Example:

{% dnd_area "main_content" %}

{% end_dnd_area %}

This makes templates flexible without requiring code changes.

Creating Reusable Partials

Header:

{% include "../partials/header.html" %}

Footer:

{% include "../partials/footer.html" %}

Advantages:

• Less duplicate code

• Easier updates

• Better organization

Customizing Typography

Example CSS:

body{

font-family:
"Geologica",
Arial,
sans-serif;

font-size:16px;

line-height:1.6;

color:#333;

}

Maintain consistent typography throughout your website.

Customizing Buttons

.primary-btn{

background:#ff6600;

color:#fff;

padding:14px 28px;

border-radius:6px;

text-decoration:none;

transition:.3s;

}

.primary-btn:hover{

background:#e14d00;

}

Use consistent button styles across the theme.

Responsive Design

Example:

@media(max-width:768px){

.container{

padding:20px;

}

}

Always test themes on:

• Desktop

• Laptop

• Tablet

• Mobile

Accessibility Best Practices

Skip Link

<a class="skip-link"
href="#main-content">

Skip to main content

</a>

Labels

<label for="email">

Email Address

</label>

<input
id="email"
type="email">

Alt Text

<img
src="team.jpg"
alt="Marketing Team">

Screen Reader Only Text

.sr-only{

position:absolute;

width:1px;

height:1px;

overflow:hidden;

clip:rect(0,0,0,0);

white-space:nowrap;

}

Accessibility improves usability and SEO.

SEO Best Practices

Every HubSpot theme should include:

• One H1 per page

• Proper heading hierarchy

• Alt text on images

• Meta descriptions

• Optimized images

• Fast loading

• Semantic HTML

• Mobile responsiveness

Performance Optimization

Improve loading speed by:

• Compressing images

• Using SVG icons

• Minifying CSS

• Minifying JavaScript

• Lazy loading images

Example:

<img
src="banner.jpg"
loading="lazy"
alt="Hero Banner">

Common Theme Customization Mistakes

Avoid:

• Using inline CSS

• Hardcoding colors

• Duplicate code

• Too many modules

• Large image files

• Missing labels

• Missing alt text

• Ignoring responsive layouts

Recommended Theme Structure

A professional HubSpot theme usually includes:

• Header

• Footer

• Navigation

• Hero Banner

• About Section

• Services

• Features

• Pricing

• Testimonials

• FAQ

• Blog Listing

• Contact Form

• Call-to-Action

• Footer

Developer Tips

✔ Keep CSS modular.

✔ Use reusable modules.

✔ Create partials.

✔ Use theme settings.

✔ Optimize every image.

✔ Test responsiveness.

✔ Write semantic HTML.

✔ Follow accessibility standards.

✔ Keep JavaScript lightweight.

✔ Comment your code.

Frequently Asked Questions

What is the difference between a template and a module?

A template defines the overall page layout, while a module is a reusable content block that can be placed inside templates or drag-and-drop areas.

Why should I use drag-and-drop areas?

They allow content editors to rearrange and manage page sections without modifying code.

Can I reuse modules on multiple pages?

Yes. That’s one of the biggest advantages of HubSpot CMS themes.

Should I use inline CSS?

No. Keep styles in external CSS files for better performance and easier maintenance.

Is accessibility important?

Yes. Accessible websites improve usability, SEO, and compliance with modern web standards.

Conclusion

HubSpot theme customization is more than changing colors or fonts. A well-designed theme is modular, responsive, accessible, SEO-friendly, and easy for marketers to update without writing code.

By organizing your theme properly, using reusable modules, following accessibility standards, and optimizing performance, you can build professional HubSpot websites that are both developer-friendly and editor-friendly.

Whether you’re creating themes for clients, your own projects, or preparing for the HubSpot CMS Developer Certification, mastering theme customization is one of the most valuable skills you can learn.