HubSpot forms

Last updated:

Use HubSpot forms to capture information from website visitors, which you can then access throughout HubSpot. You can share links to forms directly with users, submit form data via the API, and embed them on your website pages using the CMS.

Forms are a core part of the HubSpot and can be created in HubSpot accounts of any subscription level. Not only are forms important for customer conversion, but also because form data can be used in other HubSpot tools and assets, such as smart content, lists, workflows, content personalization, and more.

After creating a HubSpot form, you can add it to your templates and pages. There are a few ways to add a form to a template, depending on your use case:

The default form module

If your template has drag and drop areas, content creators can add the default form module to a page from the page editor, then configure the form options in the left sidebar.

To code a form module directly into a template with drag and drop areas, reference it as a dnd_module. 

{% dnd_area "dnd_area" class='body-container body-container__landing', label='Main section' %} {% dnd_section vertical_alignment='MIDDLE' %} {% dnd_column width=6, offset=6 %} {% dnd_row %} <!-- Form module tag for use in templates --> {% dnd_module path='@hubspot/form' %} {% end_dnd_module %} {% end_dnd_row %} {% end_dnd_column %} {% end_dnd_section %} {% end_dnd_area %}

To add a form module to a template outside of a drag and drop area, you'll instead reference it as a standard module. 

{% module "form" path="@hubspot/form" form={ "form_id": "9e633e9f-0634-498e-917c-f01e355e83c6", "response_type": "redirect", "message": "Thanks for submitting the form.", "redirect_id": null, "redirect_url": "http://www.google.com" } %}

With either implementation, you can add parameters to the module tag to specify settings such as the form to use and redirect options, as shown in the code example above. See the default modules documentation for more information on available parameters.

Cloning the default module

In addition to using the default module as-is, you can clone it to make it editable, enabling you to customize it as needed. For example, you could clone the default form module, add a color field, then wrap the module's HTML in a <section> tag with styling to add the color as a background:

  • In the left sidebar design manager, navigate to the @hubspot folder, then right click form.module and select Clone module.
clone-form-module
  • In the right sidebar, click Add field, then select Color.
  • Add a <section> tag around the HTML content, then include styling to reference the color field, such as:

<section style="background:">

default-form-module-clone-section

Form fields in custom modules

When creating a custom module, you can include a form in it by adding a form field, along with adding the field's code snippet to the module HTML. For example, you may want to add a consultation request form to a module that contains an image of a product and a descriptive value proposition.

To add a form field to a custom module from the design manager:

  • In the right sidebar of the module editor, click Add field, then select Form.
design-manager-select-form-field
  • After adding the field, hover over the field in the right sidebar, then click Actions and select Copy snippet.
module-field-copy-snippet
  • Paste the snippet into the module's HTML field.

module-field-paste-snippet

Limit form options in the editor

Once added to a page, content creators typically have control over many aspects of the form, including which form to use and the form fields themselves. However, you can limit the amount of control given in the page editor by modifying the form module’s fields.json file locally to include the following fields:

Use this table to describe parameters / fields
ParameterTypeDescription
disable_inline_form_editing
String

Set the disable_inline_form_editing property to trueto hide all inline form editing controls in the form module. This includes the form fields, submit button text, data privacy and consent options, and CAPTCHA.

required_property_types
Array

An array that specifies which forms can be selected based on the property types of the form fields. Values include: "CONTACT", "COMPANY", and "TICKET".

For example, if you’ve built out a module that should only be used for forms that enable visitors to contact your company’s various services departments, you could allow content creators to only be able to select forms that use ticket properties.

// Form field { "id" : "843b4f0f-0ed7-5b10-e86a-5cc8a0f11a0c", "name" : "form_field_1", "display_width" : null, "label" : "Form", "required" : false, "locked" : false, "type" : "form", "disable_inline_form_editing": true, "required_property_types": ["TICKET"], "default" : { "response_type" : "inline", "message" : "Thanks for submitting the form." } }

Using the form embed code

