- Docs
- Submit on change with autoSubmit()
Submit on change with autoSubmit()
Enables native auto-submit. Every change to a tracked field triggers form.requestSubmit(). Optionally debounced.
Enables native auto-submit. Every change to a tracked field triggers form.requestSubmit(). Optionally debounced.
Signature
autoSubmit(options?: boolean | AutoSubmitOptions): FormController
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
options |
boolean | AutoSubmitOptions |
no | true |
Pass true to enable, false to disable, or an { debounce } object to delay. |
interface AutoSubmitOptions {
debounce?: number
}
Returns
The same FormController — chainable.
Behaviour
autoSubmit()orautoSubmit(true)— enables auto-submit immediately on every change.autoSubmit({ debounce: ms })— schedulesform.requestSubmit()msmilliseconds after the most recent change. Subsequent changes within the debounce window reset the timer.autoSubmit(false)— disables auto-submit (equivalent todisableAutoSubmit()).
When auto-submit fires, the native submit is invoked. If the form is invalid, the controller’s submit listener prevents the browser from navigating and leaves focus where the visitor is typing. If the form is valid, the registered onSubmit handlers run as usual.
Subscribers are notified when autoSubmit is enabled, disabled, or its debounce changes (because the state’s autoSubmit field changes).
Examples
Autosave on every change
import { form } from '@samline/forms'
const draft = form('draft-form', {
validators: { title: { required: true } },
})
draft.autoSubmit()
Debounced search
import { form } from '@samline/forms'
const search = form('search-form', {
autoSubmit: { debounce: 300 },
})
search.onSubmit(async (_form, data) => {
await fetch('/search', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
})
})
Toggle at runtime
const formEl = form('search-form')
document.querySelector('#realtime')?.addEventListener('change', event => {
const enabled = (event.target as HTMLInputElement).checked
formEl.autoSubmit(enabled ? { debounce: 250 } : false)
})
Edge cases
- The submit is invoked via
form.requestSubmit()when available, falling back to clicking a submit button orform.submit()otherwise. autoSubmitdoes not validate. Validation runs as part of the submit pipeline, so an invalid form will not navigate and youronSubmithandler will not run.- The debounce timer is cancelled by
disableAutoSubmit()anddestroy(). - Setting
autoSubmitfromoptionsand from the method can both run at mount time — the method is called last, so it wins.
Related
disableAutoSubmit— turn auto-submit off.onSubmit— submit handlers.options.autoSubmit— mount-time configuration.