From a0d6c4fe08c7d95e4811bbfa972f529e0a5304d5 Mon Sep 17 00:00:00 2001
From: Matt Brophy <matt@brophy.org>
Date: Mon, 31 Jul 2023 11:10:04 -0400
Subject: [PATCH] Update docs for useNavigate() (#10749)

---
 docs/hooks/use-navigate.md | 77 ++++++++++++++++++++++++++++----------
 1 file changed, 58 insertions(+), 19 deletions(-)

diff --git a/docs/hooks/use-navigate.md b/docs/hooks/use-navigate.md
index 97b8c2b4ba..f9131ea820 100644
--- a/docs/hooks/use-navigate.md
+++ b/docs/hooks/use-navigate.md
@@ -4,6 +4,29 @@ title: useNavigate
 
 # `useNavigate`
 
+<details>
+  <summary>Type declaration</summary>
+
+```tsx
+declare function useNavigate(): NavigateFunction;
+
+interface NavigateFunction {
+  (to: To, options?: NavigateOptions): void;
+  (delta: number): void;
+}
+
+interface NavigateOptions {
+  replace?: boolean;
+  state?: any;
+  preventScrollReset?: boolean;
+  relative?: RelativeRoutingType;
+}
+
+type RelativeRoutingType = "route" | "path";
+```
+
+</details>
+
 <docs-warning>It's usually better to use [`redirect`][redirect] in [`loaders`][loaders] and [`actions`][actions] than this hook</docs-warning>
 
 The `useNavigate` hook returns a function that lets you navigate programmatically, for example in an effect:
@@ -24,31 +47,47 @@ function useLogoutTimer() {
 }
 ```
 
-## Type Declaration
+The `navigate` function has two signatures:
 
-```tsx
-declare function useNavigate(): NavigateFunction;
+- Either pass a `To` value (same type as `<Link to>`) with an optional second `options` argument (similar to the props you can pass to [`<Link>`][link]), or
+- Pass the delta you want to go in the history stack. For example, `navigate(-1)` is equivalent to hitting the back button
 
-interface NavigateFunction {
-  (
-    to: To,
-    options?: {
-      replace?: boolean;
-      state?: any;
-      relative?: RelativeRoutingType;
-    }
-  ): void;
-  (delta: number): void;
-}
-```
+## `options.replace`
 
-The `navigate` function has two signatures:
+Specifying `replace: true` will cause the navigation will replace the current entry in the history stack instead of adding a new one.
+
+## `options.state`
 
-- Either pass a `To` value (same type as `<Link to>`) with an optional second `{ replace, state }` arg or
-- Pass the delta you want to go in the history stack. For example, `navigate(-1)` is equivalent to hitting the back button.
+You may include an optional state value in to store in [history state][history-state]
 
-If using `replace: true`, the navigation will replace the current entry in the history stack instead of adding a new one.
+## `options.preventScrollReset`
+
+When using the [`<ScrollRestoration>`][scrollrestoration] component, you can disable resetting the scroll to the top of the page via `options.preventScrollReset`
+
+## `options.relative`
+
+By default, navigation is relative to the route hierarchy, so `..` will go up one `Route` level. Occasionally, you may find that you have matching URL patterns that do not make sense to be nested, and you'd prefer to use relative _path_ routing. You can opt into this behavior with `relative: true`:
+
+```jsx
+// Contact and EditContact do not share additional UI layout
+<Route path="/" element={<Layout />}>
+  <Route path="contacts/:id" element={<Contact />} />
+  <Route
+    path="contacts/:id/edit"
+    element={<EditContact />}
+  />
+</Route>;
+
+function EditContact() {
+  // Since Contact is not a parent of EditContact we need to go up one level
+  // in the path, instead of one level in the Route hierarchy
+  navigate("..", { relative: "path" });
+}
+```
 
+[link]: ../components/link
 [redirect]: ../fetch/redirect
 [loaders]: ../route/loader
 [actions]: ../route/action
+[history-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state
+[scrollrestoration]: ../components/scroll-restoration