Skip to main content

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. Below, find reference documentation for forms, including form embed configuration options, internationalization and validation error messages, and form events.

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.

When embedding a form, you can include the following customization options in the form embed code.

ParameterTypeDescription
portalIdRequiredNumber or stringThe ID of the HubSpot account that the form was created in. This is used to retrieve the form definition.
formIdRequiredStringThe form's ID, which is used to retrieve the form definition.
regionStringThe region of the account where the form was created. This is used to retrieve the form definition. Possible values are na1 or eu1.
targetStringA valid CSS selector string, specifying an existing element on the page into which the form will be embedded.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.
redirectUrlStringThe URL that the form will redirect to upon successful submission. Cannot be used with inlineMessage.
inlineMessageStringThe message to display in place of the form upon successful submission. Cannot be used with redirectUrl.
pageIdNumber or stringThe ID of the HubSpot page that you're embedding the form on. Associates the form submissions with the page.
cssRequiredStringCSS string specific to validation error messages and form styling. Set this property to an empty string if you don't want to apply default HubSpot styling to the form elements.
cssClassStringThe class that will be applied to the form.
cssStringA CSS string that, when defined, is used instead of the built-in CSS theme. This can be used for setting your own CSS styling.
submitTextStringString that overrides the submit button text.
submitButtonClassStringCSS class that will be applied to the submit button instead of the default .hs-button.primary.large.
errorClassStringCSS class that will be applied to the inputs with validation errors instead of the default .invalid.error.
errorMessageClassStringCSS class that will be applied to error messages instead of the default .hs-error-msgs.inputs-list.
localeStringThe form's locale, which is used to customize language for form errors, date pickers, labels, and links. Learn more about adding internationalized error messages.
translationsObjectAn object containing additional translation languages or to override field labels and messages for existing languages. Learn more about adding internationalization.
manuallyBlockedEmailDomainArrayArray of domains, specified as strings, to block in email input fields.
formInstanceIdStringRequired when embedding the same form on the same page multiple times. This ID can be arbitrary, so long as it's unique.

The form embed code includes event callbacks that you can use to extend form functionality when the events below occur. These are separate from the global form events that you can hook into.

ParameterTypeDescription
onBeforeFormInitFunctionA callback that executes before the form builds. Takes form configuration object as a single argument: onBeforeFormInit(ctx).
onFormReadyFunctionA 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).
onFormSubmitFunctionA callback that executes after the form is validated and 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).

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.

onBeforeFormSubmitFunctionA 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.

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.
onFormSubmittedFunctionCallback 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. Takes the jQuery form object as the argument and an array of submission values: onFormSubmitted($form, data).The callback's arguments are the form element and an object containing two properties:
  • redirectUrl: a string containing a redirect URL, if set.
  • submissionValues: an object containing the submitted values from the form.

By default, HubSpot provides a set of translated date picker field labels and validation messages for a set of supported languages. You can also add custom languages or override specific error messages and date picker months/days displayed on the form using the translation parameter.

To include the default translated strings for a supported language, add the locale parameter to the embed code, followed by one of the languages in the table below.

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

To add custom languages or override field labels and default translated strings, you can pass language objects into the translations parameter that correspond to the desired locale.

For supported locales, you only need to provide the keys and messages you wish to override. For example, the code below configures the form to replace the email field label, required field validation message, and submit button text with custom strings.

Learn more about validation below.

ValueTypeLanguage
translationsObjectAn object containing additional translation languages or to override field labels and messages for existing languages.
enObjectAn object containing custom translations for the specified locale.
fieldLabelsObjectAn object containing field label replacement values. In this object, you'll specify the name of the form field followed by your custom label.
requiredStringReplaces the validation message for required field errors with a custom message.
submitTextStringReplaces the submit button text with a custom string.

In addition to the supported locales, you can register new locale codes in 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.

KeyEnglish default
learnMoreLearn more
submitTextSubmit
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.

HubSpot provides three layers of form validation:

  • Live validation: validation that occurs while a visitor is filling out a form.
  • Client-side validation: validation that occurs after the visitor attempts to submit the form, but before the submission request has been sent to the server.
  • Server-side validation: validation that occurs after form submission.

During each step of validation, HubSpot provides a set of default error messages. These messages can be overridden by using the locale and translation parameters in the form embed code. Below, learn more about the default validation error messages and how to override them depending on when they occur.

Below are the currently supported live validation field error keys for contextual overriding. These error keys can be specified in the language object of the translations parameter.

Error keyEnglish default
requiredFieldPlease complete this required field.
requiredPlease complete this required field.
missingSelectPlease complete this required field.
missingOptionSelectionPlease complete this required field.
fileTooLargeSelected file is too large. Maximum allowed size is 100MB.
invalidEmailFormatEmail must be formatted correctly.
phoneInvalidCharactersA valid phone number may only contain numbers and any of the following characters: +, (, ), -, x.
invalidNumberPlease enter a valid number.
invalidDatePlease enter a valid date.
invalidEmailPlease enter a valid email address.
invalidNumberRangeTooSmallPlease enter a number that's greater than or equal to .
invalidNumberRangeTooLargePlease enter a number that's less than or equal to .
forbiddenEmailDomainPlease enter a different email address. This form does not accept addresses from {domain}.
manuallyBlockedEmailDomainPlease enter a different email address. This form does not accept addresses from {domain}.
numberOutOfRangeThe number you entered is not in range.
inputTooLargePlease use fewer than 65536 characters.

The following errors may be generated and displayed client-side. They can be contextually overridden using a submissionErrors object.

Error keyEnglish default
submissionErrors.MISSING_REQUIRED_FIELDSPlease complete all required fields.
submissionErrors.BLOCKED_EMAILPlease change your email address to continue.
submissionErrors.TOO_MANY_REQUESTSThere was an issue submitting your form. Please wait a few seconds and try again.

The following errors may be generated on the server after a submission request has been sent and displayed client-side when a response is received. They can be contextually overridden using a submissionErrors object.

Error keyEnglish default
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.OUT_OF_DATEThis form is no longer current. Please refresh the page and try again.
submissionErrors.FORM_NOT_PUBLISHEDThis form is no longer active. Please refresh the page and try again.
submissionErrors.MISSING_SCOPEThis form cannot be submitted. Please contact the site owner.
submissionErrors.FORM_NEVER_EXISTEDThis form cannot be submitted. Please contact the site owner.
submissionErrors.FORM_TYPE_MISMATCHThis form cannot be submitted. Please contact the site owner.
submissionErrors.FILE_TOO_LARGESelected file is too large. Maximum allowed size is 100MB.

Forms allow two ways to bind functionality onto events, including callbacks in the HubSpot form embed code and global form events.

Use these events to trigger custom JavaScript. If you need complete control over the styles and actions of your form, it's recommended that you build your own custom form and submit the data using the Forms API.

Called before the form has been inserted into DOM.

Called after the form has been inserted into DOM.

Called at the start of form submission, but before submission has been persisted. Behaves the same as onFormSubmit, but is preferred due to more accurate naming indicating when this event is triggered.

When performing custom redirects, use onFormSubmitted instead, as this event may prevent submissions being initiated, thus preventing form submissions.

Called at the start of form submission, but before submission has been persisted. Please use onBeforeFormSubmit instead.

When performing custom redirects, use onFormSubmitted instead, as this event may prevent submissions being initiated, thus preventing form submissions.

Called after the form has been submitted and the submission has persisted. Recommended for performing custom redirects.