HubSpot Template Marketplace theme requirements

Learn more about the requirements a theme must meet for submission to the HubSpot Template Marketplace. 

Keep in mind the following limits per theme:

• Free CMS Hub accounts cannot use site search or CTA functionality. Learn more about what's included with CMS Hub subscriptions in HubSpot's Product & Services catalog.
• Themes cannot contain more than:
  • 50 templates
  • 50 modules
  • 50 sections

• Themes must not contain:
  • Email templates
  • HubDB functionality
  • Serverless functions
  • CRM object fields.
  • Membership templates
  • Flexible columns in templates

Using Google Lighthouse, a theme must score higher than the following thresholds:

• Desktop accessibility: 65
• Desktop best practices: 80
• Desktop performance: 70
• Mobile performance: 40

Learn how to generate a Google Lighthouse report for your theme using the CLI.

In addition, theme assets must meet the following performance and accessibility requirements:

• Theme files should be able to be successfully minified.
• All image files should be under 1MB in size.
• All image tags should have an alt attribute (a value of "" is acceptable).
• All image tags should have a loading attribute (a value of "" is acceptable).

Themes in the marketplace must meet the following requirements:

• All submitted themes must be distinct. For example, the same theme with different copy or placeholder content does not count as a distinct theme. 
• A theme must be built with HTML + HubL templates and dnd_area tags.
• You must use sections wherever applicable. There must be a minimum of five sections in a theme. 
• You must incorporate usable drag-and-drop areas in headers and footers. 
• Themes must respect a 12-column grid.

In addition, themes must meet the following minimum requirements across their templates, theme field options, theme.jsonand field.json configurations, and module fields.

At a minimum, a theme must include the following template types:

• A website page template or landing page template.
  • When including multiple-page templates, each template must have a distinct purpose. For example, a home page, an About Us page, a full-width landing page, and a landing page with a right sidebar.
  • It is recommended to include at least eight page templates in a theme. 

• Separate blog listing and blog post templates.
  • Blog listing template: the page that shows all blog posts in a listing format (known as the blogroll). The template title must reflect that it's for the listing page.
  • Blog post template: the blog post detail page that displays individual blog posts. The template title must reflect that it's for the blog post page.
  • In addition, blog comments and blog author boxes must be styled to match the theme.

• The following system page templates:
  • 404 error template: shown when visitors hit a page that doesn't exist.
  • 500 error template: shown when the site encounters an internal error.
  • Password prompt template: shown when a page is password protected.
  • Subscription template: a subscription preferences page where email recipients can manage the types of emails they're subscribed to.
  • Subscriptions update template: a confirmation page that appears when an email recipient updates their email subscription preferences.
  • Backup unsubscribe template: the page that appears for email recipients who are trying to unsubscribe if HubSpot is unable to determine their email address.
  • Search results template: displays search results returned when using the site search. Available for paid CMS Hub accounts only.

At a minimum, a theme must include the following theme fields: 

• Typography fields:
  • Body text font fields ( p tags)
  • h1 through h6 font fields
  • Hyperlink color ( a tags), including hover styling
• Form fields:
  • Title background
  • Title text, including at least font color styles
  • Form background color
  • Form border color
  • Form label color
  • Form field border color
  • Form button, including settings for both button text, background color, and hover styling

In addition, theme fields must meet the following requirements:

• Fields inside of your theme must be grouped logically where appropriate. For example, multiple fields related to typography should be grouped under a Typography group.
• Theme fields must have the following globally applied elements:
  • Primary, secondary, and tertiary color fields
  • Heading font fields
  • Body font fields
• Theme fields should have separate color and font controls for buttons and forms, as well as separate color, logo, and font controls for the header and footer. 
• A portion of the theme's color and logo fields must inherit from the account's brand settings:
  • At a minimum, two color fields must inherit colors from the account's brand settings. Additional color fields can default to other colors, including black and white.
  • If modules within a theme are using logos, at least one logo field must inherit from the account's brand settings. If using an image field to render a logo, the image field does not have to inherit from the brand settings.

The theme.json file must include the following parameters:

Learn more about these parameters in the theme.json documentation.

The fields.json file controls the available fields and field groups in the theme editor, including style fields. The fields you include will depend on how much control you want content creators to have in the page editor. The fields.json file must contain at least three color fields.

To ensure compatible functionality between themes and independent modules, themes must include the following font and color standard naming conventions: primary_color, secondary_color, heading_font, and body_font.

If theme fields do not have primary_color, secondary_color, heading_font, or body_font fields, they can use the alternate_names field. Learn more about this requirement here.

 Learn more about these parameters in the fields.json documentation and review an example fields.json file from the HubSpot CMS Boilerplate. 

Theme settings must adhere to the following requirements.

Theme settings must not conflict with your editor styles or styles set through a module. For example, do not use !important in your CSS, as it makes it difficult for end users to override and would cause a conflict.

Theme settings must use descriptive labels for each setting so that content creators know what they're updating.

Theme settings must apply to all templates in a theme, unless there's a specific use case for additional styles. For example, changes to the style and size of h1 headings in settings must apply across all h1 tags in the theme.

Themes must include global partials. Global partials are a type of template built using HTML and HubL to can be reused across your entire website. The most common type of partials are website headers, page sidebars, and website footers. 

Global partials must include usable drag and drop area. For menus that are used globally throughout a site, users must also be able to select a HubSpot navigation menu they've created in their account settings.

Learn how to create global partials.

All themes should contain a proper folder structure and be grouped under one parent folder, which should describe your product listing. For example, if you build a theme named “SuperAwesome” for the marketplace, your structure should look similar to the image below. Learn more about theme file structure. 

When creating preview URLs you must use your own domain name. You cannot use the HubSpot-provided domain with this URL structure: [AccountID].hs-sites.com

A live website and not an image of the demo site must be used. 

If at any point your live demo becomes inaccessible, HubSpot reserves the right, with notification to the provider, to delist/remove your theme until the live demo becomes accessible again.

You must use relative local file paths when referring to theme assets. The best way to include these is to use the get_asset_url function, which returns the public URL of an asset, file, or template. You can also generate this function by either right-clicking a file and selecting Copy public URL, or by clicking Actions, then selecting Copy public URL. 

For example, a stylesheet referenced by require_css must be formatted as follows:

If your theme relies on jQuery, a version of the jQuery must be included in the event that it's not enabled by default in a customer’s account. 

For example, if you include a module that requires jQuery when the rest of the site doesn’t, you would need to use the following code to load jQuery:

Themes must be able to support multiple language versions and should specify the languages that they support. This can be done by adding the language switcher module in a global header, which allows customers to easily locate the language options and choose their desired language.

• You must only display one language at a time. For example, avoid having both English and Spanish in the UI at the same time.
• Avoid using hard-coded text. For example, rather than hard-coding a blog listing button’s text as Read More, set the text within a field so that the end user can update the text without having to go into the code.