JavaScript Events

Throughout the lifecycle of our scripts on the storefront, we emit a variety events that you might find useful.

Form events

You can attach event listeners to the document, or a <form> element (unless noted otherwise.) Adding event listeners to the <form> element can be helpful when you have multiple forms on the same page.

Targeting a form

For example, say we have a form with an ID of ak23jN, we can find the form element on the page and attach event listeners to it:

var formId = 'ak23jN';
var $form = document.querySelector('form[data-cf-form="' + formId + '"]');

$form.addEventListener('cf:field_changed', function(event) {
  // ...
});

$form.addEventListener('cf:step_changed', function(event) {
  // ...
});

Note

Later examples will reference the $form variable described above, when applicable.

`cf:ready`

Any CF form(s) have been rendered. Attempts to access a <form> element’s cfForm property will result in an error until this event is emitted.

Usage:

var $form = document.querySelector('form[data-cf-form="ak23jN"]');
$form.cfForm.setFieldValue('favorite_color', 'Magenta');
// -> Error: Cannot read property 'setFieldValue' of undefined

document.addEventListener('cf:ready', function() {
  // Forms are mounted on the page!
  $form.cfForm.setFieldValue('favorite_color', 'Magenta'); // Works!
});

// Alternatively, we provide a short-hand function for this:
CF.ready(function() {
  // Forms are mounted on the page!
  $form.cfForm.setFieldValue('favorite_color', 'Magenta'); // Works!
});

Note

Listeners for this event cannot be attached to a <form> element.

`cf:field_changed`

A field inside a CF form has been changed by user input, or by calling cfForm.setFieldValue.

Example usage:

$form.addEventListener('cf:field_changed', function(event) {
  var fieldId = event.detail.fieldId;
  var columnKey = event.detail.columnKey;
  var value = event.detail.value;

  console.log(formId, columnKey, value, event.target);
  // -> 897424, "favorite_color", "Blue", <div class="cf-field" data-cf-field-id="897424">
});

Note

Be cautious when storing a reference to a .cf-field element, as it may get removed when the step changes, due to the nature of React.

`cf:field_validated`

A field’s validations have been processed. Any errors won’t display until the user has defocused the field for the first time.

Example usage:

$form.addEventListener('cf:field_validated', function(event) {
  var fieldId = event.detail.fieldId;
  var columnKey = event.detail.columnKey;
  var errors = event.detail.errors;

  console.log(formId, columnKey, errors, event.target);
  // -> 123456, "email", ["Please enter a valid email address"], <div class="cf-field" data-cf-field-id="123456">
});

The errors array contains error messages from validations configured in the app.

`cf:rule_actions_determined`

A field has changed, causing the form to handle any actions generated by rules with passing conditions.

Example usage:

$form.addEventListener('cf:rule_actions_determined', function(event) {
  var formId = event.detail.formId;
  var actions = event.detail.actions;

  console.log(formId, actions, event.target);
  /*
    "n89j3k",
    [
      {
        effect: 'hide_field',
        metadata: {
          fieldId: 123456,
        },
      },
      {
        effect: 'set_column_value',
        metadata: {
          columnKey: 'favorite_color',
          columnType: 'text',
          value: 'Blue'
        }
      }
    ],
    <form data-cf-form="n89j3k">
  */
});

`cf:step_changed`

Step navigation has been caused by user input, or by calling cfForm.goToStep, cfForm.goToNextStep, or cfForm.goToPreviousStep.

Example usage:

$form.addEventListener('cf:step_changed', function(event) {
  var formId = event.detail.formId;
  var fromIndex = event.detail.fromIndex;
  var toIndex = event.detail.toIndex;

  console.log(formId, fromIndex, toIndex, event.target);
  // -> "a39Jk2", 0, 1, <form data-cf-form="n89j3k">
});

Step indexes begin at zero. For example, if the user navigates from step 1 to step 2, fromIndex will be 0 and toIndex will be 1.

`cf:form_submitted`

A form has been submitted successfully.

Example usage:

$form.addEventListener('cf:form_submitted', function(event) {
  var formId = event.detail.formId;
  var submissionData = event.detail.submissionData;

  console.log(formId, submissionData, event.target);
  // -> "a39Jk2", { first_name: 'John', last_name: 'Smith', ... }, <form data-cf-form="n89j3k">
});

`cf:form_submission_failed`

Our servers returned error(s) upon a form’s submission.

Example usage:

$form.addEventListener('cf:form_submission_failed', function(event) {
  var formId = event.detail.formId;
  var errors = event.detail.errors;

  console.log(formId, errors, event.target);
  /* ->
    "a39Jk2",
    {
      email: ['is invalid']
    },
    <form data-cf-form="n89j3k">
  */
});

Read more about the errors object on our page about handling server errors. The errorObj described there is the same as the errors variable above.

Customer events

Various interactions with CF.customer can cause the following events to be emitted.

`cf:customer_ready`

CF.customer is ready for use. Attempts to use CF.customer will result in thrown errors until this event is emitted.

Example usage:

CF.customer.set('favorite_color', 'Blue');
// -> Error: cannot read property 'set' of undefined

document.addEventListener('cf:customer_ready', function() {
  CF.customer.set('favorite_color', 'Blue'); // OK!
});

// Or, use this short-hand function that is always available:
CF.customerReady(function() {
  CF.customer.set('favorite_color', 'Blue'); // OK!
});

`cf:customer_changed`

The data inside CF.customer has been changed by calling CF.customer.set.

Example usage:

document.addEventListener('cf:customer_changed', function(event) {
  var changed = event.detail.changed;

  console.log(changed, changed.favorite_color);
  // -> { favorite_color: "Blue" }, "Blue"
});

`cf:customer_tags_changed`

The customer’s tags have been changed (not yet saved,) by calling CF.customer.addTag or CF.customer.removeTag.

Example usage:

document.addEventListener('cf:customer_tags_changed', function(event) {
  var tags = event.detail.tags;

  console.log(tags);
  // -> ["new", "and", "existing", "tags"]
});

Note

This event will be emitted by a form if a rule has added or removed a tag.

`cf:customer_saved`

CF.customer.save has been called, and the data has been successfully saved.

Example usage:

document.addEventListener('cf:customer_saved', function(event) {
  // Show success modal, etc.
});

Note

This event will be emitted by a form when it has been submitted without guest submission behavior.

`cf:guest_data_saved`

CF.customer.saveAsGuest has been called and the data has been successfully stored in the browser’s localStorage.

Example usage:

document.addEventListener('cf:guest_data_saved', function(event) {
  // Show success modal, etc.
});

`cf:customer_save_failed`

CF.customer.save has been called, and our servers have returned errors. Learn more about how to handle errors from our servers.

Example usage:

document.addEventListener('cf:customer_save_failed', function(event) {
  var errors = event.detail.errors;

  console.log(errors);
  // -> { email: ['is invalid'], ... }
  // Inform the user on how to fix the errors, etc.
});