useSubmitActionTriggers
Fires submit actions automatically on field change, field blur, step transitions, and idle timeout.
useSubmitActionTriggers
Manages automatic execution of submit actions based on non-submit triggers like field changes, blur events, step transitions, and idle timeouts. This is what powers real-time features like auto-saving on field change or sending analytics on step exit.
You probably don’t need this directly. useFormState handles it internally when your config has actions with non-onSubmit triggers. Use it when building custom trigger logic.
Signature
import { useSubmitActionTriggers } from '@saastro/forms';
const { triggerFieldChange, triggerFieldBlur, triggerManual, hasActionsForTrigger } =
useSubmitActionTriggers({
config,
values,
currentStep,
onActionExecuted,
onActionError,
enabled,
});
Parameters
| Parameter | Type | Required | Description |
|---|
config | FormConfig | Yes | Form configuration with submit actions |
values | Record<string, unknown> | Yes | Current form values |
currentStep | string | Yes | Active step ID |
onActionExecuted | (result) => void | No | Called after an action completes |
onActionError | (error, actionName) => void | No | Called when an action fails |
enabled | boolean | No | Enable/disable all triggers (default: true) |
Return Value
| Property | Type | Description |
|---|
triggerFieldChange | (fieldName, value) => void | Trigger onFieldChange actions (debounced) |
triggerFieldBlur | (fieldName) => void | Trigger onFieldBlur actions (immediate) |
triggerManual | (actionIds?) => Promise<SubmitActionsResult> | Manually trigger specific actions |
hasActionsForTrigger | (triggerType, triggerValue?) => boolean | Check if any actions exist for a trigger type |
Trigger Types
| Trigger | When It Fires | Behavior |
|---|
onFieldChange | User changes a field value | Debounced (default 300ms per field) |
onFieldBlur | User leaves a field | Immediate |
onStepEnter | User navigates to a step | Automatic (via step change detection) |
onStepExit | User leaves a step | Automatic (via step change detection) |
onDelay | User is idle for N milliseconds | Automatic (listens to mousedown, keydown, touchstart, scroll) |
manual | Programmatic trigger | Via triggerManual() call |
Example: Manual Trigger
const { triggerManual, hasActionsForTrigger } = useSubmitActionTriggers({
config,
values: methods.getValues(),
currentStep: currentStepId,
});
// Check if there are manual actions available
if (hasActionsForTrigger('manual')) {
const result = await triggerManual(['save-draft']);
console.log('Draft saved:', result.allSuccessful);
}