S

useSubmitConfirmation

Double-click confirmation pattern for forms with empty optional fields.

useSubmitConfirmation

Implements a double-click confirmation pattern: when a user tries to submit with empty optional fields, the button transforms into a warning state. A second click confirms the submission.

You probably don’t need this directly. The <Form /> component handles it automatically when submitConfirmation is configured. Use it when building custom submit button behavior.

Signature

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

const {
  needsConfirmation,
  isAwaitingConfirmation,
  warningFields,
  buttonProps,
  handleClick,
  resetConfirmation,
} = useSubmitConfirmation({ config, currentValues, onProceed, buttonType });

Parameters

ParameterTypeRequiredDescription
configFormConfigYesForm config with submitConfirmation
currentValuesRecord<string, unknown>YesLive form values (from methods.watch())
onProceed() => voidYesCallback when the action is confirmed
buttonType'submit' | 'next'NoWhich button this applies to (default: 'submit')

Return Value

PropertyTypeDescription
needsConfirmationbooleanWhether any optional fields are empty
isAwaitingConfirmationbooleanWhether the button is in warning state (waiting for second click)
warningFieldsstring[]Names of the empty optional fields
buttonProps{ text?, variant?, effect? }Override props for the button during warning state
handleClick(e: MouseEvent) => voidClick handler (first click = warn, second click = proceed)
resetConfirmation() => voidManually reset the confirmation state

How It Works

  1. User clicks the submit/next button with empty optional fields
  2. First click: Button transforms to warning state (text changes, variant changes). A timer starts (default 3 seconds)
  3. Second click: Confirmation accepted, onProceed() fires
  4. If the timer expires without a second click, the button reverts to normal

Configuration

.submitConfirmation({
  optionalFields: [
    { name: 'phone', message: 'Without a phone number we cannot call you back' },
    { name: 'company', message: 'Adding your company helps us prioritize' },
  ],
  buttonBehavior: {
    warningText: 'Continue without filling?',
    warningVariant: 'outline',
    resetDelay: 4000,  // ms before reverting
  },
  applyOn: 'submit',   // 'submit' | 'navigation' | 'both'
  showOnce: true,       // Only warn once per field
})

Example

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

function SubmitButton({ config, values, onSubmit }) {
  const { isAwaitingConfirmation, buttonProps, handleClick, warningFields } = useSubmitConfirmation(
    {
      config,
      currentValues: values,
      onProceed: onSubmit,
      buttonType: 'submit',
    },
  );

  return (
    <div>
      <button onClick={handleClick} className={isAwaitingConfirmation ? 'border-yellow-500' : ''}>
        {buttonProps.text || 'Submit'}
      </button>
      {isAwaitingConfirmation && (
        <p className="text-sm text-yellow-600">
          You left these fields empty: {warningFields.join(', ')}
        </p>
      )}
    </div>
  );
}