How to customize the form embed code

Last updated July 27, 2021

Note: These options are only available for forms created using the marketing form builder available with a paid Basic, Professional, or Enterprise marketing subscription. Other forms, such as collected forms or lead flows, do not support these customization options.

This is a list of options you can use to tweak a default HubSpot form. If you need complete control over the styles and actions of your form, you will still want to use the Forms API. For more on how to generate an embed code on a form, view the documentation. For information on how to use the form that this embed code generates, please see this article.

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();

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, provide this Id for each identical form embed. The Id value 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)
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
blockedEmailPlease change your email address to continue.
requiredPlease complete this mandatory field.
invalidEmailPlease enter a valid email address.
invalidEmailFormatEmail must be formatted correctly
invalidNumberPlease enter a valid number.
missingOptionSelectionPlease select at least one option.
missingSelectPlease select an option from the dropdown.
missingRequiredFieldsPlease complete all required fields.
forbiddenEmailDomainPlease enter your business email address. This form does not accept addresses from .
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 YYYY-MM-DD format.
phoneInvalidCharactersMust contain only numbers, +()-. and x
phoneInvalidRangeTooShortPlease enter a phone number that's at least { min } numbers long.
phoneInvalidRangeTooLongPlease enter a phone number that's at most { max } numbers long
emailSuggestionDid you mean ?
previousMonthPrevious Month
nextMonthNext Month