There's a new version of the HubSpot API
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.
Examples:
$('input[value="checkbox_1"]').prop('checked', true).change();
$('input[name="firstname"]').val('Brian').change();
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. 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 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. |
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.
HubSpot provides a number of custom validation messages in many different languages by default. View the example in the right code pane.
Key | Language |
---|---|
en | English |
da | Danish |
de | German |
es | Spanish (Spain) |
es-mx | Spanish (Mexico) |
fi | Finnish |
fr | French |
it | Italian |
ja | Japanese |
nl | Dutch |
pl | Polish |
pt-br | Portuguese |
sv | Swedish |
zh-cn | Chinese |
zh-hk | Chinese (Hong Kong) |
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 |
---|---|
blockedEmail | Please change your email address to continue. |
submitText | Submit |
required | Please complete this mandatory field. |
invalidEmail | Please enter a valid email address. |
invalidEmailFormat | Email must be formatted correctly |
invalidNumber | Please enter a valid number. |
missingOptionSelection | Please select at least one option. |
missingSelect | Please select an option from the dropdown. |
missingRequiredFields | Please complete all required fields. |
forbiddenEmailDomain | Please enter your business email address. This form does not accept addresses from . |
emailOptIn | Please check your email to opt back in. |
resubscribeMessage | Looks like you've opted out of email communication. Click here to get an email and opt back in. |
invalidDate | Please use the datepicker to match the YYYY-MM-DD format. |
phoneInvalidCharacters | Must contain only numbers, +()-. and x |
phoneInvalidRangeTooShort | Please enter a phone number that's at least { min } numbers long. |
phoneInvalidRangeTooLong | Please enter a phone number that's at most { max } numbers long |
emailSuggestion | Did you mean ? |
previousMonth | Previous Month |
nextMonth | Next Month |
january | January |
february | February |
march | March |
april | April |
may | May |
june | June |
july | July |
august | August |
september | September |
october | October |
november | November |
december | December |
sunday | Sunday |
monday | Monday |
tuesday | Tuesday |
wednesday | Wednesday |
thursday | Thursday |
friday | Friday |
saturday | Saturday |
sundayShort | Sun |
mondayShort | Mon |
tuesdayShort | Tue |
wednesdayShort | Wed |
thursdayShort | Thu |
fridayShort | Fri |
saturdayShort | Sat |