- Docs
- Follow form state with subscribe()
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
inputevent on a tracked field. setValue.setErrorsandclearErrors.autoSubmitanddisableAutoSubmit.reset.- Submit attempts, after their validation pass and
submitCountupdate. - Async submit state transitions: once when promise-returning handlers make
isSubmittingtrue, 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
Setsemantics guarantee no skips — once the unsubscribe returns, future mutations will not invoke that listener.