save-button-placement

What problem does it solve?

Inconsistent placement and behavior of Save Changes controls leads to user confusion, accidental navigation away from unsaved edits, and duplicated or missing submission flows; this guidance defines a single SaveButton API, placement patterns, dirty-tracking flow, and dialog exceptions to eliminate those issues.

Core Features & Use Cases

• Standardized SaveButton component contract with props for onClick, isPending, hasChanges, disabled, type, size, and test identifier to ensure consistent behavior and testability.
• Three placement patterns: PageHeader actions for primary saves, bottom-of-form mirrors paired with PageHeader saves for long forms, and tab/section-level saves for isolated sections, with examples referenced for each pattern.
• Dirty-tracking flow using a local draft state compared to last-saved data, an isDirty / hasChanges flag, a beforeunload navigation warning, and mutation handling via TanStack Query to manage isPending and reset state on success.
• Dialog exception that uses standard DialogFooter buttons rather than the SaveButton to accommodate modal UX constraints.
• Practical examples include property edit pages, company assumptions pages, and admin settings tabs where each pattern and the dirty-tracking flow are demonstrated.

Quick Start

Place the SaveButton in the PageHeader actions, maintain a local draft and isDirty flag passed to hasChanges, and trigger a TanStack Query mutation while passing mutation.isPending to isPending.