@stanfordspezi/spezi-web-design-system
Version:
Stanford Biodesign Digital Health Spezi Web Design System
72 lines (71 loc) • 2.57 kB
TypeScript
import { ComponentProps, ReactNode } from 'react';
import { Dialog } from '../Dialog';
export type BlockerStatus = "idle" | "blocked";
export interface NavigationBlockerProps extends Omit<ComponentProps<typeof Dialog>, "open"> {
/**
* Controls whether the native browser beforeunload prompt should be enabled.
* When true and {@link NavigationBlockerProps#shouldBlock|shouldBlock} is true, a native prompt will appear on page reload/close.
*
* @default false
*/
enableBeforeUnload?: boolean;
/** Indicates whether there are unsaved changes that should block navigation. */
shouldBlock?: boolean;
/** When set to "blocked", the confirmation dialog is shown. */
status?: BlockerStatus;
/** When status is blocked, this function allows navigation to continue. */
proceed?: () => void;
/** When status is blocked, this function cancels navigation (status will be reset to 'idle') */
reset?: () => void;
title?: ReactNode;
description?: ReactNode;
stayLabel?: ReactNode;
leaveLabel?: ReactNode;
}
/**
* A small confirmation dialog to guard against accidental navigation when there are unsaved changes.
* This component is router-agnostic. It does not import or depend on any specific router library.
*
* @example
* ```tsx
* import { useBlocker } from "@tanstack/react-router";
* const blocker = useBlocker({
* shouldBlockFn: (location, action) => {
* // block if there are unsaved changes and the user is trying to navigate away
* return formState.isDirty && action !== "replace";
* },
* withResolver: true,
* enableBeforeUnload: true,
* });
* return (
* <NavigationBlocker
* status={blocker.status}
* proceed={blocker.proceed}
* reset={blocker.reset}
* />
* );
* ```
*
* @example
* ```tsx
* // The `enableBeforeUnload` prop enables a native browser prompt on page reload/close.
* const [dirty, setDirty] = useState(false);
* return (
* <>
* <NavigationBlocker shouldBlock={dirty} enableBeforeUnload />
* <form
* onChange={() => setDirty(true)}
* onSubmit={(e) => {
* e.preventDefault();
* // save...
* setDirty(false);
* }}
* >
* <input name="displayName" />
* <button type="submit">Save</button>
* </form>
* </>
* );
* ```
*/
export declare const NavigationBlocker: ({ status, proceed, reset, enableBeforeUnload, shouldBlock, title, description, stayLabel, leaveLabel, ...dialogProps }: NavigationBlockerProps) => import("react").JSX.Element;