# nextjs-nav-guard
Navigation guard for Next.js App Router. Prevent users from accidentally leaving pages with unsaved changes.
**Version note:** The navigation concurrency fixes and `NavigationGuardLink` documented here require version `1.1.0` or later. They are not included in `1.0.9`. See the [changelog](https://github.com/br-schneider/nextjs-nav-guard/blob/main/CHANGELOG) for release details.
Maintained by [Brett Schneider](https://github.com/br-schneider), based on [`next-navigation-guard`](https://github.com/LayerXcom/next-navigation-guard) by [LayerX](https://github.com/LayerXcom). This fork focuses on App Router compatibility, predictable confirmation behavior, and browser regression tests.
[Documentation](https://nextjs-nav-guard.vercel.app/) · [Run the demo](#demo) · [Contribute](https://github.com/br-schneider/nextjs-nav-guard/blob/main/CONTRIBUTING.md) · [Roadmap](https://github.com/br-schneider/nextjs-nav-guard/blob/main/ROADMAP.md)
[](https://github.com/br-schneider/nextjs-nav-guard/actions/workflows/e2e-tests.yml)
## What's different from the original?
- **Next.js 16.2+ support:** fixed a runtime crash caused by `null` `history.state` in newer Next.js versions
- **Resilient internals:** private `next/dist/*` imports are centralized; if the context cannot be loaded, router and link interception are unavailable and a development warning explains it
- **Fixed React hooks violation:** removed a conditional `useContext` call that broke the rules of hooks
- **Pages Router removed:** focused on App Router only; Next.js still supports Pages Router, but this package does not
- **Better error messages:** actionable errors when the provider is missing, with code examples
- **Predictable confirmation:** overlapping attempts are blocked until the first attempt settles; unmounting or disabling a guard cancels its pending attempt
- **Explicit link integration:** `NavigationGuardLink` preserves `replace`, `scroll`, `onClick`, and `onNavigate`
- **Actively maintained:** compatible with Next.js 14, 15, and 16 (including 16.2+)
## Install
```bash
npm install nextjs-nav-guard
```
## Setup
Wrap your app with `NavigationGuardProvider` in your root layout. Mount the provider unconditionally, including while authentication or other async content is loading. Put loading branches inside it so its history listener registers before Next.js handles browser navigation.
```tsx
// app/layout.tsx
import { NavigationGuardProvider } from "nextjs-nav-guard";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
## Usage
### Simple: `window.confirm()`
```tsx
"use client";
import { useState } from "react";
import { useNavigationGuard } from "nextjs-nav-guard";
export default function NameForm() {
const [name, setName] = useState("");
useNavigationGuard({
enabled: name !== "",
confirm: () => window.confirm("Discard your changes?"),
});
return (
);
}
```
### Custom dialog UI
If you want full control over the confirmation UI, omit the `confirm` callback. The hook returns `active`, `accept`, and `reject` to drive your own dialog:
```tsx
"use client";
import { useEffect, useRef, useState } from "react";
import { useNavigationGuard } from "nextjs-nav-guard";
export default function NoteForm() {
const [note, setNote] = useState("");
const dialogRef = useRef(null);
const guard = useNavigationGuard({ enabled: note !== "" });
useEffect(() => {
const dialog = dialogRef.current;
if (guard.active && dialog && !dialog.open) dialog.showModal();
if (!guard.active && dialog?.open) dialog.close();
}, [guard.active]);
return (
<>