JavaScript events

Every Tally widget emits the same set of events. The transport changes depending on the integration method:

Embeds and popups send events as postMessage payloads. Listen for them on the message event on window.
Code injection (running inside the form via your custom domain) receives them as CustomEvents dispatched directly on window.

Add your event listeners to the page hosting the embed or popup — not to the form itself. For code injection, add them to the form via your custom domain settings.

Tally.FormLoaded

Fires when the form is rendered. Because embeds and popups are lazy-loaded, you receive this event each time the form is actually shown.

interface LoadedPayload {
  formId: string;
}

window.addEventListener('message', (e) => {
  if (e?.data?.includes('Tally.FormLoaded')) {
    const payload = JSON.parse(e.data).payload as LoadedPayload;
    // ...
  }
});

Tally.FormPageView

Fires every time the respondent navigates to a page of the form — handy for multi-page forms.

interface PageViewPayload {
  formId: string;
  page: number;
}

// For embeds and popups
window.addEventListener('message', (e) => {
  if (e?.data?.includes('Tally.FormPageView')) {
    const payload = JSON.parse(e.data).payload as PageViewPayload;
    // ...
  }
});

// For code injection via a custom domain
window.addEventListener('Tally.FormPageView', (e) => {
  const payload = e.detail as PageViewPayload;
  // ...
});

Tally.FormSubmitted

Fires when the form is submitted. The payload contains the submission metadata and the full set of answers.

interface SubmissionPayload {
  id: string; // submission ID
  respondentId: string;
  formId: string;
  formName: string;
  createdAt: Date; // submission date
  locale?: string; // language code the form was shown in, e.g. 'nl', 'pt-BR' or 'zh-CN'; only on a form with translations
  fields: Array<{
    id: string;
    title: string;
    type:
      | 'INPUT_TEXT'
      | 'INPUT_NUMBER'
      | 'INPUT_EMAIL'
      | 'INPUT_PHONE_NUMBER'
      | 'INPUT_LINK'
      | 'INPUT_DATE'
      | 'INPUT_TIME'
      | 'TEXTAREA'
      | 'MULTIPLE_CHOICE'
      | 'DROPDOWN'
      | 'CHECKBOXES'
      | 'LINEAR_SCALE'
      | 'FILE_UPLOAD'
      | 'HIDDEN_FIELDS'
      | 'CALCULATED_FIELDS'
      | 'RATING'
      | 'MULTI_SELECT'
      | 'MATRIX'
      | 'RANKING'
      | 'SIGNATURE'
      | 'PAYMENT';
    answer: { value: any; raw: any };
  }>;
}

// For embeds and popups
window.addEventListener('message', (e) => {
  if (e?.data?.includes('Tally.FormSubmitted')) {
    const payload = JSON.parse(e.data).payload as SubmissionPayload;
    // ...
  }
});

// For code injection via a custom domain
window.addEventListener('Tally.FormSubmitted', (e) => {
  const payload = e.detail as SubmissionPayload;
  // ...
});

Tally.PopupClosed

Fires only for popups, when the popup is closed.

interface PopupClosedPayload {
  formId: string;
}

window.addEventListener('message', (e) => {
  if (e?.data?.includes('Tally.PopupClosed')) {
    const payload = JSON.parse(e.data).payload as PopupClosedPayload;
    // ...
  }
});

Popups also accept lifecycle callbacks (onOpen, onClose, onPageView, onSubmit) directly on the Tally.openPopup() options argument. See Popups for the full reference.

Getting started

Integration methods

Events

Examples

Tally.FormLoaded

Tally.FormPageView

Tally.FormSubmitted

Tally.PopupClosed

​Tally.FormLoaded

​Tally.FormPageView

​Tally.FormSubmitted

​Tally.PopupClosed

Tally.FormLoaded

Tally.FormPageView

Tally.FormSubmitted

Tally.PopupClosed