Reference

Follow form state with subscribe()

Registers a listener that fires immediately with the current state and at controller notification points. Returns an unsubscribe function.

Registers a listener that fires immediately with the current state and at controller notification points. Returns an unsubscribe function.

Signature

subscribe(listener: FormStateListener): () => void

Parameters

Name Type Required Description
listener FormStateListener yes Callback invoked with the full state snapshot.

Returns

A function. Calling it removes the listener.

Behaviour

  • The listener fires once synchronously on registration with the current FormStateSnapshot.
  • It then fires at explicit controller notification points. This is not a proxy around every internal assignment.
  • Multiple subscribers are supported. They run in registration order.

State mutations that fire subscribers include:

  • Any input event on a tracked field.
  • setValue.
  • setErrors and clearErrors.
  • autoSubmit and disableAutoSubmit.
  • reset.
  • Submit attempts, after their validation pass and submitCount update.
  • Async submit state transitions: once when promise-returning handlers make isSubmitting true, and again after their submission batch settles. Overlapping batches keep it true until all settle.
  • MutationObserver-detected DOM changes.

Direct validate and revalidate calls update validation state and visual attributes but do not independently notify subscribers. Use their returned result when synchronous rendering is required.

Examples

Mirror state into a view layer

import { form } from '@samline/forms'

const profile = form('profile-form')

const unsubscribe = profile.subscribe(state => {
  document.querySelector('#status')!.textContent = state.isValid ? 'Ready' : 'Errors'
  document.querySelector('#counter')!.textContent = String(state.submitCount)
})

window.addEventListener('beforeunload', unsubscribe)

React to a specific field

const signup = form('signup-form')

signup.subscribe(state => {
  const password = state.values.password
  const passwordError = state.errors.password?.[0]
  document.querySelector('#password-hint')!.textContent =
    passwordError ?? (typeof password === 'string' && password.length > 0 ? 'OK' : 'Empty')
})

Track submit attempts

const profile = form('profile-form')

profile.subscribe(state => {
  if (state.submitCount > 0 && !state.isValid) {
    console.warn('submit attempt failed:', state.submitCount)
  }
})

Track asynchronous submission

const profile = form('profile-form')

profile.subscribe(state => {
  submitButton.disabled = state.isSubmitting
  submitButton.textContent = state.isSubmitting ? 'Saving...' : 'Save'
})

profile.onSubmit(async (_form, _data, formData) => {
  await fetch('/profile', { method: 'POST', body: formData })
})

Edge cases

  • The listener is invoked with a fresh snapshot on every fire — it is safe to store the reference for the duration of one call.
  • Subscribers do not receive partial / incremental updates. Each fire carries the whole snapshot.
  • Subscribers and watchers are independent. A field-level change fires both the watchers for that field and every subscriber.
  • Unsubscribing does not detach the listener immediately if it is currently iterating. JavaScript’s Set semantics guarantee no skips — once the unsubscribe returns, future mutations will not invoke that listener.