docs: link docs

remix-run · brophdawg11 · Sep 13, 2023 · Aug 31, 2023 · Aug 31, 2023 · Aug 29, 2023
commit 49deef498c90c5aa927cfee7fc89eec5e92eed46
diff --git a/docs/components/link.md b/docs/components/link.md
@@ -4,25 +4,17 @@ title: Link
 
 # `<Link>`
 
-This component renders an anchor tag and is the primary way the user will navigate around your website. Anywhere you would have used `<a href="...">` you should now use `<Link to="..."/>` to get all the performance benefits of client-side routing in Remix.
+A `<a href>` wrapper to enable navigation with client-side routing.
 
 ```tsx
 import { Link } from "@remix-run/react";
 
-export default function GlobalNav() {
-  return (
-    <nav>
-      <Link to="/dashboard">Dashboard</Link>{" "}
-      <Link to="/account">Account</Link>{" "}
-      <Link to="/support">Support</Link>
-    </nav>
-  );
-}
+<Link to="/dashboard">Dashboard</Link>;
 ```
 
 ## `prefetch`
 
-In the effort to remove all loading states from your UI, `Link` can automatically prefetch all the resources the next page needs: JavaScript modules, stylesheets, and data. This prop controls if and when that happens.
+Defines the data and module prefetching behavior for the link.
 
 ```tsx
 <>
@@ -34,17 +26,122 @@ In the effort to remove all loading states from your UI, `Link` can automaticall
 </>
 ```
 
-- **"none"** - Default behavior. This will prevent any prefetching from happening. This is recommended when linking to pages that require a user session that the browser won't be able to prefetch anyway.
-- **"intent"** - Recommended if you want to prefetch. Fetches when Remix thinks the user intends to visit the link. Right now the behavior is simple: if they hover or focus the link it will prefetch the resources. In the future we hope to make this even smarter. Links with large click areas/padding get a bit of a head start. It is worth noting that when using `prefetch="intent"`, `<link rel="prefetch">` elements will be inserted on hover/focus and removed if the `<Link>` loses hover/focus. Without proper `cache-control` headers on your loaders, this could result in repeated prefetch loads if a user continually hovers on and off a link.
-- **"render"** - Fetches when the link is rendered.
-- **"viewport"** - Fetches while the link is in the viewport
+- **none** - default, no prefetching
+- **intent** - prefetches when the user hovers or focuses the link
+- **render** - prefetches when the link renders
+- **viewport** - prefetches when the link is in the viewport, very useful for mobile
+
+Prefetching is done with HTML `<link rel="prefetch">` tags. They are inserted after the link.
+
+```tsx
+<nav>
+  <a href="..." />
+  <a href="..." />
+  <link rel="prefetch" /> {/* might conditionally render */}
+</nav>
+```
+
+Because of this, if you are using `nav :last-child` you will need to use `nav :last-of-type` so the styles don't conditionally fall off your last link (and any other similar selectors).
+
+## `preventScrollReset`
+
+If you are using [`<ScrollRestoration>`](./scroll-restoration), this lets you prevent the scroll position from being reset to the top of the window when the link is clicked.
+
+```tsx
+<Link to="?tab=one" preventScrollReset />
+```
+
+This does not prevent the scroll position from being restored when the user comes back to the location with the back/forward buttons, it just prevents the reset when the user clicks the link.
+
+<details>
+<summary>Discussion</summary>
+
+An example when you might want this behavior is a list of tabs that manipulate the url search params that aren't at the top of the page. You wouldn't want the scroll position to jump up to the top because it might scroll the toggled content out of the viewport!
+
+```
+      ┌─────────────────────────┐
+      │                         ├──┐
+      │                         │  │
+      │                         │  │ scrolled
+      │                         │  │ out of view
+      │                         │  │
+      │                         │ ◄┘
+    ┌─┴─────────────────────────┴─┐
+    │                             ├─┐
+    │                             │ │ viewport
+    │   ┌─────────────────────┐   │ │
+    │   │  tab   tab   tab    │   │ │
+    │   ├─────────────────────┤   │ │
+    │   │                     │   │ │
+    │   │                     │   │ │
+    │   │ content             │   │ │
+    │   │                     │   │ │
+    │   │                     │   │ │
+    │   └─────────────────────┘   │ │
+    │                             │◄┘
+    └─────────────────────────────┘
+
+```
+
+</details>
+
+## `relative`
+
+Defines the relative path behavior for the link.
+
+```tsx
+<Link to=".." />; // default: "route"
+<Link relative="route" />;
+<Link relative="path" />;
+```
+
+- **route** - default, relative to the route hierarchy so `..` will remove all URL segments of the current route pattern
+- **path** - relative to the path so `..` will remove one URL segment
+
+## `reloadDocument`
+
+Will use document navigation instead of client side routing when the link is clicked, the browser will handle the transition normally (as if it were an `<a href>`).
+
+```tsx
+<Link to="/logout" reloadDocument />
+```
+
+## `replace`
+
+The `replace` prop will replace the current entry in the history stack instead of pushing a new one onto it.
 
-<docs-error>You may need to use the <code>:last-of-type</code> selector instead of <code>:last-child</code> when styling child elements inside of your links</docs-error>
+```tsx
+<Link replace />
+```
 
-Remix uses the browser's cache for prefetching with HTML `<link rel="prefetch"/>` tags, which provides a lot of subtle benefits (like respecting HTTP cache headers, doing the work in browser idle time, using a different thread than your app, etc.) but the implementation might mess with your CSS since the link tags are rendered inside of your anchor tag. This means `a *:last-child {}` style selectors won't work. You'll need to change them to `a *:last-of-type {}` and you should be good. We will eventually get rid of this limitation.
+```
+# with a history stack like this
+A -> B
 
-## React Router `<Link/>`
+# normal link click pushes a new entry
+A -> B -> C
+
+# but with `replace`, B is replaced by C
+A -> C
+```
+
+## `state`
+
+Adds persistent client side routing state to the next location.
+
+```tsx
+<Link to="/somewhere/else" state={{ some: "value" }} />
+```
+
+The location state is accessed from the `location`.
+
+```ts
+function SomeComp() {
+  const location = useLocation();
+  location.state; // { some: "value" }
+}
+```
 
-This component is a wrapper around [React Router `<Link/>`][rr-link]. It has the same API except for Remix's `prefetch` addition. For more information and advanced usage, refer to the [React Router docs][rr-link].
+This state is inaccessible on the server as it is implemented on top of [`history.state`](https://developer.mozilla.org/en-US/docs/Web/API/History/state).
 
 [rr-link]: https://reactrouter.com/en/main/components/link