DocsSign inCreate an account
Developer guide

JavaScript: Events

Events let your application observe field changes, resets, validation results, and configured email delivery. This page shows the API and examples for JavaScript.

EventJavaScript bindingPayloadWhen
item:updatedform.on('item:updated'){ id: string, value: FieldValue }Emitted when the JavaScript model updates one field.
resetform.on('reset')voidEmitted after the renderer clears the form model values.
submitform.on('submit')SubmitDataEmitted after validation for every submit attempt, including an 'invalid' attempt.
mail-sendform.on('mail-send'){ success: boolean }Emitted after email delivery for a valid form finishes, when email delivery is configured.

Payload types

TypeScript projects can import these definitions from @jcees-forms/types/interfaces/data. Add @jcees-forms/types as a direct development dependency when your package manager does not expose transitive dependencies. 

npm install --save-dev @jcees-forms/types
type FieldValue =
  | string
  | number
  | string[]
  | number[]
  | Record<string, boolean>

interface UserData {
  id: string
  label: string
  value: FieldValue
  visible: boolean
  invalid: boolean
  errors: string[]
}

interface SubmitData {
  status: 'valid' | 'invalid'
  items: UserData[]
}

item:updated: one field value

The JavaScript renderer exposes a lower-level update payload. It contains the field ID and value, but not the label or validation state included in Vue and React's UserData payload. 

{ id: 'email', value: 'person@example.com' }

submit: validation status and all fields

The submit callback runs for every attempt. Always inspect status before sending data to your own API. The items array contains every field; use each item's visible flag if hidden fields should be excluded by your application. 

{
  status: 'valid',
  items: [
    {
      id: 'field-id',
      label: 'Email address',
      value: 'person@example.com',
      visible: true,
      invalid: false,
      errors: []
    }
  ]
}
{
  status: 'invalid',
  items: [{
    id: 'email',
    label: 'Email address',
    value: '',
    visible: true,
    invalid: true,
    errors: ['Email address is required']
  }]
}

reset: no payload

The callback is invoked without arguments after the renderer clears its model values. Use it to clear related application state or analytics.

mail-send: delivery result

This event only follows a valid submission when the published form has email delivery configured. It is not emitted for an invalid submission or a form without email settings. 

{ success: true }
// or
{ success: false }

In the current renderers, success: false means the email workflow threw an exception. success: true means that workflow completed; provider-level failures returned without an exception may still be logged separately.

Submit and email are separate

submit reports form validation immediately. mail-send reports the later email step. A valid submit therefore does not by itself confirm email delivery.

JavaScript usage

Subscribe with form.on(). Field updates use the lower-level item:updated event with { id, value }. 

import { JCeesForm } from '@jcees-forms/javascript'

const form = new JCeesForm({
  spaceId: 'your-space-id',
  formId: 'your-form-id',
  language: 'en'
})

form.on('item:updated', ({ id, value }) => console.log(id, value))
form.on('reset', () => console.log('reset'))
form.on('submit', (result) => console.log('submitted', result))
form.on('mail-send', ({ success }) => console.log('mail sent', success))

Every JavaScript event is also dispatched on window as jcees:<event>. The payload is available in CustomEvent.detail. 

window.addEventListener('jcees:submit', (event) => {
  const result = event.detail
  console.log(result.status, result.items)
})