Reference information for using modules in templates.
Last modified: September 26, 2025
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
Report incorrect code
Copy
Ask AI
{% 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", } ]%}
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.
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.
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
Report incorrect code
Copy
Ask AI
{# 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 %}
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.
Report incorrect code
Copy
Ask AI
{% 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 %}
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'
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.
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.
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.
Report incorrect code
Copy
Ask AI
{% 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.
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.
Pass a URL field parameter as a JSON object containing logo configuration details. Similar to link field parameters, but with fewer customization options.
