There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

How to customize the form embed code

Last updated October 16, 2023

Use the options below to customize a HubSpot form's embed code and edit a default HubSpot form. Before getting started, do take note of the following:

  • These options are only available for forms created using the form editor in:
    • Marketing Hub Professional or Enterprise
    • CMS Hub Professional or Enterprise
  • These options can only be used with forms that have been set as raw HTML.
  • Other forms, such as collected forms or lead flows, do not support these customization options.

If you want to customize your form to add functionality not otherwise provided by HubSpot, use the methods documented in this article. If you require a more complex use-case and further customization over the styles and actions in your form, it is recommended to use the Forms API.

Learn how to generate an embed code on a form. For information on how to using the generated form, please see the developer documentation.

Please note: HubSpot forms should 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.

If you're using jQuery to manipulate the values of form inputs (i.e. using val() or prop()), you must trigger a change event using change() or trigger('change') for the change to properly register.


Examples:
$('input[value="checkbox_1"]').prop('checked', true).change();
$('input[name="firstname"]').val('Brian').change(); 
    
If not using jQuery:
input.value = value;
input.dispatchEvent(new Event('input', { bubbles: true }));

For Checkboxes:
input.click()
    

Configuration options

Tag legend:

  • R - (required) This attribute must be provided for the embed code to work properly.
  • O - (optional) Optional form customization attribute intended for use by end-users.

Attribute Type Types Description
portalId Number or String R The portal ID of the HubSpot account where you created the form. This is used to retrieve the form definition.
formId String R The form's ID, which is used to retrieve the form definition.
region String O The region of the portal where the form was created. This is used to retrieve the form definition. Possible values are na1 or eu1.
target String O A valid CSS selector string, specifying an existing element on the page into which the form will be embedded. NOTE: If you're including multiple forms on the page, it is strongly recommended that you include a separate, specific target for each form. It's strongly recommended you specify this property, otherwise the form is injected after the script location.
redirectUrl String O URL to which the form will redirect upon a successful form completion. Cannot be used with inlineMessage.
inlineMessage String O Inline message to display in place of the form upon a successful form completion. Cannot be used with redirectUrl.
pageId Number or String O ID of the CMS page that you're embedding the form on. Used to associate form submissions with the page.
cssRequired String O CSS string specific to validation error messages and form styling. Set this property to an empty string if you do not want to apply default HubSpot styling to the elements of your form.
cssClass String O CSS class that will be applied to the form.
css String O A CSS string that, when defined, is used instead of the built-in CSS theme. This can be used for setting your own CSS styling.
submitText String O String that overrides the text of the submit button.
submitButtonClass String O CSS class that will be applied to the submit input instead of the default .hs-button.primary.large.
errorClass String O CSS class that will be applied to inputs with validation errors instead of the default .invalid.error.
errorMessageClass String O CSS class that will be applied to error messages instead of the default .hs-error-msgs.inputs-list.
locale String O Locale for the form, used to customize language for form errors, the date picker, labels, and links. See the Add internationalized error messages section below.
translations Object O An object containing additional translation languages or to override field labels or messages for existing languages. See the Customize internationalization section below.
manuallyBlockedEmailDomain Array O Array of domains, specified as strings, to block in email input fields.
formInstanceId String O Required when embedding the same form on the same page multiple times. The value you specify here as the ID can be arbitrary, so long as it is not the same between forms.
sfdcCampaignId String O Set the Salesforce campaign key to associate form submissions with the campaign.
goToWebinarWebinarKey String O Set the GoToWebinar campaign key to enroll form submission contacts to a GoToWebinar webinar. The portal must have the GoToWebinar integration installed.
formInstanceId String O Required when embedding the same form on the same page multiple times. The value you specify here as the ID can be arbitrary, so long as it is not the same between forms.
onBeforeFormInit Function O Callback that executes before the form builds, takes form configuration object as single argument: onBeforeFormInit(ctx)
onFormReady Function O Callback that executes just before the form render. This callback should be used for any logic that needs to execute when the form has fully rendered on the page. Takes the jQuery form object as the argument: onFormReady($form)
onFormSubmit Function O Callback that executes after form is validated, before the form is submitted (i.e., right before the data is actually sent). This is for any logic that needs to execute before submission is initiated. Any changes made to form fields will not be validated. Takes the jQuery form object as the argument: onFormSubmit($form).

Note: It is not recommended to perform a browser redirect in this callback, as it could prevent the form submission. For any custom redirects, use the onFormSubmitted callback.
onBeforeFormSubmit Function O Callback that executes after the form is validated, before the form is submitted i.e. before the data is actually sent. This is for any logic that needs to execute before submission is initiated. Any changes made to fields will not be validated. .

Note: This callback behaves in the same way as onFormSubmit, but is preferred due to the accurate naming of when it is triggered. Takes the jQuery form object as the argument and an array of submission values: onBeforeFormSubmit($form, submissionValues). As in the case of onFormSubmit, It is NOT recommended to perform a browser redirect in this callback as this could prevent before the submission is initiated, thus preventing form submissions. For any custom redirects, please use the onFormSubmitted callback.
onFormSubmitted Function O Callback that executes after form submission. This is for executing actions when the submission is fully complete, such as displaying a confirmation or thank you message, or performing a custom redirect.

