React Unsaved Changes Hook

A React hook and provider for managing unsaved changes in web applications, providing an easy way to prevent users from accidentally navigating away from a page with unsaved work.

Features

• useUnsavedChanges Hook: Easily track changes within a component.
• UnsavedChangesProvider: Manage global unsaved changes state across your application.
• Customizable Prompt: Configure the message shown to users when unsaved changes are detected.
• Blocking Navigation: Integrates with browser's beforeunload event to prevent accidental page closes or reloads.

Installation

You can install the hook using npm or yarn:

npm install react-unsaved-changes-hook
# or
yarn add react-unsaved-changes-hook

This package requires react and react-dom as peer dependencies. Make sure you have them installed in your project:

npm install react react-dom
# or
yarn add react react-dom

Usage

1. UnsavedChangesProvider

Wrap your application or a part of it with UnsavedChangesProvider to enable unsaved changes tracking.

import React from "react";
import ReactDOM from "react-dom/client";
import { UnsavedChangesProvider } from "react-unsaved-changes-hook";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <UnsavedChangesProvider
      // Optional: Custom message for the browser's beforeunload dialog
      alertMessage="You have unsaved changes. Are you sure you want to leave?"
    >
      <App />
    </UnsavedChangesProvider>
  </React.StrictMode>
);

Props

• alertMessage?: string: An optional custom message to display in the browser's beforeunload confirmation dialog. If not provided, a default browser message will be used.
• children: React.ReactNode: The components that will have access to the unsaved changes context.

2. useUnsavedChanges Hook

Use the useUnsavedChanges hook in any functional component to signal whether there are unsaved changes.

import React, { useState } from "react";
import { useUnsavedChanges } from "react-unsaved-changes-hook";

function MyForm() {
  const [value, setValue] = useState("");
  const [isChanged, setIsChanged] = useState(false);

  // Set unsaved changes status
  useUnsavedChanges(isChanged);

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setValue(e.target.value);
    setIsChanged(true); // Mark as changed when input is modified
  };

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    // Save logic here
    console.log("Saving:", value);
    setIsChanged(false); // Mark as unchanged after saving
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="text" value={value} onChange={handleChange} />
      <button type="submit">Save</button>
      {isChanged && <span>Unsaved changes!</span>}
    </form>
  );
}

export default MyForm;

Parameters

• hasUnsavedChanges: boolean: A boolean indicating whether the current component or form has unsaved changes. When true, the beforeunload event will be triggered, prompting the user.

API Reference

UnsavedChangesProvider

The provider component that manages the global state for unsaved changes.

interface UnsavedChangesProviderProps {
  alertMessage?: string;
  children: React.ReactNode;
}

useUnsavedChanges(hasUnsavedChanges: boolean)

A hook to signal to the UnsavedChangesProvider whether the current component has unsaved changes.

Parameters

• hasUnsavedChanges: boolean: A flag that, when true, indicates there are unsaved changes and will trigger the browser's beforeunload event.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.