Skip to main content

Releasing a new version of a module, rather than update the existing version, enables HubSpot to make significant updates without impacting existing content. For example, HubSpot may release a new version of a particular module to better organize fields and provide more styling options, or to improve functionality by adding JavaScript.

New versions of modules are first released to new HubSpot accounts created after a certain date. This means that different accounts may be using different versions of the same default module. If multiple accounts are using a theme that you built, you'll need to take module versioning into consideration so that the theme works as expected across all accounts. Below, learn more about how to develop your theme with versioning in mind, and which modules have multiple versions.

HubSpot's existing default modules are treated as v0 modules, while new versions are released started at v1. For compatibility, HubSpot automatically maps v0 fields to v1 fields, which means that references to module fields are forward compatible. However, field references are not backwards compatible, meaning that v1 field references won't map to v0 fields.

To account for changes in an module's HTML, CSS, and JavaScript, you can use conditional statements to configure it depending on the account's available versions.

To add add a conditional statement, use get_asset_version("@hubspot/module-name") within an HTML, CSS, or JavaScript file. The module's version will be returned as a string, enabling you to configure module options based on the returned version.

When developing a theme, you can specify which module versions that you want to support within the theme.json file. When a version is specified, content editors will only allow access to that version in the editor, and the template will render that version accordingly. On upload via the CLI, or when making changes in the design manager, specified module versions will be validated to ensure validity of the modules and their version definitions.

You can specify supported module versions in theme.json by including a pinned_module_versions object. For each module, you can specify a version or a range of versions.

For example, the code below would result in the theme allowing access to either v0 or v1 of the divider module, but only v1 of the search input module.

Any default modules not included in the pinned_module_versions object will not be restricted to a particular version. In addition, you shouldn't specify versions of default modules that don't currently support versioning, and you can only specify versions that are available (e.g. you can't specify 2 for a module that doesn't have a v2).

Learn more about submitting to HubSpot's Template Marketplace.

In an account's Themes & Modules settings (Settings >** Content** > Themes & Modules) users can opt into new module versions, revert  modules updated within the past 30 days, and view the version information for all default modules.

To opt into a new version of a module:

  • In your HubSpot account, click the settings icon in the top navigation bar.
  • In the left sidebar menu, navigate to ContentThemes & Modules.
  • On the Alerts tab, the latest updates for default modules will appear with an Update Available tag. Click View update next to a module to view more details about the update.

themes-and-modules-settings-alerts-tab-view-update

  • In the panel, review the changes. The panel will include a high-level summary of the update, along with a detailed breakdown of the changes and the assets that will be affected.

versioning-details-sidebar-panel

  • To update the module, click Install update. Then, in the dialog box, click Confirm update. Note that it can take up to 10 minutes for pages and templates to reflect the updated module.

After updating the module, you'll be taken to the Modules tab of the Themes & Modules settings page. On this page, you can see recently updated modules, modules with available updates, and version information for all your account's default modules.

themes-and-modules-settings-modules-tab-recently-updated

Within 30 days of updating a module, you can revert it to a previous version if needed:

  • On the Modules tab, next to the module that you want to revert, click Roll back recent update.

roll-back-recent-update-button

  • In the panel, review the module's version history, then click Roll back this update.

roll-back-recent-update-button

  • Review the information in the right sidebar to confirm that you'd like to roll back the update, then click Roll back.
  • In the dialog box, click Confirm.

After reverting the update, it may take some time for your templates and pages to reflect the reverted module. At any point, you can update the module again by following the update steps above.

Below, learn more about the modules that currently support versioning.

A new version of the default divider module has been released to accounts created after August 25th, 2022 (changelog announcement). This version update impacts the following module files:

  • fields.json
  • module.html

Below, learn more about the new v1 version updates in each file, along with the original v0 version for comparison.

  • All fields that were previously in the Content tab have been moved to the Styles tab.
  • The following fields have moved, but HubSpot automatically links the previous references to the new field names, so you don't need to make any manual updates:
    • The height field has been moved to styles.line.thickness.
    • The width field has been moved to styles.size.width.
    • The color field has been moved to styles.line.color.
    • The line type field has been moved to styles.line.style.
  • The alignment field, which was previously a choice field, has been replaced by a new field type of Alignment, and can be accessed under styles.alignment.alignment.
  • The padding field, which was previously a number field, has been replaced by a new field type of Spacing, and can be accessed under styles.spacing.spacing.
  • The show_padding field has been removed.

A new version of the language switcher module has been released.

