Update useNavigate reference page (#1388)

Author: amirhhashemi

src/routes/solid-router/reference/primitives/use-navigate.mdx

@@ -9,31 +9,159 @@ tags:
   - programmatic
   - history
   - state
-version: '1.0'
+version: "1.0"
 description: >-
   Navigate programmatically with useNavigate - redirect users, handle auth
   flows, and control navigation with replace and scroll options.
 ---
 
-Retrieves the method which accepts a path to navigate to and an optional object with the following options:
+The `useNavigate` function provides a function for programmatically navigating to a new route.
 
-- resolve (_boolean_, default `true`): resolve the path against the current route
-- replace (_boolean_, default `false`): replace the history entry
-- scroll (_boolean_, default `true`): scroll to top after navigation
-- state (_any_, default `undefined`): pass custom state to `location.state`
+## Import
+
+```ts
+import { useNavigate } from "@solidjs/router";
+```
+
+## Type
+
+```ts
+interface NavigateOptions<S = unknown> {
+	resolve: boolean;
+	replace: boolean;
+	scroll: boolean;
+	state: S;
+}
+
+function useNavigate(): (
+	to: string,
+	options?: Partial<NavigateOptions>
+) => void;
+function useNavigate(delta: number): void;
+```
+
+## Parameters
+
+`useNavigate` takes no arguments.
+
+## Return value
+
+- **Type:** `(to: string | number, options?: NavigateOptions) => void | (delta: number) => void`
+
+Returns a function that accepts two arguments:
+
+### `to`
+
+- **Type:** `string | number`
+- **Required:** Yes
+
+The target destination.
+
+- `string`:
+  A path to navigate to.
+- `number`:
+  A history delta (e.g., `-1` for back, `1` for forward).
+  If provided, the `options` argument is ignored.
+
+### `options`
+
+- **Type:** `NavigateOptions`
+- **Required:** No
+
+Configuration object for the navigation.
+
+#### `resolve`
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Resolves the path relative to the current route.
+If `false`, the path is resolved against the root (`/`).
+
+If `to` is a query-only string (e.g., `?sort=asc`), this defaults to `false` to preserve the current pathname.
+
+#### `replace`
+
+- **Type**: `boolean`
+- **Default**: `false`
+
+Replaces the current history entry instead of adding a new one.
+Used for redirects or state updates to prevent the user from navigating back to the previous state.
+
+#### `scroll`
+
+- **Type**: `boolean`
+- **Default**: `true`
+
+Scrolls the window to the top after navigation.
+
+- `true`:
+  Scrolls to the top or to the element matching the hash.
+- `false`:
+  Maintains the current scroll position (unless a hash matches).
+
+#### `state`
+
+- **Type**: `any`
+- **Default**: `undefined`
+
+Arbitrary state stored in `history.state`.
+This value is accessible via `useLocation().state`.
+
+State is serialized using the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which supports most built-in types but not functions or DOM nodes.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { useNavigate } from "@solidjs/router";
+
+const navigate = useNavigate();
+
+navigate("/users/123");
+```
+
+### With `replace`
+
+```tsx
+import { useNavigate } from "@solidjs/router";
+
+const navigate = useNavigate();
+
+// Redirect (replace history)
+function login() {
+	navigate("/dashboard", { replace: true });
+}
+```
+
+### With `delta`
+
+```tsx
+import { useNavigate } from "@solidjs/router";
 
-```js
 const navigate = useNavigate();
 
-if (unauthorized) {
-	navigate("/login", { replace: true });
+// Go back one page
+function goBack() {
+	navigate(-1);
 }
 ```
 
-If you are inside of a query, action or cache (deprecated) function you will instead want to use [redirect](/solid-router/reference/response-helpers/redirect) or [reload](/solid-router/reference/response-helpers/reload).
+### With `state`
+
+```tsx
+import { useNavigate } from "@solidjs/router";
+
+const navigate = useNavigate();
+
+// Pass custom state
+navigate("/checkout", {
+	state: { from: "cart", total: 100 },
+});
+```
+
+## Related
 
-:::note
-	The state is serialized using the [structured clone
-	algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)
-	which does not support all object types.
-:::
+- [useLocation](/solid-router/reference/primitives/use-location)
+- [redirect](/solid-router/reference/response-helpers/redirect)