There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. Your API Keys could be deactivated at any time after Nov. 30th, and we recommend that you migrate to Private Apps as soon as possible so you do not lose business-critical functionality.

How to customize the form embed code

Last updated December 7, 2022

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 marketing form builder in Marketing Hub and CMS Hub Professional or Enterprise subscriptions.
  • 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 need complete control over the styles and actions of your form, you can use the Forms API. For more on how to generate an embed code on a form, check out HubSpot's Knowledge Base. For information on how to use the form that this embed code generates, please see the developer documentation.

Please Note 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.

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

For Checkboxes:

Configuration options

Type legend:

  • R - (required) This attribute must be provided for the embed code to work properly.
  • I - (internal) Used internally by a HubSpot tool. Use with caution, as it will likely affect how this form behaves or how the submission data is processed.
  • O - (optional) Optional form customization attribute intended for use by end-users.
  • C - (callback) A callback function that will be executed at various points in the form's lifecycle.

Attribute Types Description
portalId R, I User's portal ID
formId R, I Unique ID of the form you wish to build
target O jQuery style selector specifying an existing element on the page into which the form will be placed once built. NOTE: If you're including multiple forms on the page, it is strongly recommended that you include a separate, specific target for each form.
redirectUrl O, I URL to which the form will redirect upon a successful form completion. Cannot be used with inlineMessage.
inlineMessage O, I Inline message to display in place of the form upon a successful form completion. Cannot be used with redirectUrl.
pageId O, I ID of the landing page on which the form exists. This must be the content ID of a landing page built in HubSpot.
cssRequired O, I CSS string specific to validation error messages and form styling. Empty string == no style. Note: when setting/declaring this field in the embed code, elements of your form will no longer have default HubSpot styling applied.
cssClass O CSS class that will be applied to the form.
submitButtonClass O, I CSS class that will be applied to the submit input instead of the default .hs-button.primary.large.
errorClass O, I CSS class that will be applied to inputs with validation errors instead of the default .invalid.error.
errorMessageClass O, I CSS class that will be applied to error messages instead of the default .hs-error-msgs.inputs-list.
groupErrors O Show all errors at once inside a single container. Defaults to true, otherwise only shows the first error for each field.
locale O Locale for the form, used to customize language for form errors and the date picker. See Add internationalized error messages below.
translations O An object containing additional translation languages or to override field labels or messages for existing languages. See Customize internationalization below.
manuallyBlockedEmailDomain O, I Array of domains to block in email inputs.
formInstanceId O, I When embedding the same form on the same page twice, populate this Id for each identical form embed. The Id value is must be in string format, using a number instead of a string can result in issues when submitting the form. The Id value used is arbitrary, so long as it is not the same between forms.
onBeforeFormInit O, C Callback that executes before the form builds, takes form configuration object as single argument: onBeforeFormInit(ctx)
onFormReady O, C Callback that executes after form is built, placed in the DOM, and validation has been initialized. This is perfect for any logic that needs to execute when the form is on the page. Takes the jQuery form object as the argument: onFormReady($form)
onFormSubmit O, C Callback that executes after form is validated, just before the data is actually sent. This is for any logic that needs to execute during the submit. Any changes will not be validated. Takes the jQuery form object as the argument: onFormSubmit($form). Note: Performing a browser redirect in this callback is not recommended and could prevent the form submission
onFormSubmitted O, C Callback the data is actually sent.This allows you to perform an action when the submission is fully complete, such as displaying a confirmation or thank you message.


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
esSpanish (Spain)
es-mxSpanish (Mexico)
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
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
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.