language-switcher-in-editor

This version update impacts the following module files:

  • meta.json
  • fields.json
  • module.html
  • module.css
  • module.js

Below, learn more about the new v1 version updates in each file, along with the original v0 version for comparison.

A placeholder field has been added with the following options:

  • show_module_icon (boolean): when set to false, no icon will appear.
  • title (string): the placeholder title.
  • description (string): the placeholder descriptive text.

A new version of the default post_listing module was released at the end of March 2024. The new version of this module is built with JavaScript and React as opposed to HubL, and module code is now rendered server-side to improve performance.

It preserves all of the previous module fields while bringing in some modern styling options for the user with new fields for text and layout.

Below, learn more about the new v1 version updates in each file, along with the original v0 version for comparison.

The fields.json is file replaced by fields.tsx.

Existing fields

The new version of the module includes all existing module fields.

  • selectBlog: a field for selecting the blog to display posts from (aliased to the existing select_blog field).
  • listingType: a field for selecting the attribute to list posts by (aliased to the existing listing_type field).
  • postsHeading: a field for setting the heading text at the top of the listing (aliased to the existing list_title field).
  • maxLinks: a field for setting the maximum number of blog posts to display (aliased to the existing max_links field).

New fields

  • A displayForEachListItem choice field has been added to enable selecting the elements that will display for each blog post, including:
    • Featured image (image)
    • Post title (title)
    • Author name (authorName)
    • Publish date (publishDate)
  • A headingLevel choice field has been added to enable selecting the postsHeading level (h1 - h6).

Style fields

The following styling fields have been added:

  • Layout styling: a groupLayout field group contains a style choice field for selecting whether the posts will display as rows or 2-column tiles.
  • Heading styling: a groupHeading field group contains a font field for styling postsHeading.
  • Post title styling: a groupTitle field group contains font, spacing, and hoverFont fields for styling post titles.
  • Author styling: a groupAuthor field group contains a font field for styling the post author name text.
  • Publish date styling: a groupPublishDate field group contains a font field for styling the publish date text.
  • Background styling: a background field group contains backgroundColor and spacing fields to style the module background.

A new version of the default search input module has been released. This version update impacts the following module files:

  • fields.json
  • module.html
  • module.css
  • module.js

Below, learn more about the new v1 version updates in each file, along with the original v0 version for comparison.

Existing fields

  • The field_label and placeholder text fields have been moved into the search group.
  • The include_search_button toggle has been removed.
  • The content_types group has been moved into the results group.

New fields

  • A button group has been added, which enables controls for:
    • icon: the search button's icon.
    • button_label: the search button's text label.
  • A results group has been added, which enables controls for:
    • use_custom_search_results_template: toggle to choose which template is used for the search results page.
    • path_id: the ID of the page that will be used for search results. The referenced page must contain the search results module.
  • A default_text group has been added, which allows for the translation of default content.

Style fields

The following style field groups have been added:

  • container: fields for styling the module container's background color, border radius, and spacing.
  • field_label: fields for styling the module's label font and spacing.
  • input: fields for styling the search input's font, spacing, background color, border, and corner radius.
  • button: fields for styling the button's font, background color, border, corner radius, and spacing. Also includes options for hover styling and button positioning.
  • autosuggest_results: fields for styling the auto-suggested results box's background color, border, border radius, spacing, header font, suggestion link font, hover font, and hover background color.

A new version of the default search results module module has been released. This version update impacts the following module files:

  • fields.json
  • module.html
  • module.css
  • module.js

Below, learn more about the new v1 version updates in each file, along with the original v0 version for comparison.

Existing fields

  • The display_featured_images field has been moved to the results group and renamed to display_for_each_result.

New fields

  • A title group has been added, which enables controls for:
    • show_title: a toggle for whether the title displays.
    • heading_tag: the search results heading level (h1 by default).
  • A pagination group has been added, which enables controls for pagination, such as showing the number of pages and the previous/next arrows and labels.
  • A default_text group has been added, which allows for the translation of default content.

Style fields

The following style field groups have been added:

  • container: a field for styling the module container's spacing.
  • title: fields for styling the page's title font and capitalization options.
  • results_count_message: fields for styling the page's result count font and capitalization.
  • featured_image: fields for styling the featured image's size, aspect ratio, border, radius, and spacing.
  • results: fields for styling the returned result title and description fonts, as well as spacing between results.
  • pagination: fields for styling the pagination fonts, icon size, background colors, spacing, border, and corner radius. Includes options for hover styling.