From bd82da25ab52f7e3ae740dc08cdc5a003faf22cc Mon Sep 17 00:00:00 2001
From: Tobbe Lundberg <tobbe@tlundberg.com>
Date: Mon, 15 Apr 2024 16:06:09 +0200
Subject: [PATCH] docs(router): Document new NavLink className replacement
 behavior (#10401)

---
 docs/docs/router.md | 34 +++++++++++++++++++++++-----------
 1 file changed, 23 insertions(+), 11 deletions(-)

diff --git a/docs/docs/router.md b/docs/docs/router.md
index 7d1e9a715032..0cea8e101879 100644
--- a/docs/docs/router.md
+++ b/docs/docs/router.md
@@ -218,26 +218,34 @@ Named route functions simply return a string, so you can still pass in hardcoded
 
 ## Active links
 
-`NavLink` is a special version of `Link` that will add an `activeClassName` to the rendered element when it matches the current URL.
+`NavLink` is a special version of `Link` that will switch to the
+`activeClassName` classes for the rendered element when it matches the current
+URL.
 
 ```jsx title="MainMenu.jsx"
 import { NavLink, routes } from '@redwoodjs/router'
 
-// Will render <a className="link activeLink" {...rest}> respectively when on the page
 const MainMenu = () =>
   <ul>
     <li>
-      <!-- Adds "activeLink" when the URL matches "/" -->
+      <!--
+        Normally renders as `<a className="link homeLink" ...>`, but when the
+        URL matches "/" it'll switch to render
+        `<a className="activeLink homeLink" ...>`
+      -->
       <NavLink
-        className="link"
-        activeClassName="activeLink"
+        className="link homeLink"
+        activeClassName="activeLink homeLink"
         to={routes.home()}>
         Home
       </NavLink>
     </li>
     <li>
-      <!-- Adds "activeLink" when the URL matches "/?tab=tutorial" -->
-      <!-- (params order insensitive) -->
+      <!--
+        Normally renders as `<a className="link" ...>`, but when the URL
+        matches "/?tab=tutorial" (params order insensitive) it'll switch to
+        render `<a className="activeLink" ...>`
+      -->
       <NavLink
         className="link"
         activeClassName="activeLink"
@@ -248,12 +256,14 @@ const MainMenu = () =>
   </ul>
 ```
 
-The `activeMatchParams` prop can be used to control how query params are matched:
+The `activeMatchParams` prop can be used to control how query params are
+matched:
 
 ```jsx
 import { NavLink, routes } from '@redwoodjs/router'
 
-// Will render <a href="/?tab=tutorial&page=2" className="link activeLink"> when on any Home tutorial page
+// Will render <a href="/?tab=tutorial&page=2" className="activeLink"> when on
+// any Home tutorial page
 const MainMenu = () => (
   <li>
     <NavLink
@@ -268,9 +278,11 @@ const MainMenu = () => (
 )
 ```
 
-> Note `activeMatchParams` is an array of `string` _(key only)_ or `Record<string, any>` _(key and value)_
+> Note `activeMatchParams` is an array of `string` _(key only)_ or
+> `Record<string, any>` _(key and value)_
 
-More granular match; needs to be on the tutorial tab (`tab=tutorial`) and have the `page` key specified:
+More granular match; needs to be on the tutorial tab (`tab=tutorial`) and have
+the `page` key specified:
 
 ```jsx
 // Match /?tab=tutorial&page=*