UX Patterns Guide
UI + UX Error Prevention And Recovery established

Unsaved changes prompt

Track the dirty edit buffer, intercept abandonment or replacement actions, present a specific save-discard-stay decision with changed-field evidence, complete or fail saving before continuing, and clear the prompt only when the edit buffer is safe, intentionally discarded, or still preserved.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • A close, cancel, switch, or edit-mode exit would discard unsaved local changes.
  • The editor can identify changed fields or sections and keep them available while the decision is made.
  • Users need an explicit choice between saving, discarding, reviewing, and continuing to edit.
  • Autosave, draft, or recovery mechanisms do not already make the current dirty buffer safe.

Avoid when

  • There are no actual unsaved changes.
  • Every latest change is already saved or safely recoverable.
  • The problem is broad browser or route departure covered by exit warning.
  • The task is a destructive command unrelated to local dirty edits.
  • A durable draft lifecycle is the main user model.

Problem it prevents

Users can close an editor, cancel a modal, switch objects, replace selections, or exit edit mode while local changes are dirty, causing accidental loss or uncertainty about whether the latest values were saved.

Test the behavior

Open the interactive example when you need it

The full lab is intentionally loaded on request. That keeps this reading page fast while preserving the strong and weak states, keyboard checks, and failure scenarios.

In the lab you can
  • switch between strong UI, weak UI, strong UX, and weak UX;
  • trigger required, empty, loading, error, and recovery states;
  • inspect keyboard and accessibility expectations beside the demo.
Launch Unsaved changes prompt in the lab
Pattern anatomy

What a strong implementation has to make clear

User need

The surface has editable values that can differ from the last saved record.

Pattern promise

Track the dirty edit buffer, intercept abandonment or replacement actions, present a specific save-discard-stay decision with changed-field evidence, complete or fail saving before continuing, and clear the prompt only when the edit buffer is safe, intentionally discarded, or still preserved.

Required state

Clean editor state with no prompt.

Recovery path

A clean editor still prompts on close and trains users to ignore warnings.

Access contract

Use dialog or alertdialog semantics when the prompt interrupts the current task and requires a response.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A profile editor close button opens Save changes to Billing contact?, lists edited phone and department fields, and offers Keep editing, Review changes, Save changes, or Discard changes.
  • A report detail page blocks switching to another report while the current report has unsaved title and filter edits, then continues to the requested report only after save or discard succeeds.
  • A user edits two fields, clicks Close, reviews the changed fields in the prompt, saves, and the editor closes only after the saved state is confirmed.
  • A user chooses Keep editing from the prompt and returns to the same dirty editor with focus near the close control and all unsaved values intact.
Weak implementation

Vague, hidden, hard to recover from

  • A modal says Are you sure? when the user clicks Cancel, with OK and Cancel labels that do not say whether edits will be saved or discarded.
  • A tab switch silently replaces the dirty editor with a different record and loses the user's typed notes.
  • A user chooses Save, the request fails, and the editor still closes as though the latest values were safe.
  • A prompt appears for every close action even when no field changed, so users stop reading the actual discard warning.
UI guidance
  • Show a focused prompt when users try to close, cancel, switch records, replace content, or leave edit mode while current edits are dirty and not yet recoverable.
  • Name the edited object, summarize what changed, and offer distinct Save changes, Discard changes, Review changes, and Keep editing choices when the system can support them.
UX guidance
  • Use an unsaved changes prompt to protect local edits at the moment a user is about to abandon or replace them inside the product.
  • Treat the prompt as a decision about the current edit buffer: saving must complete before the close or switch continues, discarding must be deliberate, and staying must preserve every typed value.
Implementation contract

What the implementation must handle

States

  • Clean editor state with no prompt.
  • Dirty editor state with changed-field tracking.
  • Close, cancel, object switch, or mode switch attempted state.
  • Prompt open with object name and changed-field summary.

Interaction

  • Opening the prompt never clears the dirty values.
  • Keep editing closes the prompt, preserves all local values, and returns focus to the editor or triggering control.
  • Review changes shows what changed before the user saves or discards.
  • Save changes sends the current dirty values once, disables duplicate save and discard while saving, and continues only after success.

Accessibility

  • Use dialog or alertdialog semantics when the prompt interrupts the current task and requires a response.
  • Give the prompt an accessible name that includes the object or action, such as Save changes to Billing contact?
  • Associate the changed-field summary with the dialog description.
  • Move focus into the prompt and return focus to the triggering close, cancel, or editor control after Keep editing.

Review

  • What exact object or fields are dirty?
  • Which user actions can destroy or replace the dirty edit buffer?
  • Can users inspect changed fields before deciding?
  • Does Save complete before close, cancel, or switch continues?
Evidence trail

Source-backed claims behind this guidance

MDN: Window beforeunload event

Mozilla - checked

MDN documents warning users about unsaved data loss and limiting listeners to actual unsaved-change conditions.

GitLab Pajamas: Saving and feedback

GitLab Pajamas Design System - checked

GitLab Pajamas documents save feedback, failed-save recovery, undo, and leave warnings for unsaved form changes.

Full agent/debug reference

Problem Context

  • The surface has editable values that can differ from the last saved record.
  • A close, cancel, object switch, tab switch, mode switch, replace, or route action can remove the current edit buffer.
  • The product can identify the object and at least a useful summary of changed fields.
  • Users need to choose whether to keep editing, save first, review changes, or intentionally discard local edits.

