Form Page Guard (Next.js App Router)

Form Page Guard (Next.js App Router) blocks in-app navigation while a Form Page is dirty. Form Page itself is router-agnostic: it owns the native tab-close prompt and broadcasts guard state. This item is the Next.js App Router adapter. Requires Next.js ≥ 15.3 (onNavigate on Link).

This docs app does not run the Next.js App Router, so the live example is the wiring checklist. Copy the Usage snippet into a Next host.

When To Use

• The host is Next.js App Router and Form Page warnOnUnsavedChanges should stop Link / router.push / back.
• Pair with Form Page — do not install this adapter without it.
• Use Form Page Guard (TanStack Router) instead on TanStack Router hosts.
• Do not mix next/link + useRouter with a dirty form. Only GuardedLink / useGuardedRouter consult the provider.
• The native tab-close prompt stays on Form Page. This adapter does not replace beforeunload.

Features

Installing

pnpm dlx shadcn@latest add https://ui.isaacfei.com/api/plus/r/form-page-guard-next.json

npx shadcn@latest add https://ui.isaacfei.com/api/plus/r/form-page-guard-next.json

yarn dlx shadcn@latest add https://ui.isaacfei.com/api/plus/r/form-page-guard-next.json

bunx shadcn@latest add https://ui.isaacfei.com/api/plus/r/form-page-guard-next.json

With the @f-ui-plus namespace configured in components.json, shadcn add @f-ui-plus/form-page-guard-next also works.

registryDependencies: @f-ui-plus/form-page. Peer: Next.js ≥ 15.3 (next/link, next/navigation).

Usage

import {
  FormNavigationGuardProvider,
  FormPageUnsavedGuard,
  GuardedLink,
  useGuardedRouter,
} from "@/components/f-ui/form-page/navigation-guard/next-app-router";

// app/layout.tsx
<FormNavigationGuardProvider>{children}</FormNavigationGuardProvider>;

// form page
<FormPage form={form} onFinish={handleSubmit} warnOnUnsavedChanges>
  <FormPageUnsavedGuard />
  {/* fields */}
</FormPage>;

function Actions() {
  const router = useGuardedRouter();
  return (
    <>
      <GuardedLink href="/orders">Back to orders</GuardedLink>
      <button type="button" onClick={() => router.push("/orders")}>
        Cancel
      </button>
    </>
  );
}

Examples

Three Pieces

Provider at the layout, guard inside Form Page, guarded navigation primitives everywhere else. Skipping any one of these lets a dirty form navigate away with no confirm.

"use client";

import { SectionCard } from "@/components/f-ui/section-card/section-card";

/** Next.js App Router wiring — this docs app is not Next, so the adapter is not mounted. */
export function FormPageGuardNextDemo() {
  return (
    <SectionCard title="Three pieces">
      <ol className="text-sm text-muted-foreground list-decimal space-y-2 pl-5">
        <li>
          Wrap the app in <code>FormNavigationGuardProvider</code> (layout).
        </li>
        <li>
          Drop <code>FormPageUnsavedGuard</code> inside <code>FormPage</code>.
        </li>
        <li>
          Navigate with <code>GuardedLink</code> or <code>useGuardedRouter</code> — not{" "}
          <code>next/link</code> / <code>useRouter</code> alone.
        </li>
      </ol>
    </SectionCard>
  );
}

API Reference

FormNavigationGuardProvider

FormPageUnsavedGuard

No props. Must be a child of FormPage (reads guard context) and under FormNavigationGuardProvider. Renders null; the provider paints the dialog.

Throws if the provider is missing.

GuardedLink

Forwards next/link props. While dirty, onNavigate is prevented and the confirm runs before router.push(href).

useGuardedRouter

Returns { push, replace, back, forward, refresh }. push / replace / back call the guard registry; forward and refresh pass through.

useNextFormNavigationGuard

Low-level { when, confirm? } registration if you are not using FormPageUnsavedGuard. Prefer the drop-in guard inside Form Page.