useSubmitConfirmation

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

View as Markdown

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);

The hook takes positional arguments (not an options object).

Parameters

Parameter Type Required Description
config FormConfig Yes Form config with submitConfirmation
currentValues Record<string, unknown> Yes Live form values (from methods.watch())
onProceed () => void Yes Callback when the action is confirmed
buttonType 'submit' | 'next' No Which button this applies to (default: 'submit')

Return Value

Property Type Description
needsConfirmation boolean Whether the next click will show a warning (empty optional fields, filtered by applyOn and showOnce)
isAwaitingConfirmation boolean Whether the button is in warning state (waiting for second click)
warningFields string[] Names of the empty optional fields (populated after the first click)
buttonProps { text?, variant?, effect? } Override props for the button during warning state
handleClick (e: React.MouseEvent<HTMLButtonElement>) => void Click handler (first click = warn, second click = proceed)
resetConfirmation () => void Manually 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

The hook reads config.submitConfirmation, set via the submitConfirmation() method on FormBuilder:

FormBuilder.create('contact')
  // ...fields
  .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 (default: 3000)
    },
    applyOn: 'submit', // 'submit' | 'steps' | 'both' — 'steps' targets the Next button
    showOnce: true, // Only warn once per session (default: true)
  })
  .build();

Example

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

function SubmitButton({ config, values, onSubmit }) {
  const { isAwaitingConfirmation, buttonProps, handleClick, warningFields } = useSubmitConfirmation(
    config,
    values,
    onSubmit,
    '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>
  );
}