From 793531210d0ef0635ac076d9aee1d31d3ee82655 Mon Sep 17 00:00:00 2001
From: Ryan Florence <rpflorence@gmail.com>
Date: Wed, 8 Mar 2023 08:04:15 -0700
Subject: [PATCH] docs: updated NavLink docs

---
 docs/components/nav-link.md | 154 ++++++++++++++++++++++++------------
 1 file changed, 104 insertions(+), 50 deletions(-)

diff --git a/docs/components/nav-link.md b/docs/components/nav-link.md
index 4b01edc80ab..24fa75e3d8a 100644
--- a/docs/components/nav-link.md
+++ b/docs/components/nav-link.md
@@ -5,66 +5,120 @@ toc: false
 
 # `<NavLink>`
 
-A `<NavLink>` is a special kind of `<Link>` that knows whether or not it is "active". This is useful when building a navigation menu, such as a breadcrumb or a set of tabs where you'd like to show which of them is currently selected. It also provides useful context for assistive technology like screen readers.
-
-By default, an `active` class is added to a `<NavLink>` component when it is active. You can pass a function as children to customize the content of the `<NavLink>` component based on their active state, specially useful to change styles on internal elements.
+A `<NavLink>` is a special kind of `<Link>` that knows whether or not it is "active" or "pending". This is useful when building a navigation menu, such as a breadcrumb or a set of tabs where you'd like to show which of them is currently selected. It also provides useful context for assistive technology like screen readers.
 
 ```tsx
 import { NavLink } from "@remix-run/react";
 
-function NavList() {
-  // This styling will be applied to a <NavLink> when the
-  // route that it links to is currently selected.
-  const activeStyle = {
-    textDecoration: "underline",
-  };
-  const activeClassName = "underline";
-  return (
-    <nav>
-      <ul>
-        <li>
-          <NavLink
-            to="messages"
-            style={({ isActive }) =>
-              isActive ? activeStyle : undefined
-            }
-          >
-            Messages
-          </NavLink>
-        </li>
-        <li>
-          <NavLink
-            to="tasks"
-            className={({ isActive }) =>
-              isActive ? activeClassName : undefined
-            }
-          >
-            Tasks
-          </NavLink>
-        </li>
-        <li>
-          <NavLink to="tasks">
-            {({ isActive }) => (
-              <span
-                className={
-                  isActive ? activeClassName : undefined
-                }
-              >
-                Tasks
-              </span>
-            )}
-          </NavLink>
-        </li>
-      </ul>
-    </nav>
-  );
+<NavLink
+  to="/messages"
+  className={({ isActive, isPending }) =>
+    isPending ? "pending" : isActive ? "active" : ""
+  }
+>
+  Messages
+</NavLink>;
+```
+
+## Default `active` class
+
+By default, an `active` class is added to a `<NavLink>` component when it is active so you can use CSS to style it.
+
+```tsx
+<nav id="sidebar">
+  <NavLink to="/messages" />
+</nav>
+```
+
+```css
+#sidebar a.active {
+  color: red;
 }
 ```
 
-If the `end` prop is used, it will ensure this component isn't matched as "active" when its descendant paths are matched. For example, to render a link that is only active at the website root and not any other URLs, you can use:
+## `className`
+
+The `className` prop works like a normal className, but you can also pass it a function to customize the classNames applied based on the active and pending state of the link.
+
+```tsx
+<NavLink
+  to="/messages"
+  className={({ isActive, isPending }) =>
+    isPending ? "pending" : isActive ? "active" : ""
+  }
+>
+  Messages
+</NavLink>
+```
+
+## `style`
+
+The `style` prop works like a normal style prop, but you can also pass it a function to customize the styles applied based on the active and pending state of the link.
+
+```tsx
+<NavLink
+  to="/messages"
+  style={({ isActive, isPending }) => {
+    return {
+      fontWeight: isActive ? "bold" : "",
+      color: isPending ? "red" : "black",
+    };
+  }}
+>
+  Messages
+</NavLink>
+```
+
+## `children`
+
+You can pass a render prop as children to customize the content of the `<NavLink>` based on the active and pending state, which is useful to change styles on internal elements.
+
+```tsx
+<NavLink to="/tasks">
+  {({ isActive, isPending }) => (
+    <span className={isActive ? "active" : ""}>Tasks</span>
+  )}
+</NavLink>
+```
+
+## `end`
+
+The `end` prop changes the matching logic for the `active` and `pending` states to only match to the "end" of the NavLinks's `to` path. If the URL is longer than `to`, it will no longer be considered active.
+
+Without the end prop, this link is always active because every URL matches `/`.
+
+```tsx
+<NavLink to="/">Home</NavLink>
+```
+
+To match the URL "to the end" of `to`, use `end`:
 
 ```tsx
 <NavLink to="/" end>
   Home
 </NavLink>
 ```
+
+Now this link will only be active at `"/"`. This works for paths with more segments as well:
+
+| Link                          | URL          | isActive |
+| ----------------------------- | ------------ | -------- |
+| `<NavLink to="/tasks" />`     | `/tasks`     | true     |
+| `<NavLink to="/tasks" />`     | `/tasks/123` | true     |
+| `<NavLink to="/tasks" end />` | `/tasks`     | true     |
+| `<NavLink to="/tasks" end />` | `/tasks/123` | false    |
+
+## `caseSensitive`
+
+Adding the `caseSensitive` prop changes the matching logic to make it case sensitive.
+
+| Link                                         | URL           | isActive |
+| -------------------------------------------- | ------------- | -------- |
+| `<NavLink to="/SpOnGe-bOB" />`               | `/sponge-bob` | true     |
+| `<NavLink to="/SpOnGe-bOB" caseSensitive />` | `/sponge-bob` | false    |
+
+## `aria-current`
+
+When a `NavLink` is active it will automatically apply `<a aria-current="page">` to the underlying anchor tag. See [aria-current][aria-current] on MDN.
+
+[aria-current]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current