use-form-guard

Framework-agnostic React hook to prevent accidental navigation when a form has unsaved changes.

Works with React Hook Form, Formik, TanStack Form, or any boolean dirty state.
Covers browser tab close, SPA navigation, and the browser back/forward button — including Next.js App Router.

---

The Problem

Every form-heavy app needs this pattern:

User types something → clicks a link → browser asks "You have unsaved changes. Leave?"

React Hook Form gives you formState.isDirty, but it does not handle:

• Browser tab close / refresh (beforeunload)
• SPA navigation (router.push(), <Link> clicks)
• The browser back / forward button (popstate)

Next.js App Router made this especially painful by removing the router.events API that Pages Router developers relied on. There is no official solution — developers have been copy-pasting 30+ line hacks in every project.

use-form-guard solves all of this in one hook.

---

Features

• Zero dependencies — only requires React ≥ 17 as a peer
• Framework-agnostic — works with React Hook Form, Formik, TanStack Form, useState, anything
• Covers all exit paths — tab close, SPA navigation, back/forward button
• Next.js App Router support — patches history.pushState to intercept <Link> clicks and router.push()
• Custom dialog support — bring your own modal instead of the native window.confirm()
• TypeScript-first — full type inference, no @types/* needed
• Tiny — ~1.75 KB minified (~0.8 KB gzipped)

---

Installation

npm install use-form-guard
# or
pnpm add use-form-guard
# or
yarn add use-form-guard

---

Usage

With React Hook Form

import { useForm } from 'react-hook-form'
import { useFormGuard } from 'use-form-guard'

function EditProfileForm() {
  const { register, handleSubmit, formState: { isDirty } } = useForm()

  useFormGuard(isDirty)

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('name')} />
      <button type="submit">Save</button>
    </form>
  )
}

With useState (or any boolean)

import { useState } from 'react'
import { useFormGuard } from 'use-form-guard'

function EditForm() {
  const [isDirty, setIsDirty] = useState(false)

  useFormGuard(isDirty)

  return (
    <textarea onChange={() => setIsDirty(true)} />
  )
}

With Formik

import { useFormik } from 'formik'
import { useFormGuard } from 'use-form-guard'

function MyForm() {
  const formik = useFormik({ ... })

  useFormGuard(formik.dirty)

  return <form onSubmit={formik.handleSubmit}>...</form>
}

With a custom dialog (no window.confirm)

import { useFormGuard } from 'use-form-guard'
import { openConfirmModal } from './my-modal'

function EditForm() {
  const [isDirty, setIsDirty] = useState(false)

  useFormGuard({
    isDirty,
    onBlock: () => openConfirmModal({
      title: 'Unsaved Changes',
      message: 'You have unsaved changes. Are you sure you want to leave?',
    }),
    // openConfirmModal must return Promise<boolean>
    // true  → allow navigation
    // false → stay on page
  })

  return <form>...</form>
}

With a custom message

useFormGuard({
  isDirty,
  message: 'Your draft will be lost. Leave anyway?',
})

Temporarily disable the guard

const [isDirty, setIsDirty] = useState(false)
const [isPreviewMode, setIsPreviewMode] = useState(false)

useFormGuard({
  isDirty,
  enabled: !isPreviewMode, // disable guard in preview mode
})

---

API

useFormGuard(isDirty, options?)

useFormGuard(isDirty: boolean, options?: Options): Result

useFormGuard(options)

useFormGuard(options: Options): Result

Options

Property	Type	Default	Description
isDirty	boolean	—	Whether the form has unsaved changes.
message	string	'You have unsaved changes. Are you sure...'	Message for the window.confirm() SPA navigation dialog.
onBlock	() => Promise<boolean>	undefined	Custom async dialog. Return true to allow, false to block. Not called on tab close / refresh (browser security restriction).
enabled	boolean	true	Set to false to temporarily disable without changing isDirty.

Result

Property	Type	Description
isBlocked	boolean	Whether navigation is currently being guarded.

---

How It Works

use-form-guard guards three exit paths:

Exit path	Mechanism
Tab close / refresh / hard navigation	window.beforeunload event
SPA navigation (<Link>, router.push())	history.pushState / replaceState patching
Browser back / forward button	popstate event + history.go()

Next.js App Router

In Next.js App Router, router.events was removed. use-form-guard works around this by patching window.history.pushState and window.history.replaceState — the same methods that Next.js's router calls internally when navigating.

Note: For full reliability with custom async dialogs (onBlock) in Next.js App Router, it is recommended to test your specific setup, as React's concurrent rendering may have already started a transition before pushState is intercepted.

---

Comparison

Feature	use-form-guard	Manual beforeunload	react-router-prompt
Tab close / refresh	✅	✅	❌
<Link> / router.push()	✅	❌	✅ (React Router only)
Browser back / forward	✅	❌	✅ (React Router only)
Next.js App Router	✅	❌	❌
Custom dialog	✅	❌	✅
Framework-agnostic	✅	✅	❌
Zero dependencies	✅	✅	❌
TypeScript-first	✅	manual	✅

---

Contributing

Contributions, issues, and feature requests are welcome.
Please check the issues page before submitting.

---

License

MIT © rl0425