Module and Theme Field Types
Themes and modules support a lot of different kinds of fields. The variety of fields enables the developer to provide the right editing experience for content creators. Since the UI is handled by HubSpot, all modules and themes have the same design for fields. These same field UI elements are used throughout the HubSpot app. This consistency makes it easier for content creators to familiarize themselves with the controls and get up and running.
To provide a better reference experience we've separated the field types from the module and theme field overview type information.
The information that has moved to the new page includes:
Fields all have a few properties in common, these properties control the variable names you use to reference their values and their appearance for content creators.
// Boolean field
{
"name" : "is_teaser_img",
"label" : "Enable Teaser Image",
"required" : false,
"locked" : false,
"type" : "boolean",
"inline_help_text" : "Shows Teaser image when toggled on",
"help_text" : "Teaser images are used to help provide visual context to the post.",
"default" : false
}| Parameter | Type | Description | Default |
|---|---|---|---|
help_text
| String | Text that will appear in the editor via tooltip to assist the content creator. Best used for information that is supplementary but not required to use the field. |
none
|
id
| String | Unique id for a field. This is generated by HubSpot. When building locally you do not need to specify this id. | |
inline_help_text
| String | Help text that will be shown inline below the label of the field (limit 300 chars). Best used for information required to use the field. |
null
|
label
| String | The text the content creator sees describing the field. May contain spaces. |
Rich text field, Date field, etc.
|
locked
| Boolean | Determines if the field is editable in the content editor. If "true", the field will not appear in the content editor. |
false
|
name
| String | The variable name you will use to refer to this field's values, and is what the value of the field is stored against. Cannot contain spaces or special characters. |
richtext_field, date_field, etc.
|
required
| Boolean | Determines if the field can be left blank in the editor. If true, content will not be allowed to publish without filling out this field. |
false
|
type
| String | The type of field see field types below for documentation on all field types. | |
visibility
| Array | Determines the display conditions for a field. |
Do not use inline_help_text and help_text interchangeably.
Instead ask yourself "Is this information necessary for a user to complete a task?".
- If the answer is yes, the information should be on the screen, and
inline_help_textis best. - If no, then it's okay to put in a tooltip using
help_text.
Keeping consistent to this helps users quickly understand the interface you provide them.
This field provides a way for content editors to select a blog, providing you, the developer the blog's id. This is useful for situations like pulling teaser information for featured blogs in modules. You can use the blog id in blog-related HubL functions to get information like blog authors, recent blog posts, recent blog posts with a specific tag, and more.
Blog fields are supported in modules.
// blog field
{
"name" : "blog",
"label" : "Blog",
"sortable" : false,
"required" : false,
"locked" : false,
"type" : "blog",
"default" : 1234567890
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| "default" / blog id | Specifies which blog is selected by default. This parameter accepts arguments of either 'default' or a blog ID (available in the URL of the Blog dashboard). |
null
|
This field provides a way for content editors to enable/disable functionality. Booleans can only be true or false. Often it makes sense to make groups or fields conditional based on boolean fields. If you think you might need to provide more than two states down the road, a Choice field may be a better option as you can grow into that with less effort should needs change later.
Boolean fields are supported in both themes and modules.
// Boolean field
{
"name" : "is_teaser_img",
"label" : "Enable Teaser Image",
"sortable" : false,
"required" : false,
"locked" : false,
"type" : "boolean",
"default" : false
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Boolean | Set's whether the default state of this field is |
false
|
Choice fields are kind of synonymous with <select> elements and radio buttons. They provide a way for a content creator to pick 1 item out of a list of options. They can take two forms visually in the page editor. You can set them to appear like a select field or radio buttons. The options for a choice field can have separate labels for their values. After a module's been used in a page the option labels can still be modified without negatively impacting sites since the value is still the same. Change the value however and any modules that previously had that value become disassociated.
Choice fields are supported in both themes and modules.
// Choice field
{
"name" : "img_position",
"label" : "Image Position",
"sortable" : false,
"required" : false,
"locked" : false,
"display" : "select",
"choices" : [ [ "img--left", "Image Left - Text Right" ], [ "img--right", "Text Left - Image Right" ] ],
"type" : "choice",
"default" : "img--left"
}| Parameter | Type | Description | Default |
|---|---|---|---|
choices
| Array | Array of value and label pairs. Values listed first. |
[
[ "value 1", "Label 1" ],
[ "value 2", "Label 2" ]
]
|
default
| Value | Sets the default selected value from the choice array. | |
display
| String | Sets which way the field displays to users. The two options are |
"select"
|
Color fields provide a color picker interface for content creators. They support solid colors as well as transparency. They are a perfect choice for when you want to give content creators full control over colors within a module.
Color fields are supported in both themes and modules.
// color field
{
"name" : "bg_color",
"label" : "Background color",
"sortable" : false,
"required" : false,
"locked" : false,
"type" : "color",
"default" : {
"color" : "#ff0000",
"opacity" : 100
}
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Object | Sets the default selected color and opacity. |
{
"color" : "#ffffff",
"opacity" : 100
}
|
Call-To-Action (CTA) fields provide a way for users to pick a CTA to display. CTA's are essentially trackable buttons or links. Content creators create CTAs that can be used throughout a site.
CTA fields are supported in modules.
// CTA field
{
"name" : "cta",
"label" : "CTA",
"required" : false,
"locked" : false,
"type" : "cta",
"default" : null
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| String | The default selected CTA. Expects a CTA id which can be found in the URL when editing a CTA in the CTA manager. |
null
|
Date fields provide a date picker interface to make it easy for content creators to select a date. Returns a timestamp you can use in your code.
Date fields are supported in modules.
// Date field
{
"name" : "event_start_date",
"label" : "Event Date",
"required" : false,
"locked" : false,
"type" : "date",
"default" : 1577854800000
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Timestamp | The Unix Epoch timestamp for the date and time you want to default to. Leave this null to allow the date and time picker to start the content creator at the current date and time in the picker. |
null
|
Date and time fields provide a date picker interface just like the date field, as well as a time picker to make it easy for content creators to select a date and time of day. Returns a timestamp you can use in your code.
Date and time fields are supported in modules.
// Date and time field
{
"name" : "event_start",
"label" : "Event Start",
"required" : false,
"locked" : false,
"type" : "datetime",
"default" : 1577854800000
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Timestamp | The Unix Epoch timestamp for the date and time you want to default to. Leave this null to allow the date and time picker to start the content creator at the current date and time in the picker. |
null
|
Email address fields allow a user to select multiple email addresses. This could be used for displaying contact information. The email field returns an array of selected email addresses you can loop through.
Email fields are supported in modules.
// Email address field
{
"name" : "emails",
"label" : "Email address",
"required" : false,
"locked" : false,
"type" : "email",
"default" : null
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Array | Array of email address strings |
null
|
File fields allow the user to upload a file to the file manager, or document manager, and make it easy to attach items that are in those locations. This can be useful for linking out to PDF files or files of other formats. For displaying images on a page you should use the image field.
File fields are supported in modules.
// Email address field
{
"name" : "file_field",
"label" : "File",
"required" : false,
"locked" : false,
"type" : "file",
"picker" : "file",
"default" : null
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Array | Array of email address strings |
null
|
picker
| String | Acceptable values: "file", "document", "image". |
file
|
Followup email fields allow a content creator to designate an email that will be sent in response to a form submission. This works in tandem with the HubL form tag, through the simple_email_campaign_id parameter.
Followup email fields are supported in modules.
// Followup email field
{
"name" : "followup_email",
"label" : "Followup email",
"required" : false,
"locked" : false,
"type" : "followupemail",
"default" : null
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| String | Email id |
null
|
Font fields provide content creators basic font styling controls. Content creators can choose the size, color, font family, and the format (bold, italic, and underlined). The listed fonts are all Google fonts and standard web-safe fonts.
Font fields are supported in both themes and modules.
// Font field
{
"name" : "font",
"label" : "Font",
"required" : false,
"locked" : false,
"load_external_fonts" : true,
"type" : "font",
"default" : {
"size" : 12,
"font":"Merriweather",
"font_set":"GOOGLE",
"size_unit" : "px",
"color" : "#000",
"styles" : { }
}
}Note: The font family is determined by the font and font_set combined. You must have both to load the font. When inheriting fields this means you need to inherit both values.
| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Object | Font object with settings for size, sizing unit, color, and styles for bold, italic, and underline. |
{
"size" : 12,
"size_unit" : "px",
"color" : "#000",
"styles" : { }
}
|
load_external_fonts
| Boolean | HubSpot automatically loads the selected web font to the page if the font is selected and referenced by HubL in a stylesheet or in a module. Set this to false, if you are already loading the font to the page, that way the font won't load twice. |
true
|
Form fields allow a content creator to designate a form in their account. You can then use this to render a form to a page using the HubL form tag.
Form fields are supported in modules.
// Form field
{
"name" : "form",
"label" : "Form",
"required" : false,
"locked" : false,
"type" : "form",
"default" : {
"form_id" : "f7110408-1935-4ed3-8a8e-293bb1c9d1ec",
"response_type" : "inline",
"message" : "Thanks for submitting the form.",
"gotowebinar_webinar_key" : null,
"form_type" : "HUBSPOT"
}
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Object | Object for forms containing the selected form id, response type and message. |
{
"response_type" : "inline",
"message" : "Thanks for submitting the form."
}
|
HubDB Table fields allow a content creator to designate a HubDB in their account. You can then use this to render a form to a page using the HubL form tag. Returns the table id, which you can use with the HubDB HubL functions.
HubDB Table fields are supported in modules.
// HubDB Table field
{
"name" : "recipe_table",
"label" : "Recipe Table",
"required" : false,
"locked" : false,
"type" : "hubdbtable",
"default" : 2010782
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| String | HubDB table id |
null
|
Icon fields provide an icon picker UI to make it easier for content creators to add icons to your modules. The Icon field is preloaded with FontAwesome Icons.
Icon fields are supported in modules.
// Icon field
{
"name" : "icon_field",
"label" : "Icon",
"required" : false,
"locked" : false,
"type" : "icon",
"default" : {
"name" : "accessible-icon",
"unicode" : "f368",
"type" : "REGULAR"
}
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Object | Icon object |
Image fields provide an easy interface for content creators to add images to a module or theme. Image fields provide a file picker interface that lists images from the File Manager. Since images can be used and displayed in different ways, developers can limit the sizing options available to the content creator in the UI.
Image fields are supported in modules.
// Image field
{
"name" : "bg_img",
"label" : "Background Image",
"required" : false,
"locked" : false,
"responsive" : true,
"resizable" : true,
"type" : "image",
"default" : {
"size_type" : "auto",
"src" : "",
"alt" : null
}
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Object | Image object containing parameters for the sizing preference, src, and alt text. |
{
"size_type" : "auto",
"src" : "",
"alt" : null
}
|
responsive
| Boolean | determines if the image is to act responsively or have a fixed height and width. |
true
|
Link fields provide an easy interface for content creators to provide links to URLs and email addresses. For external links, content creators choose "external". For email links "email address". Finally for content hosted on the HubSpot CMS they can use "content" which shows a list of all pages and blog posts in the account, file showing file assets, and blog, showing all of the blog listings in the account. Link fields are very similar to URL fields except for the key difference that they provide a UI for "open in new window" and "tell search engines not to follow". If you do not want content creators to have that control use the URL field.
Link fields are supported in modules.
// Link field
{
"name" : "link",
"label" : "Link",
"required" : false,
"locked" : false,
"supported_types" : [ "EXTERNAL", "CONTENT", "FILE", "EMAIL_ADDRESS", "BLOG" ],
"type" : "link",
"default" : {
"url" : {
"content_id" : null,
"type" : "EXTERNAL",
"href" : ""
},
"open_in_new_tab" : false,
"no_follow" : false
}
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Object | URL object |
{
"url" : {
"content_id" : null,
"type" : "EXTERNAL",
"href" : ""
},
"open_in_new_tab" : false,
"no_follow" : false
}
|
supported_types
| Array | list of the types of links this field allows content creators to select. Remove types from the list that you don't want content creators to have access to set. |
[ "EXTERNAL", "CONTENT", "FILE", "EMAIL_ADDRESS", "BLOG" ]
|
Logo fields provide a way for content creators to specify logo images to use in a page, defaulting to the domain's logo. This is useful for site headers and footers that may contain the company logo.
Logo fields are supported in modules.
// Logo field
{
"name" : "logo",
"label" : "Logo",
"required" : false,
"locked" : false,
"type" : "logo",
"default" : {
"override_inherited_src" : false,
"src" : null,
"alt" : null
}
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Object | Logo object |
{
"override_inherited_src" : false,
"src" : null,
"alt" : null
}
|
Menu fields provide an easy interface for content creators to create, edit and select a navigation menu that is re-usable on other pages. This field is great for use in menus that are used across multiple pages like main navigation and footer navigation and other global content. Use this field in tandem with the menu tag or menu() function, to render a menu inside of your module.
For menus that do not make sense to re-use on other pages, like a table of contents menu for a really long page, use the simple menu field.
Menu fields are supported in modules.
// Menu field
{
"name" : "menu",
"label" : "Menu",
"required" : false,
"locked" : false,
"type" : "menu",
"default" : 12345678911
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| integer | The menu ID for the menu. The default value of |
null
|
Number fields provide an easy interface for content creators to enter in or adjust numerical values and options. This can be used for creating percentage based items or anything where numbers are needed for input.
Number fields are supported in modules.
// Number field
{
"name" : "number_field",
"label" : "Number",
"required" : false,
"locked" : false,
"display" : "slider",
"min" : 1,
"max" : 10,
"step" : 1,
"type" : "number",
"default" : null
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Number | A default number to be used. |
null
|
Page fields provide an interface for content creators to select site pages and landing pages.
The value returned by a page field is the page id of the selected page. When used in tandem with the content_by_id or content_by_ids functions, you can use data from the selected pages in the current page.
Page fields are supported in modules.
// Page field
{
"name" : "page_field",
"label" : "Page",
"help_text" : "Pulls data from the selected page.",
"required" : false,
"locked" : false,
"placeholder" : "Page to pull from",
"type" : "page",
"default" : null
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Integer | A default page id to be selected. |
null
|
Rich Text fields provide content creators with a WYSIWYG text editor experience. When a rich text field's value is printed it is printed as HTML. When you do not want content creators to have formatting capabilities use text fields.
Rich text fields are supported in modules.
// Rich text field
{
"name" : "description",
"label" : "Description",
"required" : false,
"locked" : false,
"type" : "richtext",
"default" : null
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| String | string of content to be displayed supports HTML |
""
|
Simple menu fields provide an easy interface for content creators to create a navigation menu that is not re-usable on other pages. For menus that should be reusable, use the menu field. A time you may want this is for a table of contents menu that links to headings on very long pages, or a list of links to content that only makes sense to have on the current page.
Simple menu fields are supported in modules.
// Simple menu field
{
"name" : "toc_menu",
"label" : "Table of Contents",
"required" : false,
"locked" : false,
"type" : "simplemenu",
"default" : [ {
"isPublished" : false,
"pageLinkId" : null,
"pageLinkName" : null,
"isDeleted" : null,
"categoryId" : null,
"subCategory" : null,
"contentType" : null,
"state" : null,
"linkLabel" : "Why is product marketing important?",
"linkUrl" : null,
"linkParams" : null,
"linkTarget" : null,
"type" : "NO_LINK",
"children" : [ {
"isPublished" : false,
"pageLinkId" : null,
"pageLinkName" : null,
"isDeleted" : null,
"categoryId" : null,
"subCategory" : null,
"contentType" : null,
"state" : null,
"linkLabel" : "Product Marketing Responsibilities",
"linkUrl" : "#product-marketing-responsibilities",
"linkParams" : null,
"linkTarget" : null,
"type" : "URL_LINK",
"children" : [ ]
}, {
"isPublished" : false,
"pageLinkId" : null,
"pageLinkName" : null,
"isDeleted" : null,
"categoryId" : null,
"subCategory" : null,
"contentType" : null,
"state" : null,
"linkLabel" : "1. Identify the buyer personas and target audience for your product.",
"linkUrl" : "#step1",
"linkParams" : null,
"linkTarget" : null,
"type" : "URL_LINK",
"children" : [ ]
}, {
"isPublished" : false,
"pageLinkId" : null,
"pageLinkName" : null,
"isDeleted" : null,
"categoryId" : null,
"subCategory" : null,
"contentType" : null,
"state" : null,
"linkLabel" : "2. Successfully create, manage and carry out your product marketing strategy.",
"linkUrl" : "#step2",
"linkParams" : null,
"linkTarget" : null,
"type" : "URL_LINK",
"children" : [ ]
} ]
}, {
"isPublished" : false,
"pageLinkId" : null,
"pageLinkName" : null,
"isDeleted" : null,
"categoryId" : null,
"subCategory" : null,
"contentType" : null,
"state" : null,
"linkLabel" : "How HubSpot can help",
"linkUrl" : "https://hubspot.com",
"linkParams" : null,
"linkTarget" : null,
"type" : "URL_LINK",
"children" : [ ]
} ]
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Array of objects | JSON structure for menu and menu children. |
[]
|
Tag fields provide a blog tag picker for content creators. This tag picker returns a blog tag id which can then be used in blog tag related functions such as Blog Tag URL and Blog Recent Tag Posts.
Tag fields are supported in modules.
// Tag field
{
"id" : "c3395cd3-8e60-7e47-2f1b-b7ccf4d669c9",
"name" : "blog_tag",
"label" : "Blog Tag",
"required" : false,
"locked" : false,
"tag_value" : "SLUG",
"type" : "tag",
"default" : null
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| String | Blog tag id |
null
|
Text fields provide content creators a simple text editing experience with no rich text functionality. Text fields initially show as a single line, but can actually expand to be textareas, supporting multiple lines. Use these when you do not want content creators to have control over formatting. If you do want to provide formatting controls use rich text fields.
Text fields are supported in modules.
// Text field
{
"name" : "product_name",
"label" : "Product Name",
"required" : false,
"locked" : false,
"validation_regex" : "",
"allow_new_line" : false,
"show_emoji_picker" : false,
"type" : "text",
"default" : null
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| String | Text string. |
""
|
URL fields provide a similar experience to link fields. Providing a UI for content creators to add links. URL fields, however, do not show a UI for open in a new window, nor tell search engines not to follow. Use this field when you as a developer want to dictate the values for that. If you want the user to have control, use link fields instead.
URL fields are supported in modules.
// URL field
{
"name" : "url",
"label" : "URL",
"required" : false,
"locked" : false,
"supported_types" : [ "EXTERNAL", "CONTENT", "FILE", "EMAIL_ADDRESS", "BLOG" ],
"type" : "url",
"default" : {
"content_id" : null,
"href" : "http://example.com",
"type" : "EXTERNAL"
}
}| Parameter | Type | Description | Default |
|---|---|---|---|
default
| Object | URL object, with type, href and content id (if content is a page or post on HubSpot) |
{
"content_id" : null,
"href" : "",
"type" : "EXTERNAL"
}
|
supported_types
| Array | list of the types of links this field allows content creators to select. Remove types from the list that you don't want content creators to have access to set. |
[ "EXTERNAL", "CONTENT", "FILE", "EMAIL_ADDRESS", "BLOG" ]
|