NavLink: replace activeClassName + activeStyle props (#7985)

Author: chaance

docs/advanced-guides/migrating-5-to-6.md

@@ -27,20 +27,22 @@ In general, the process looks like this:
   - Use `<Route children>` everywhere
   - Use hooks instead of `withRouter` and "floating" `<Route>`s (that aren't
     part of a `<Switch>`)
-- [Upgrade to React Router v6](#upgrade-to-react-router-v6)
-  - [Upgrade all `<Switch>` elements to `<Routes>`](#upgrade-all-switch-elements-to-routes)
-    - Update `<Link to>` values
-    - Update `<Route path>` patterns
-    - Remove `<Route exact>` and `<Route strict>` props
-    - Move `<Route sensitive>` to containing `<Routes caseSensitive>`
-    - Consolidate your `<Route>`s into a nested config (optional)
-  - [Use `navigate` instead of `history`](#use-navigate-instead-of-history)
-    - Use `useNavigate` hook instead of `useHistory`
-    - Use `<Navigate>` instead of `<Redirect>`
-  - [Use `useRoutes` instead of `react-router-config`](#use-useroutes-instead-of-react-router-config)
+- [Migrating React Router v5 to v6](#migrating-react-router-v5-to-v6)
+  - [Upgrade to React v16.8](#upgrade-to-react-v168)
+  - [Upgrade to React Router v5.1](#upgrade-to-react-router-v51)
+  - [Upgrade to React Router v6](#upgrade-to-react-router-v6)
+    - [Upgrade all `<Switch>` elements to `<Routes>`](#upgrade-all-switch-elements-to-routes)
+    - [Relative Routes and Links](#relative-routes-and-links)
+    - [Advantages of `<Route element>`](#advantages-of-route-element)
+    - [Note on `<Route path>` patterns](#note-on-route-path-patterns)
+    - [Note on `<Link to>` values](#note-on-link-to-values)
+  - [Use useRoutes instead of react-router-config](#use-useroutes-instead-of-react-router-config)
+  - [Use navigate instead of history](#use-navigate-instead-of-history)
   - [Rename `<Link component>` to `<Link as>` and `<NavLink exact>` to `<NavLink end>`](#rename-link-component-to-link-as-and-navlink-exact-to-navlink-end)
+  - [Remove `activeClassName` and `activeStyle` props from `<NavLink />`](#remove-activeclassname-and-activestyle-props-from-navlink-)
   - [Get `StaticRouter` from `react-router-dom/server`](#get-staticrouter-from-react-router-domserver)
   - [Move `basename` from `<Router>` to `<Routes>`](#move-basename-from-router-to-routes)
+  - [What did we miss?](#what-did-we-miss)
 
 ## Upgrade to React v16.8
 
@@ -708,6 +710,59 @@ function SomeForm() {
 This is a simple renaming of a prop to better align with the common practice of
 other libraries in the React ecosystem including styled-components and Reach UI.
 
+## Remove `activeClassName` and `activeStyle` props from `<NavLink />`
+
+As of `v6.0.0-beta.3`, the `activeClassName` and `activeStyle` props have been removed from `NavLinkProps`. Instead, you can pass a function to either `style` or `className` that will allow you to customize the inline styling or the class string based on the component's active state.
+
+```diff tsx
+<NavLink
+  to="/messages"
+- style={{ color: 'blue' }}
+- activeStyle={{ color: 'green' }}
++ style={isActive => ({ color: isActive ? 'green' : 'blue })}
+>
+  Messages
+</NavLink>
+```
+
+```diff tsx
+<NavLink
+  to="/messages"
+- className="nav-link"
+- activeClassName="activated"
++ className={isActive => "nav-link" + (isActive ? " activated" : "")}
+>
+  Messages
+</NavLink>
+```
+
+If you prefer to keep the v5 props, you can create your own `<NavLink />` as a wrapper component for a smoother upgrade path.
+
+```tsx
+import React from "react";
+import { NavLink as BaseNavLink } from "react-router-dom";
+
+const NavLink = React.forwardRef(
+  ({ activeClassName, activeStyle, ...props }, ref) => {
+    return (
+      <BaseNavLink
+        ref={ref}
+        {...props}
+        className={isActive =>
+          [props.className, isActive ? activeClassName : null]
+            .filter(Boolean)
+            .join(" ")
+        }
+        style={isActive => ({
+          ...props.style,
+          ...(isActive ? activeStyle : null)
+        })}
+      />
+    );
+  }
+);
+```
+
 ## Get `StaticRouter` from `react-router-dom/server`
 
 The `StaticRouter` component has moved into a new bundle:

docs/api-reference.md

@@ -341,19 +341,19 @@ TODO: example
 ```tsx
 declare function NavLink(props: NavLinkProps): React.ReactElement;
 
-interface NavLinkProps extends LinkProps {
-  activeClassName?: string;
-  activeStyle?: object;
+interface NavLinkProps extends Omit<LinkProps, "className" | "style"> {
   caseSensitive?: boolean;
+  className?: string | ((isActive: boolean) => string);
   end?: boolean;
+  style?: React.CSSProperties | ((isActive: boolean) => React.CSSProperties);
 }
 ```
 
 </details>
 
-A `<NavLink>` is a special kind of [`<Link>`](#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.
+A `<NavLink>` is a special kind of [`<Link>`](#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 assitive technology like screen readers.
 
-Both `<NavLink activeClassName>` and/or `<NavLink activeStyle>` are applied to the underlying `<Link>` when the route it links to is currently active.
+By default, an `active` class is added to a `<NavLink>` component when it is active. This provides the same simple styling mechanism for most users who are upgrading from v5. One difference as of `v6.0.0-beta.3` is that `activeClassName` and `activeStyle` have been removed from `NavLinkProps`. Instead, you can pass a function to either `style` or `className` that will allow you to customize the inline styling or the class string based on the component's active state.
 
 ```tsx
 import React from "react";
@@ -370,12 +370,18 @@ function NavList() {
     <nav>
       <ul>
         <li>
-          <NavLink to="messages" activeStyle={activeStyle}>
+          <NavLink
+            to="messages"
+            style={isActive => (isActive ? activeStyle : undefined)}
+          >
             Messages
           </NavLink>
         </li>
         <li>
-          <NavLink to="tasks" activeStyle={activeStyle}>
+          <NavLink
+            to="tasks"
+            style={isActive => (isActive ? activeStyle : undefined)}
+          >
             Tasks
           </NavLink>
         </li>
@@ -385,9 +391,36 @@ function NavList() {
 }
 ```
 
-If the `end` prop is used, it will ensure this component isn't matched as "active" when its descendant paths are matched:
+If you prefer the v5 API, you can create your own `<NavLink />` as a wrapper component:
+
+```tsx
+import React from "react";
+import { NavLink as BaseNavLink } from "react-router-dom";
 
+const NavLink = React.forwardRef(
+  ({ activeClassName, activeStyle, ...props }, ref) => {
+    return (
+      <BaseNavLink
+        ref={ref}
+        {...props}
+        className={isActive =>
+          [props.className, isActive ? activeClassName : null]
+            .filter(Boolean)
+            .join(" ")
+        }
+        style={isActive => ({
+          ...props.style,
+          ...(isActive ? activeStyle : null)
+        })}
+      />
+    );
+  }
+);
 ```
+
+If the `end` prop is used, it will ensure this component isn't matched as "active" when its descendant paths are matched:
+
+```tsx
 <NavLink to="/" end>Home</NavLink>
 ```