Selection Rules

  • Choose unsaved changes prompt when a user action inside the product would abandon or replace dirty local edits before they are saved.
  • Use exit warning when the trigger is broader page, browser, route, reload, external-link, or sign-out departure rather than a focused editor close or object switch.
  • Use autosave form when reliable background saving makes abandonment safe or when the main job is continuous progress persistence.
  • Use autosave recovery when saving has already failed or become uncertain and users need retry, copy, compare, or restore evidence.
  • Use draft state when the unsaved work is a durable unpublished object that can be resumed later from lists or deep links.
  • Use confirmation dialog for explicit consequential commands such as Delete, Cancel application, or Discard draft; an unsaved changes prompt is specifically about dirty edit-buffer loss.
  • Show the prompt only when dirty state is real; do not prompt for clean editors, read-only views, or recoverable drafts already saved elsewhere.
  • If Save changes is offered, keep the prompt open or show a saving state until the save succeeds; do not close the editor after failed save.
  • If Discard changes is offered, label it as discard and identify the affected object or fields.
  • Offer Review changes when users may need to inspect field-level differences before deciding.

Required States

  • Clean editor state with no prompt.
  • Dirty editor state with changed-field tracking.
  • Close, cancel, object switch, or mode switch attempted state.
  • Prompt open with object name and changed-field summary.
  • Review changes state showing before and after values or changed sections.
  • Save in progress state that blocks duplicate close or switch actions.
  • Save failed state that keeps the editor open with values intact.
  • Saved and continue state that closes or switches after success.
  • Discarded state that clears the dirty buffer intentionally.
  • Keep editing state that returns focus and preserves values.

Interaction Contract

  • Opening the prompt never clears the dirty values.
  • Keep editing closes the prompt, preserves all local values, and returns focus to the editor or triggering control.
  • Review changes shows what changed before the user saves or discards.
  • Save changes sends the current dirty values once, disables duplicate save and discard while saving, and continues only after success.
  • A failed save leaves the prompt or editor visible, explains the failure, and keeps the unsaved values editable.
  • Discard changes requires a deliberate action and clears only the named dirty buffer.
  • After save, discard, or reset to clean state, the same close or switch action does not prompt again.

Implementation Checklist

  • Track dirty state from actual field values, not from opening an editor.
  • Store changed field names, original values when safe to show, current values, target close or switch action, and save request state.
  • Intercept close, cancel, record switch, tab switch, inline edit exit, modal dismissal, replacement, and route actions that would destroy the dirty buffer.
  • Use explicit button labels such as Keep editing, Review changes, Save changes, and Discard changes.
  • Make save idempotent or disable repeated save while a request is in flight.
  • Keep values in memory and visible after save failure.
  • Clear dirty state after confirmed save, explicit discard, reset, or successful autosave that truly covers the latest values.
  • Test clean close, dirty close, object switch, failed save, double activation, discard, review, keyboard Escape, focus return, screen reader labels, and mobile dismissal gestures.

Common Generated-UI Mistakes

  • Prompting when nothing changed.
  • Using OK and Cancel labels that hide whether edits will be saved, discarded, or preserved.
  • Closing after Save even when the save request failed.
  • Discarding all editor state when only one embedded panel was dirty.
  • Showing a warning but omitting a way to keep editing.
  • Replacing the dirty object during a tab or record switch without a save or discard decision.
  • Relying on a disappearing toast to say edits were not saved.

Critique Questions

  • What exact object or fields are dirty?
  • Which user actions can destroy or replace the dirty edit buffer?
  • Can users inspect changed fields before deciding?
  • Does Save complete before close, cancel, or switch continues?
  • What happens when Save fails or the user activates Save twice?
  • Does Keep editing preserve values and return focus predictably?
  • Does the prompt disappear for clean state?
Accessibility
  • Use dialog or alertdialog semantics when the prompt interrupts the current task and requires a response.
  • Give the prompt an accessible name that includes the object or action, such as Save changes to Billing contact?
  • Associate the changed-field summary with the dialog description.
  • Move focus into the prompt and return focus to the triggering close, cancel, or editor control after Keep editing.
  • Use explicit action labels; do not rely on color, icon-only controls, or OK and Cancel.
  • Announce save in progress, save failed, saved, and discarded states through status text.
  • Keep Review changes, Save changes, Discard changes, and Keep editing reachable by keyboard.
Keyboard Behavior
  • Enter or Space on close, cancel, switch, or replace opens the prompt when dirty state exists.
  • Initial focus supports safe decision-making, usually Keep editing or the prompt heading for severe loss.
  • Tab and Shift+Tab stay within the prompt while it is open.
  • Escape follows the safe Keep editing path unless the platform convention requires a visible close control with the same effect.
  • Save changes disables duplicate activation while saving and leaves focus stable.
  • After failed save, focus moves to or remains near the failure message and recovery actions.
  • After discard or saved close, focus moves to the destination or stable outcome state.
Variants
  • Close editor unsaved prompt
  • Cancel edit unsaved prompt
  • Switch record unsaved prompt
  • Switch tab unsaved prompt
  • Discard local changes prompt
  • Review unsaved changes prompt
  • Save before close prompt
  • Failed save before close prompt

Verification

Source trail checked:

Saved items