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. The <Form> component wires it up internally whenever your config has submitActions. Use it when building custom trigger logic on top of your own form.

Signature

import { useSubmitActionTriggers } from '@saastro/forms';

const { triggerFieldChange, triggerFieldBlur, triggerManual, hasActionsForTrigger } =
  useSubmitActionTriggers({
    config,
    getValues,
    currentStep,
    onActionExecuted,
    onActionError,
    enabled,
  });

Parameters

getValues is a function reference, not a values object. Pass methods.getValues directly — do not call it (methods.getValues()). The hook reads values lazily at fire time, so triggers always see the latest data without subscribing to every keystroke.

Return Value

Trigger Types

onSubmit actions are not handled by this hook — they run inside the submit pipeline when the form is submitted. hasActionsForTrigger('onSubmit') still reports them.

Example: Manual Trigger

import { useFormState, useSubmitActionTriggers } from '@saastro/forms';
import type { FormConfig } from '@saastro/forms';

function SaveDraftButton({ config }: { config: FormConfig }) {
  const { methods, currentStepId } = useFormState({ config, fields: config.fields });

  const { triggerManual, hasActionsForTrigger } = useSubmitActionTriggers({
    config,
    getValues: methods.getValues, // pass the function, don't call it
    currentStep: currentStepId,
  });

  const saveDraft = async () => {
    // Check if there are manual actions available
    if (hasActionsForTrigger('manual')) {
      const result = await triggerManual(['save-draft']);
      console.log('Draft saved:', result.allSuccessful);
    }
  };

  return <button onClick={saveDraft}>Save draft</button>;
}

Notes

• triggerManual ignores enabled — it executes even when enabled is false. The automatic effects and triggerFieldChange/triggerFieldBlur do respect it.
• triggerFieldChange ignores its value argument; values are read via getValues() when the debounced action actually fires.
• The hook’s option and return interfaces are not exported types — only the function itself is public.
• All debounce and idle timers are cleared on unmount.

Related

• Submit & Actions — Configuring submit actions with different triggers