How to customize the form embed code

This is a list of options that you can use if you just need 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.

Please Note If you are 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
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.
css O, I CSS string that will replace the default HubSpot CSS. Empty string == no style. As an alternative, after disabling the default CSS, you can style the form in your stylesheet
cssRequired O, I CSS string specific to validation error messages. Empty string == no style
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.
blockedDomains 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 and configuration object as arguments: onFormReady($form, ctx)
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: onFormSubmit($form)


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

Now by default, HubSpot provides a number of custom validation messages in many different languages. 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 also override field labels by specifying the label as {locale: {fieldLabels: {fieldName: customLabel}}}. 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
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.
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
phoneInvalidLengthOrFormatMust be a valid phone number
emailSuggestionDid you mean ?
previousMonthPrevious Month
nextMonthNext Month