# useSubmitConfirmation

URL: https://docs.forms.saastro.io/docs/use-submit-confirmation
> 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

```tsx

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`:

```tsx
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

```tsx

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

---

## Related

- [FormBuilder API](/docs/formbuilder) — `submitConfirmation()` configuration reference