From dbc2e555de805c14699ea1296532a14e16b3465d Mon Sep 17 00:00:00 2001
From: Brian Liu <ralphbliu@gmail.com>
Date: Fri, 20 Aug 2021 07:26:45 +1000
Subject: [PATCH] Updated useMatch and NavLink doc in respect to #2683 (#3241)

Co-authored-by: Brian Liu <brian@vouchfor.com>
Co-authored-by: David Price <thedavid@thedavidprice.com>
---
 packages/router/README.md | 72 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 67 insertions(+), 5 deletions(-)

diff --git a/packages/router/README.md b/packages/router/README.md
index 3a775481f773..df4979b5af91 100644
--- a/packages/router/README.md
+++ b/packages/router/README.md
@@ -182,17 +182,67 @@ 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 add an `activeClassName` to the rendered element when it matches **exactly** the current URL.
 
-```js
+
+```jsx
 // MainMenu.js
 import { NavLink, routes } from '@redwoodjs/router'
 
-// Will render <a href="/" className="link activeLink"> when on the home page
-const MainMenu = () => <NavLink className="link" activeClassName="activeLink" to={routes.home()} >Home</NavLink>
+// Will render <a className="link activeLink" {...rest}> respectively when on the page
+const MainMenu = () =>
+  <ul>
+    <li>
+      <!-- When match "/" -->
+      <NavLink
+        className="link"
+        activeClassName="activeLink"
+        to={routes.home()}>
+        Home
+      </NavLink>
+    </li>
+    <li>
+      <!-- When match "/?tab=tutorial" (params order insensitive) -->
+      <NavLink
+        className="link"
+        activeClassName="activeLink"
+        to={routes.home({ tab: 'tutorial' })}>
+          Home > Tutorial
+      </NavLink>
+    </li>
+  </ul>
 ```
 
-You can `useMatch` to create your own component with active styles. `NavLink` uses it internally!
+Alternatively, you can add the `activeMatchParams` prop to your `NavLink` to match the current URL **partially**
+
+```jsx
+import { NavLink, routes } from '@redwoodjs/router'
+
+// Will render <a href="/?tab=tutorial&page=2" className="link activeLink"> when on any of Home tutorial pages
+const MainMenu = () =>
+  <li>
+    <NavLink
+      className="link"
+      activeClassName="activeLink"
+      activeMatchParams={[{ tab: 'tutorial' }]}
+      to={routes.home({ tab: 'tutorial', page: '2' })}>
+        Home > Tutorial
+    </NavLink>
+  </li>
+```
+
+> Note `activeMatchParams` is an array of `string` *(key only)* or `Record<string, any>` *(key and value)*
+
+More granular match, `page` key only and `tab=tutorial`
+
+```jsx
+// Match /?tab=tutorial&page=*
+activeMatchParams={[{ tab: 'tutorial' }, 'page' ]}
+```
+
+You can `useMatch` to create your own component with active styles.
+
+> `NavLink` uses it internally!
 
 ```js
 import { Link, routes, useMatch } from '@redwoodjs/router'
@@ -208,6 +258,18 @@ const MainMenu = () => {
 }
 ```
 
+`useMatch` accepts `searchParams` in the `options` for matching granularity which is exactly the same as `activeMatchParams` of `NavLink`
+
+```jsx
+import { Link, routes, useMatch } from '@redwoodjs/router'
+
+const CustomLink = ({to, ...rest}) => {
+  const matchInfo = useMatch(to, { searchParams: [{ tab: 'tutorial' }, 'page'] })
+
+  return <SomeStyledComponent as={Link} to={to} isActive={matchInfo.match} />
+}
+```
+
 ## Route parameters
 
 To match variable data in a path, you can use route parameters, which are specified by a parameter name surrounded by curly braces: