Using modules in templates

Modules can either be added directly to a template or added to individual pages with drag and drop areas via the content editor. When a module is added to a template, the module will appear in that location by default. In contrast, modules added to drag and drop areas can be moved and removed, and other modules can be added around them. After a module has been defined, you can get its field values at the template level through the content.widgets dict.

Basic module syntax

You can include a module in a template file using {% %} statement delimiters, followed by specifying either module or dnd_module, depending on the implementation. dnd_module denotes a module within a drag and drop area. Then, configure the module using a set of module detail fields, listed below. These fields can be formatted as individual lines or as a single block.

{% module
  "unique_module_name"
  path="@hubspot/module_type",
  parameterString='String parameter value',
  parameterBoolean=True
%}

Parameter	Type	Description
`"unique_module_name"`	String	A custom name to identity the module, which should be unique within the context of the template. This name is used for populating the module with content added through the page editor. The name must be in quotes, and must be the second value defined within the module (after `module`/`dnd_module`). If a page contains multiple modules with the same name, content added through the page/email editor will appear in both module instances.
`path`	String	The path of the module, either the path found in design manager or a relative path when developing locally. HubSpot default module paths always start with `@hubspot/`.
Additional parameters	String \| Boolean \| Integer \| Enumeration \| JSON object	Additional parameters to configure the module’s behavior and how it renders. All modules have access to a set of common module parameters, such as `label`, along with parameters based on the included module fields. Parameter value syntax is based on the type of parameter. String values must be in single or double quotes (`"string"`/`'string'`) while boolean parameters do not require quotes (`True`/`False`). Note that there is no in-editor validation for field values. For example, if module has a number field that has a minimum value of `1`, and you pass into the parameter a `0`, you will not see a warning that the value is invalid.

Below are some additional examples of basic syntax for a default and custom module defined in a template.

{# HubSpot default text module #}
{% module "job_title"
  path="@hubspot/text",
  label="Job Title",
  value="Chief Morale Officer"
%}

{# Custom module #}
{% module "faqs"
  path="/myWebsite/modules/faq_module",
  label="Custom FAQ Module"
  faq_group_title="Commonly Asked Questions"
%}

In the design manager, you can copy a module’s basic HubL code by locating the module in the left sidebar, then right-clicking the module and selecting Copy snippet.

Screenshot of hte copy snippet option in the design manager

Passing dicts to module parameters

For modules with fields that expect dicts, you can pass them like you would other parameters. If it’s cleaner to you or you plan to re-use the values, you can set the dict to a variable, and pass the variable to the parameter instead.

{% module "social_buttons",
  path="@hubspot/social_sharing",
  email={
    "default": true,
    "enabled": false,
    "img_src": "https://..."
  }
%}

Passing fields that have dnd associated parameters

Drag and drop tags, such as dnd_area, come with a set of default parameters, such as width. While the design manager will prevent you from creating new fields that use one of these reserved parameters, modules created before drag and drop tags were introduced may already use a reserved parameter. To fix this, you can use the fields parameter. Just like you would pass field data to a group, you can pass the field name as a key on the fields object. Its value must be consistent with the format the field type expects.

{% dnd_area "main_content" %}
  {% dnd_section %}
    {% dnd_column %}
      {% dnd_row %}
        {% dnd_module path="@hubspot/divider",
          fields={width: "90"}
        %}
        {% end_dnd_module %}
      {% end_dnd_row %}
    {% end_dnd_column %}
  {% end_dnd_section %}
{% end_dnd_area %}

Setting default field values in templates

You can set default values for module fields at the template level by including parameters in the dnd_module tags. Below, learn how to set default field values in nested field groups, repeating fields, repeating field groups, and style fields.

Nested field groups

Below is an example of a custom drag and drop module with a custom style field group containing other nested field groups. Compare its template-level configuration with how this same grouping would appear in the design manager.

{% dnd_module
 path="/Nested_Module.module"
 style={
  "group":{
  "section":{
   "color_field":{
   "color" : "#000",
   "opacity" : 100
    }
   }
  }
 }
%}
{% end_dnd_module %}

Repeating fields

You can set template-level default values for repeating fields by passing an array to the field’s parameter. The array’s items must be in the format expected based on the field type. For example:

A simple text field only expects a string
An image repeater field expects an image field object. This applies to all of the other field types.

{% module "recipe_card"
  path='../modules/recipe_card.module',
  ingredients=["Eggs","Ham","Cheese"]
%}

{% module "my_repeater_module"
path="/img_repeater_module",
label="img_repeater_module",
image=[
  {
    "src" : "https://www.hubspot.com/hubfs/WBZ%202025%20Rebrand/Hub%20Logos/Icons%20SVGs/marketing-hub-logo-small.svg",
    "alt" : "Marketing Hub Logo",
    "width" : 80,
    "height" : 80
  },{
    "src" : "https://www.hubspot.com/hubfs/WBZ%202025%20Rebrand/Hub%20Logos/Icons%20SVGs/sales-hub-logo-small.svg",
    "alt" : "Sales Hub Logo",
    "width" : 80,
    "height" : 80
  }
]
%}

Repeating field groups

Modules that contain repeating groups of fields, like you might see in a slideshow module or FAQ module, can have a template-level default set for those groups. To do this, pass an array of objects to your field group’s parameter. The key-value pairs of the object are the field names and their values.

{% module path='../modules/slideshow.module',
  slides=[
    {
    "caption":"Cute dog looking up",
    "image_url":"http://example.com/image.jpg",
    },
    {
    "caption":"Cuter cat not looking amused",
    "image_url":"http://example.com/image2.jpg",
    }
  ]
%}

Style fields

you can explicitly set default values for style fields using the styles parameter. This works just like other groups do, where the parameter is the name of the group. You pass an object to that parameter with all of the fields you wish to set.

{% dnd_module
    path="./path/to/module",
    styles={
      "background_color":{
          "color":"#123",
          "opacity":50
       }
    }
%}

Block syntax

While most modules have parameters that control default content, there may be situations where you need to add large code blocks to the default content of a module. For example, you may want to include a large block of HTML as the default content for a rich text or HTML module. Rather than trying to write that code into a value parameter, insert the module using a {% module_block %} tag, then include within it a {% module_attribute %} tag that specifies content by the name of the field. As an example, the following code would insert a custom <p> element into the html field of a default rich text module instance.

{% module_block module
  "my_rich_text_module"
  path="@hubspot/rich_text",
  label="rich_text.module"
%}
  {% module_attribute "html" %}
    <p>Hello there!</p>
  {% end_module_attribute %}
{% end_module_block %}

Older HubSpot templates may contain the deprecated widget_block, widget_attribute, and type_of_module parameters. These parameters have been replaced by {% module_block %}/{% module_attribute %}. Learn more by expanding the section below.

Show legacy information

Prior to the module_block syntax, widget_block was used. It follows the same pattern, except that it used opening tags of widget_block, and widget_attribute, and closing tags of end_widget_attribute, end_widget_block.

The widget_block syntax is deprecated, but supported for backwards compatibility. It’s still recommended to use module_block moving forward.

The type_of_module parameter supports V1 HubSpot module names, for example: rich_text and raw_html. Additional parameters can be added to the first line of HubL. The second line defines which parameter the contents of the block will be applied to. For example, for a rich_text module this would be the html parameter. For a raw_html module, this would be the value parameter (examples below).

HubL
Output

{# widget_block is deprecated, use module_block instead.
This example is only to explain what type_of_module
 was used for, for those with legacy code. #}

{% widget_block rich_text "my_rich_text_module" overrideable=True, label='My rich-text module'  %}
  {% widget_attribute "html" %}
    <h2>New Module</h2>
    <p>Add content here.</p>
  {% end_widget_attribute %}
{% end_widget_block %}

<span
  id="hs_cos_wrapper_my_rich_text_module"
  class="hs_cos_wrapper hs_cos_wrapper_widget hs_cos_wrapper_type_rich_text"
  style=""
  data-hs-cos-general-type="widget"
  data-hs-cos-type="rich_text"
>
  <h2>New Module</h2>
  <p>Add content here.</p>
</span>

content_attribute

In addition to regular and block syntax, there are certain instances where you may want to specify a large block default content for a predefined content variable. The most common example of this proves to be the content.email_body variable. This variable prints a standard email body that can be altered in the content editor. Since this isn’t a standard HubL module, we use a content_attribute tag to specify a block of default content. The example below shows the email body variable populated with a default content code block.

{% content_attribute "email_body" %}
  <p>Hi {{ contact.firstname }},</p>
  <p>Describe what you have to offer the customer. Why should they read? What did you promise them in the subject line? Tell them something cool. Make them laugh. Make them cry. Well, maybe don't do that...</p>
  <p>Use a list to:</p>
  <ul>
    <li>Explain the value of your offer</li>
    <li>Remind the reader what they’ll get out of taking action</li>
    <li>Show off your skill with bullet points</li>
    <li>Make your content easy to scan</li>
  </ul>
  <p><a href="http://hubspot.com">LINK TO A LANDING PAGE ON YOUR SITE</a> (This is the really important part.)</p>
  <p>Now wrap it all up with a pithy little reminder of how much you love them.</p>
  <p>Aw. You silver-tongued devil, you.</p>
  <p>Sincerely,</p>
  <p>Your name</p>
{% end_content_attribute %}

Parameters available for all modules

While some modules have certain special parameters, below is a list of parameters supported by all modules.

Parameter	Type	Description	Default
`label`	String	The name of the module displayed in the content editor. This parameter can also be used to give users additional instructions.
`overrideable`	Boolean	Controls whether or not the module can be edited in the content editor, equivalent to the Prevent editing in content editors setting in the design manager.	`True`
`no_wrapper`	Boolean	When set to `True`, removes the wrapping markup from around the content of a module.On pages, modules are always wrapped in a `<div>` with special classes. This wrapping markup makes it so when you click the module in the preview pane, the editor scrolls to that module. There may be instances where you want to remove the wrapper, such as if you want to use a text module to populate the destination of an anchor tag `href` attribute.	`False`
`extra_classes`	String	Adds classes to the module wrapper. You can add multiple classes by separating the classes with spaces. For example:`extra_classes='full-width panel'`
`export_to_template_context`	Boolean	When set to `True`, instead of rendering the HTML, the parameters from this widget will be available in the template context. Learn how to use this parameter and the widget_data tag.	`False`
`unique_in_loop`	Boolean	When the module is defined within a loop, appends the module name with the loop.index. When set to `True`, a different version of the module will print within each iteration of the loop. Appends the module name with the loop.index.	`False`

Field-based parameters

When defining a module in a template file, you can pass additional parameters to the module based on the module’s defined fields. For HubSpot default modules, you can find available parameters in the default web modules reference. When working with modules locally, you can find a module’s fields in the fields.json file. The format for the parameter value depends on the field’s type. For example, the default button module includes a link field, which accepts a JSON object. In the template, you could pass those URL details as shown below.

{% module "button"
path="@hubspot/button",
button_text="Go Home"
link={
  "url":{
    "type": "EXTERNAL",
    "href": "/"
  },
    "open_in_new_tab": false,
    "no_follow": false
  }
%}

The field’s name determines how you specify it in the parameter override, so if the field were named link_field instead of link, your module code would need to include a link_field parameter instead.

{% module "custom_button"
path="/custom-button",
button_text="Click if you dare"
link_field={
  "url":{
    "type": "EXTERNAL",
    "href": "/"
  },
    "open_in_new_tab": false,
    "no_follow": false
  }
%}

Below, learn more about the available types of fields and the values they accept. For more information about field configuration, check out the module and field types reference.

Field	Type	Example
Blog	Integer (blog ID)	`1234567890`
Boolean	True/False	`False`
Choice	String	`"option_1"`
Color	Object	See color parameters
CTA	String (CTA ID)	`"fb9c0055-6beb-489d-8dda-3e1222458750"`
Date	Integer (timestamp)	`1566360000000`
Datetime	Integer (timestamp)	`1566360000000`
Email address	Array of email address strings	`["develop@hubspot.com", "design@hubspot.com"]`
File	String (URL of file)	`"https://cdn2.hubspot.net/hubfs/file.pdf"`
Follow Up Email	Integer (follow up email ID)	`1234567890`
Font	Object	See font parameters
Form	Object	See form parameters
HubDB Table	Integer (HubDB table ID)	`123456789`
Icon	Object	See icon parameters
Image	Object	See image parameters
Link	Object	See link parameters
Logo	Object	See logo parameters
Meeting	String (meeting link)	`"https://app.hubspot.com/meetings/developers-r-kewl"`
Menu	Integer (menu ID)	`123456789`
Number	Integer	`1`
Page	Integer (page ID)	`1234567890`
richtext	String (can contain HTML)	`"# Hello, world!"`
Salesforce Campaign	String (Salesforce campaign ID)	`"7016A0000005S0tQAE"`
Simple Menu	Array of menu item objects	See simple menu parameters
Tag	Integer (tag ID)	`1234567890`
Text	String	`"string it together"`
URL	Object	See URL parameters

Color parameters

Pass a color field parameter as a JSON object containing a hexadecimal color code and numerical opacity value.

{% module "my_module"
  path="../modules/my_custom_module",
  color={
    "color": "#ff0000",
    "opacity": 85
  }
%}

Font parameters

Pass a font field parameter as a JSON object containing font configuration details.

{% module "my_module"
  path="../modules/my_custom_module",
  font={
    "size": 12,
    "size_unit": "px",
    "color": "#000",
    "styles": {
      "text-decoration": "underline"
    },
    "font": "Roboto",
    "fallback": "serif",
    "variant": "regular",
    "font_set": "GOOGLE"
  }
%}

Form parameters

Pass a form field parameter as a JSON object containing form configuration details

{% module "my_module"
  path="../modules/my_custom_module",
  form={
    "form_id": "9aa2e5f3-a46d-4774-897e-0bc37478521c",
    "response_type": "redirect",
    "redirect_url": "http://www.hubspot.com",
    "redirect_id": null
  }
%}

Parameter	Type	Description
`form_id`	String	The form’s ID. Learn how to find a form ID in HubSpot.
`response_type`	String	The behavior after form submission. Can be one of: `inline`: an inline text message. `redirect`: redirect the visitor after submission.
`redirect_url`	String	The redirect URL (if redirecting)
`redirect_id`	String	The ID of a HubSpot page to redirect to (if redirecting)
`message`	String	The message to display after submission (if displaying an inline text message).

Icon parameters

Pass an icon field parameter as a JSON object containing FontAwesome icon configuration details.

{% module "my_module"
  path="../modules/my_custom_module",
  icon={
  "name": "apple",
  "unicode": "f179",
  "type": "SOLID"
  }
%}

Parameter	Type	Description
`name`	String	The icon’s name.
`unicode`	String	The icon’s unicode value.
`type`	String	The type of icon. Can be one of: `"SOLID"`, `"REGULAR"`
`redirect_id`	String	The ID of a HubSpot page to redirect to (if redirecting)
`message`	String	The message to display after submission (if displaying an inline text message).

Image parameters

Pass an image field parameter as a JSON object containing image configuration details.

{% module "my_module"
  path="../modules/my_custom_module",
  image={
    "src": "https://cdn2.hubspot.net/hubfs/image.jpeg",
    "alt": "an_image",
    "width": 100,
    "height": 100
  }
%}

Link parameters

Pass a link field parameter as a JSON object containing link configuration details. Learn more about url types in the link field reference.

{% module "my_module"
  path="../modules/my_custom_module",
  link={
    "url":{
      "type": "EXTERNAL",
      "href": "/"
    },
      "open_in_new_tab": false,
      "no_follow": false
    }
%}

Logo parameters

Pass a logo field parameter as a JSON object containing logo configuration details.

{% module "my_module"
  path="../modules/my_custom_module",
  logo={
    "override_inherited_src": true,
    "src": "https://cdn2.hubspot.net/hubfs/logo.png",
    "alt": "best_logo_ever",
    "width": 100,
    "height": 100
  }
%}

Pass a simple menu parameter as an array containing JSON objects of menu configuration details. You can link either to pages that are hosted in the HubSpot account, or external pages by URL.

{% module "my_module"
  path="../modules/my_custom_module",
  simplemenu=[
    {
    "isPublished": true,
    "pageLinkId": 123456789,
    "pageLinkName": "Page 1",
    "isDeleted": false,
    "categoryId": 1,
    "subCategory": "site_page",
    "contentType": "site_page",
    "state": "PUBLISHED_OR_SCHEDULED",
    "linkLabel": "Page 1",
    "linkUrl": null,
    "linkParams": null,
    "linkTarget": null,
    "type": "PAGE_LINK",
    "children": []
  },
  {
    "linkLabel": "Page 2",
    "linkUrl": "https://www.google.com",
    "linkTarget": "_blank",
    "type": "URL_LINK",
    "children": [
    	{
        "linkLabel": "Child 1",
        "linkUrl": "https://www.google.com",
        "linkTarget": "_blank",
        "type": "URL_LINK",
        "children": [],
      }
    ],
  }
]
%}

Parameter	Type	Description
`isPublished`	Boolean	Whether the page is published (for HubSpot-hosted pages).
`pageLinkId`	Integer	The page ID (for HubSpot-hosted pages).
`pageLinkName`	Boolean	The page’s name (for HubSpot-hosted pages).
`isDeleted`	Boolean	Whether the page has been deleted (for HubSpot-hosted pages).
`categoryId`	Integer	The ID of the page category. Can be one of: `1`: Website page `3`: Blog post `12`: Knowledge base article `4`
`subCategory`	String	The page subcategory. Can be one of: `site_page`, `landing_page`, `blog`, `normal_blog_post`.
`contentType`	Integer	The page’s content type. Can be one of: `site_page`,`landing_page`,`blog`
`state`	String	The publish state of the page. Can be one of: `DRAFT` `DRAFT_AB` `PUBLISHED` `PUBLISHED_OR_SCHEDULED` `PUBLISHED_AB` `SCHEDULED`
`linkLabel`	String	The text that will be displayed for the menu item.
`linkUrl`	String	The URL of the menu item.
`linkParams`	String	Query parameters appended to the link URL (for menu items of the `PAGE_LINK_WITH_PARAMS` type).
`linkTarget`	String	Set to `"_blank"` to open the link in a new browser tab.
`type`	String	The type of menu item. Can be one of: `"PAGE_LINK"` (HubSpot page) `"PAGE_LINK_WITH_PARAMS"` (HubSpot page) `"NO_LINK"` `"URL_LINK"` (external page)
`children`	Array	An array of sub-menu items.

URL parameters

Pass a URL field parameter as a JSON object containing logo configuration details. Similar to link field parameters, but with fewer customization options.

{% module "my_module"
  path="../modules/my_custom_module",
  link={
    "type" : "CONTENT",
    "href" : null,
    "content_id" : 123456789
  }
%}

Parameter	Type	Description
`type`	String	The type of link. Can be one of: `"EXTERNAL"`: for external links `"CONTENT"`: for website pages, landing pages, and blog posts `"FILE"`: for files hosted in the file manager `"EMAIL_ADDRESS"`: for email addresses `"BLOG"`: for blog index pages
`href`	String	The URL of the link.
`content_id`	String	The ID of the page you’re linking to (for HubSpot-hosted pages).

​Basic module syntax

​Passing dicts to module parameters

​Passing fields that have dnd associated parameters

​Setting default field values in templates

​Nested field groups

​Repeating fields

​Repeating field groups

​Style fields

​Block syntax

​content_attribute

​Parameters available for all modules

​Field-based parameters

​Color parameters

​Font parameters

​Form parameters

​Icon parameters

​Image parameters

​Link parameters

​Logo parameters

​Simple menu parameters

​URL parameters