Please note: the functionality described in this article only pertains to forms created through the updated forms editor in HubSpot’s UI. If you need to work with global form events for a legacy form, check out this article instead.
Form events
Throughout their lifecycle, HubSpot forms will emit various events based form readiness and user interactions. These events are defined in the table below. You can define listeners for each event by using thewindow.addEventListener(EVENT_NAME)
function.
Event name | Description |
---|---|
hs-form-event:on-ready | The form has finished loading and has been fully rendered. |
hs-form-event:on-submission:success | The form has been submitted successfully. |
hs-form-event:on-submission:failed | The form submission failed. |
hs-form-event:on-interaction:navigate | On a multi-step form, the user has navigated to either the previous step or next step in the form. |
hs-form-event:on-interaction:navigate:next | On a multi-step form, in addition to the generic hs-form-event:on-interaction:navigate event, this event is also fired to indicate the user navigated to the next step in the form. |
hs-form-event:on-interaction:navigate:previous | On a multi-step form, in addition to the generic hs-form-event:on-interaction:navigate event, this event is also fired to indicate the user navigated to the previous step in the form. |
Event object
All global form events are emitted with an event object that’s passed to the event handler. This event object includes two nested IDs, theformId
and the instanceId
, within the details
field, which allows you to reference the ID of the form and the specific instance of that form on your page.
getFormFromEvent
method accessible from the HubSpotFormsV4
object, which is available on any page where your form is present. This method returns a form instance that can be used to retrieve or populate data in the from.
Please note: you should define any
hs-form-event:on-ready
listeners on your page before the form embed code is executed. This will ensure that your listeners are set up to listen for the event before it’s emitted and avoid race conditions.Getting form instances
HubSpot provides instance API methods within thewindow.HubSpotFormsV4
object. The available methods are detailed in the sections below.
getForms
To retrieve all form instances on a page, call thegetForms
method. The method will return an array of form
instances.
getFormFromEvent
To get a specific form instance using an emitted form event, call thegetFormFromEvent
method, using the emitted event
object as an argument. The method will return a specific form
instance object.
Please note: the
form
instance object includes several fields intended for internal use only, such as __SECRET_INTERNAL_DO_NOT_USE
. Avoid usage of these fields as they are unstable, and are not designed for public usage. Usage of these fields could break your integration.Form instance methods
Form instance methods are useful for retrieving and passing data to and from your form. Although these methods can be called at any point in the form’s lifecycle, some form data fields can only be retrieved or set before the form is submitted, while others can only be accessed after form submission.getFormId
Use thegetFormId
method to retrieve the ID of your form. The method will return the ID as a string.
getInstanceId
Use thegetInstanceId
method to retrieve the ID of the form instance. The method will return the ID as a string.
getFieldValue
Use theasync
getFieldValue
method to retrieve the value of a field in your form. The method accepts the field’s name
as a string argument, and returns either a string value or an array of string values for multi-checkbox fields. You can also use this method to retrieve the value of a conditionally hidden field.
getFormFieldValues
Use theasync
getFormFieldValues
method to retrieve the values of all the fields in your form. This method returns an array of key-value pair objects that contain the field name as a string and the value as either a string or an array of strings for multi-checkbox fields. You can also use this method to retrieve the value of a conditionally hidden field.
Please note: the value of a file field will not be returned if you attempt to get the value using either the
getFieldValue
or getFormFieldValues
methods.getConversionId
Use thegetConversionId
method to retrieve the ID of a form conversion. The method will return a valid string value when called after the form is successfully submitted.
getRedirectUrl
For forms set up to redirect to a specific URL after submission, you can use thegetRedirectUrl
method to retrieve the redirect URL. This method returns the URL as a string after successful form submission.
setExtraSubmissionMetadata
Use thesetExtraSubmissionMetadata
method to pass additional metadata to the form submission. The method accepts an object with a set of key-value pairs, which will be sent as part of the form submission.
setFieldValue
You can use thesetFieldValue
method to programmatically update the value of a field on the form. Provide the field’s name
as the first string argument, then the field’s value
as the second argument.
Please note: setting the value of a file field is not supported.
Field type | Data type |
---|---|
Single-line text | string |
Number | string, number |
Single checkbox | boolean |
Multiple checkboxes | string[] |
Dropdown | string |
Phone number | string, number |
Date | string, number (provided as a UNIX timestamp in milliseconds) |
Multi-line text | string |
Radio | string |
Hidden | string[] |