When a module or HubL tag isn't ideal, or if you want to add a form to an external page, you can instead embed it using the form embed code. You can also customize the form embed code to extend the form's functionality. View all form embed code customization options and more in the forms reference guide.

Please note: 

  • Form customization options are only available for forms created in HubSpot that have been set as raw HTML. The HubSpot account must have a Marketing Hub or Content Hub Professional or Enterprise subscription.
  • HubSpot forms should only be loaded using the HubSpot-hosted JavaScript file. Making a copy of the form embed code and self-hosting it is not supported. Any improvements that HubSpot makes to improve security, anti-spam, accessibility, and performance will not propagate to your form if you decide to self-host the HubSpot form embed code.

Below is a sample of a form embed code without any customization.

<script charset="utf-8" type="text/javascript" src="//js.hsforms.net/forms/embed/v2.js"></script> <script> hbspt.forms.create({ region: "na1", portalId: "123456", formId: "df93f0c1-2919-44ef-9446-6a29f9a7f" }); </script>
Use this table to describe parameters / fields
ParameterTypeDescription
portalId
Required
Number or string

The ID of the HubSpot account that the form was created in. This is used to retrieve the form definition.

formId
Required
String

The form's ID, which is used to retrieve the form definition.

region
String

The region of the account where the form was created. This is used to retrieve the form definition. Possible values are na1 or eu1.

Add internationalization

By default, HubSpot provides a number of validation messages in many different languages, which you can access using the locale parameter. You can also add custom languages or override the error messages and date picker months/days displayed on the form using the translation parameter.

Learn more about internationalization and form validation error messages in the forms reference documentation.

hbspt.forms.create({ portalId: '', formId: '', locale: 'en', translations: { en: { fieldLabels: { email: "Electronic mail" }, required: "Hey! That's required!", submitText: "Custom Submit Button Text", submissionErrors:{ MISSING_REQUIRED_FIELDS: "Please fill in all required fields!" } } } });

Form events

Forms allow two ways to bind functionality onto events: callbacks in the HubSpot form embed code and global form events. Learn more about the available form embed code callbacks and global form events in the forms reference documentation.

// Example form embed code callback hbspt.forms.create({ portalId: '', formId: '', onBeforeFormSubmit: function($form) { // YOUR SCRIPT HERE } }); // Example listener window.addEventListener('message', event => { if(event.data.type === 'hsFormCallback' && event.data.eventName === 'onFormSubmitted') { someAnalyticsLib('formSubmitted'); console.log("Form Submitted! Event data: ${event.data}"); } });

Form styling

While HubSpot offers form styling from a global setting and form specific setting level, you can also style a form depending on how it's added to your CMS pages.

Please note: all forms generated on the HubSpot CMS (excluding using the form embed code) will ignore any styling that is configured via the global form settings or the form's individual settings. 

Styling forms via the default form module or HubL tag

HubSpot forms added to HubSpot pages can be styled using your website's CSS. HubSpot includes a number of different classes and attributes on forms that are generated where you can apply styling. As a starting point, refer to the HubSpot Boilerplate's form CSS, which represents the best practices for how to style forms.

Styling forms via a custom module

Forms inside custom modules can be styled by CSS in the module's CSS pane within the design manager. By keeping CSS scoped to the module, you can ensure that whenever the module is added to a page, the styling comes with it. It's recommended to add a wrapper to the form, then using that wrapper as the top-level selector for the CSS. This will prevent your custom module's form styling from being overwritten by additional styles in your websites main stylesheet. Below is a screenshot of the custom module from above with form styling added to the CSS Pane.

Custom Module with CSS

Styling forms added via the form embed code

When using the form embed code, you can style the form using the global form styling settings or using your website's CSS.

Using the global form styling settings enables you to configure default settings for every form in the account. You can also override these styles on an individual form within the form editor.

Global Form Styles

If you have a Marketing Hub or CMS Hub Professional or Enterprise subscription, you can select the Set as raw HTML form option when creating a form. This setting makes the form render as HTML instead of an iframe, which makes it easier to style the embedded form with CSS. 

Learn more about styling embedded forms on the Knowledge Base.

Set as raw HTML form setting

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.