The callback's arguments are the form element and an object containing two properties:
  • redirectUrl: a string containing a redirectUrl, if set.
  • submissionValues: an object containing the submitted values from the form

onFormSubmitted($form, data)

Examples

Make labels/fields side-by-side instead of stacked

As the default CSS styling is 'stacked', i.e. labels atop inputs, removing the default classes on the form will result in an alignment of inputs to the right of their labels. To accomplish this, simply set your own custom cssClass that does not include the class 'stacked'. View the example in the right code pane.

Add internationalized error messages

HubSpot provides a number of custom validation messages in many different languages by default. View the example in the right code pane.

Key Language
enEnglish
daDanish
deGerman
esSpanish (Spain)
es-mxSpanish (Mexico)
fiFinnish
frFrench
itItalian
jaJapanese
nlDutch
plPolish
pt-brPortuguese
svSwedish
zh-cnChinese
zh-hkChinese (Hong Kong)

Customize internationalization

You can add custom languages or override the error messages and datepicker months/days displayed on the form by passing language objects into the translations parameter described above.

The embed code expects the format {locale: {messageKey: customMessage}}. You can override field labels by specifying the label as {locale: {fieldLabels: {fieldName: customLabel}}}, and the submit button text using {locale:{submitText: customSubmitText}} See the example in the right code pane.

To override existing messages, just pass in a language object with the desired locale found in the above table. For locales listed in the table above, you only need to provide the keys and messages you wish to override.

It's also possible to register new locale codes to use with the locale parameter. In this case, make sure to specify messages for all of the keys listed in the table below. Omitted keys will show a "missing translation" message in their place.

Key English default
learnMoreLearn more
submitTextSubmit
requiredPlease complete this required field.
invalidEmailPlease enter a valid email address.
invalidEmailFormatEmail must be formatted correctly.
invalidNumberPlease enter a valid number.
invalidNumberRangeTooSmallPlease enter a number that's greater than or equal to {{ min }}.
invalidNumberRangeTooLargePlease enter a number that's less than or equal to {{ max }}.
missingOptionSelectionPlease select at least one option.
missingSelectPlease select an option from the dropdown menu.
forbiddenEmailDomainPlease enter your business email address. This form does not accept addresses from {{ domain }}.
forbiddenEmailDomainGenericPlease enter your business email address. This form does not accept addresses from that domain.
manuallyBlockedEmailDomainPlease enter a different email address. This form does not accept addresses from {{ domain }}.
emailOptInPlease check your email to opt back in.
resubscribeMessageLooks like you've opted out of email communication. Click here to get an email and opt back in.
invalidDatePlease use the datepicker to match the {{ format }} format.
phoneInvalidCharactersMust contain only numbers, and the following symbols: + ( ) . - x
phoneInvalidCharactersWithoutCountryCodeMust contain only numbers, and the following symbols: + ( ) . - x
phoneInvalidRangeTooShortPlease enter a phone number that's at least { min } numbers long.
numbersOutOfRangeThe number you entered is not in range.
inputTooLargePlease use fewer than 65536 characters.
emailSuggestionDid you mean {{ email }}?
invalidDomainPlease enter a valid domain name and try again.
invalidCaptchaThe Captcha you entered is invalid. Please try again.
valueNotInFieldDefintionPlease choose one of the provided values.
previousMonthPrevious Month
nextMonthNext Month
januaryJanuary
februaryFebruary
marchMarch
aprilApril
mayMay
juneJune
julyJuly
augustAugust
septemberSeptember
octoberOctober
novemberNovember
decemberDecember
sundaySunday
mondayMonday
tuesdayTuesday
wednesdayWednesday
thursdayThursday
fridayFriday
saturdaySaturday
sundayShortSun
mondayShortMon
tuesdayShortTue
wednesdayShortWed
thursdayShortThu
fridayShortFri
saturdayShortSat
fallbackDescriptionWe had some trouble loading this form.
fallbackCtaClick here to continue.
fallbackGenericDescriptionThis form didn't load. Please try again later.
fileTooLargeSelected file is too large. Maximum allowed size is 100MB.
defaultSelectOptionLabelPlease Select
notYouNot you?
resetTheFormClick here to reset
submissionErrors.SERVER_ERRORSorry, something went wrong and the form was not submitted. Please try again later.
submissionErrors.RECAPTCHA_VALIDATION_ERRORFailed to validate Captcha. Please try again.
submissionErrors.MISSING_REQUIRED_FIELDSPlease complete all required fields.
submissionErrors.OUT_OF_DATEThis form is no longer current. Please refresh the page and try again.
submissionErrors.BLOCKED_EMAILPlease change your email address to continue.
submissionErrors.SUBMISSION_NOT_ALLOWEDThis form cannot be submitted. Please contact the site owner.
submissionErrors.DELETEDThis form is no longer active. Please refresh the page and try again.
submissionErrors.FORM_NOT_PUBLISHEDThis form is no longer active. Please refresh the page and try again.
submissionErrors.TOO_MANY_REQUESTSThere was an issue submitting your form. Please wait a few seconds and try again.
standaloneErrorPage.titleThis form no longer exists.