diff --git a/docs/upgrading/v5.md b/docs/upgrading/v5.md index 7d84bd3f65..cb7bea6d14 100644 --- a/docs/upgrading/v5.md +++ b/docs/upgrading/v5.md @@ -15,20 +15,11 @@ Until then, we hope this guide will help you do the upgrade all at once! ## Introduction -React Router version 6 introduces several powerful new features, as well as -improved compatibility with the latest versions of React. It also introduces a -few breaking changes from version 5. This document is a comprehensive guide on -how to upgrade your v4/5 app to v6 while hopefully being able to ship as often -as possible as you go. +React Router version 6 introduces several powerful new features, as well as improved compatibility with the latest versions of React. It also introduces a few breaking changes from version 5. This document is a comprehensive guide on how to upgrade your v4/5 app to v6 while hopefully being able to ship as often as possible as you go. -If you are just getting started with React Router or you'd like to try out v6 in -a new app, please see [the Getting Started guide](../getting-started/installation.md). +If you are just getting started with React Router or you'd like to try out v6 in a new app, please see [the Getting Started guide](../getting-started/installation.md). -The examples in this guide will show code samples of how you might have built -something in a v5 app, followed by how you would accomplish the same thing in -v6. There will also be an explanation of why we made this change and how it's -going to improve both your code and the overall user experience of people who -are using your app. +The examples in this guide will show code samples of how you might have built something in a v5 app, followed by how you would accomplish the same thing in v6. There will also be an explanation of why we made this change and how it's going to improve both your code and the overall user experience of people who are using your app. In general, the process looks like this: @@ -36,26 +27,17 @@ In general, the process looks like this: 2. [Upgrade to React Router v5.1](#upgrade-to-react-router-v51) 3. [Upgrade to React Router v6](#upgrade-to-react-router-v6) -The following is a detailed breakdown of each step that should help you migrate -quickly and with confidence to v6. +The following is a detailed breakdown of each step that should help you migrate quickly and with confidence to v6. ## Upgrade to React v16.8 -React Router v6 makes heavy use of [React -hooks](https://reactjs.org/docs/hooks-intro.html), so you'll need to be on React -16.8 or greater before attempting the upgrade to React Router v6. The good news -is that React Router v5 is compatible with React >= 15, so if you're on v5 (or -v4) you should be able to upgrade React without touching any of your router -code. +React Router v6 makes heavy use of [React hooks](https://reactjs.org/docs/hooks-intro.html), so you'll need to be on React 16.8 or greater before attempting the upgrade to React Router v6. The good news is that React Router v5 is compatible with React >= 15, so if you're on v5 (or v4) you should be able to upgrade React without touching any of your router code. -Once you've upgraded to React 16.8, **you should deploy your app**. Then you can -come back later and pick up where you left off. +Once you've upgraded to React 16.8, **you should deploy your app**. Then you can come back later and pick up where you left off. ## Upgrade to React Router v5.1 -It will be easier to make the switch to React Router v6 if you upgrade to v5.1 -first. In v5.1, we released an enhancement to the handling of `` -elements that will help smooth the transition to v6. Instead of using `` and `` props, just use regular element `` everywhere and use hooks to access the router's internal state. +It will be easier to make the switch to React Router v6 if you upgrade to v5.1 first. In v5.1, we released an enhancement to the handling of `` elements that will help smooth the transition to v6. Instead of using `` and `` props, just use regular element `` everywhere and use hooks to access the router's internal state. ```js // v4 and v5 before 5.1 @@ -100,23 +82,14 @@ function App() { } ``` -You can read more about v5.1's hooks API and the rationale behind the move to -regular elements [on our blog](https://reacttraining.com/blog/react-router-v5-1/). +You can read more about v5.1's hooks API and the rationale behind the move to regular elements [on our blog](https://reacttraining.com/blog/react-router-v5-1/). -In general, React Router v5.1 (and v6) favors elements over components (or -"element types"). There are a few reasons for this, but we'll discuss more -further down when we discuss v6's `` API. +In general, React Router v5.1 (and v6) favors elements over components (or "element types"). There are a few reasons for this, but we'll discuss more further down when we discuss v6's `` API. -When you use regular React elements you get to pass the props -explicitly. This helps with code readability and maintenance over time. If you -were using `` to get a hold of the params, you can just +When you use regular React elements you get to pass the props explicitly. This helps with code readability and maintenance over time. If you were using `` to get a hold of the params, you can just `useParams` inside your route component instead. -Along with the upgrade to v5.1, you should replace any usage of `withRouter` -with hooks. You should also get rid of any "floating" `` elements that -are not inside a ``. Again, [the blog post about -v5.1](https://reacttraining.com/blog/react-router-v5-1/) explains how to do this -in greater detail. +Along with the upgrade to v5.1, you should replace any usage of `withRouter` with hooks. You should also get rid of any "floating" `` elements that are not inside a ``. Again, [the blog post about v5.1](https://reacttraining.com/blog/react-router-v5-1/) explains how to do this in greater detail. In summary, to upgrade from v4/5 to v5.1, you should: @@ -128,27 +101,23 @@ In summary, to upgrade from v4/5 to v5.1, you should: - Replace any ``s that are not inside a `` with `useRouteMatch`, or wrap them in a `` -Again, **once your app is upgraded to v5.1 you should test and deploy it**, and -pick this guide back up when you're ready to continue. +Again, **once your app is upgraded to v5.1 you should test and deploy it**, and pick this guide back up when you're ready to continue. ## Upgrade to React Router v6 -**Heads up:** This is the biggest step in the migration and will probably take -the most time and effort. +**Heads up:** This is the biggest step in the migration and will probably take the most time and effort. -For this step, you'll need to install React Router v6 and the history library, -which is now a peer dependency. If you're managing dependencies via npm: +For this step, you'll need to install React Router v6. If you're managing dependencies via npm: ```bash -$ npm install react-router@next react-router-dom@next history +$ npm install react-router-dom@next # or, for a React Native app -$ npm install react-router@next react-router-native@next history +$ npm install react-router-native@next ``` ### Upgrade all `` elements to `` -React Router v6 introduces a `Routes` component that is kind of like `Switch`, -but a lot more powerful. The main advantages of `Routes` over `Switch` are: +React Router v6 introduces a `Routes` component that is kind of like `Switch`, but a lot more powerful. The main advantages of `Routes` over `Switch` are: - All ``s and ``s inside a `` are relative. This leads to leaner and more predictable code in `` and `` @@ -160,18 +129,13 @@ but a lot more powerful. The main advantages of `Routes` over `Switch` are: routes at once. In large apps, you can still nest routes in bundles that you load dynamically via `React.lazy` -In order to use v6, you'll need to convert all your `` elements to -``. If you already made the upgrade to v5.1, you're halfway there. +In order to use v6, you'll need to convert all your `` elements to ``. If you already made the upgrade to v5.1, you're halfway there. First, let's talk about relative routes and links in v6. ### Relative Routes and Links -In v5, you had to be very explicit about how you wanted to nest your routes and -links. In both cases, if you wanted nested routes and links you had to build the -`` and `` props from the parent route's `match.url` and -`match.path` properties. Additionally, if you wanted to nest routes, you had to -put them in the child route's component. +In v5, you had to be very explicit about how you wanted to nest your routes and links. In both cases, if you wanted nested routes and links you had to build the `` and `` props from the parent route's `match.url` and `match.path` properties. Additionally, if you wanted to nest routes, you had to put them in the child route's component. ```js // This is a React Router v5 app @@ -273,29 +237,17 @@ A few important things to notice about v6 in this example: automatically detect the best route for the current URL. This prevents bugs due to manually putting routes in the wrong order in a `` -You may have also noticed that all `` from the v5 app changed to -`` in v6. Assuming you followed the upgrade steps to v5.1, this -should be as simple as moving your route element from the child position to a -named `element` prop. +You may have also noticed that all `` from the v5 app changed to `` in v6. Assuming you followed the upgrade steps to v5.1, this should be as simple as moving your route element from the child position to a named `element` prop. ### Advantages of `` -In the section about upgrading to v5.1, we promised that we'd discuss the -advantages of using regular elements instead of components (or element types) -for rendering. Let's take a quick break from upgrading and talk about that now. +In the section about upgrading to v5.1, we promised that we'd discuss the advantages of using regular elements instead of components (or element types) for rendering. Let's take a quick break from upgrading and talk about that now. -For starters, we see React itself taking the lead here with the `}>` API. The `fallback` prop takes a React element, not a -component. This lets you easily pass whatever props you want to your `` -from the component that renders it. +For starters, we see React itself taking the lead here with the `}>` API. The `fallback` prop takes a React element, not a component. This lets you easily pass whatever props you want to your `` from the component that renders it. -Using elements instead of components means we don't have to provide a -`passProps`-style API so you can get the props you need to your elements. For -example, in a component-based API there is no good way to pass props to the -`` element that is rendered when `` matches. Most React libraries who take this approach end -up with either an API like `` or use a render prop or higher-order component. +Using elements instead of components means we don't have to provide a `passProps`-style API so you can get the props you need to your elements. For example, in a component-based API there is no good way to pass props to the `` element that is rendered when `` matches. Most React libraries who take this approach end up with either an API like `` or use a render prop or higher-order component. -Also, in case you didn't notice, in v4 and v5 `Route`'s rendering API became -rather large. It went something like this: +Also, in case you didn't notice, in v4 and v5 `Route`'s rendering API became rather large. It went something like this: ```js // Ah, this is nice and simple! @@ -337,11 +289,7 @@ export default withRouter(DeepComponent); // ... *facepalm* ``` -At least part of the reason for this API sprawl was that React did not provide -any way for us to get the information from the `` to your route element, -so we had to invent clever ways to get both the route data **and** your own -custom props through to your elements: `component`, render props, `passProps` -higher-order-components ... until **hooks** came along! +At least part of the reason for this API sprawl was that React did not provide any way for us to get the information from the `` to your route element, so we had to invent clever ways to get both the route data **and** your own custom props through to your elements: `component`, render props, `passProps` higher-order-components ... until **hooks** came along! Now, the conversation above goes like this: @@ -370,11 +318,7 @@ function DeepComponent() { // Aaaaaaaaand we're done here. ``` -Another important reason for using the `element` prop in v6 is that -`` is reserved for nesting routes. This is one of people's -favorite features from v3 and `@reach/router`, and we're bringing it back in -v6. Taking the code in the previous example one step further, we can hoist all -`` elements into a single route config: +Another important reason for using the `element` prop in v6 is that `` is reserved for nesting routes. This is one of people's favorite features from v3 and `@reach/router`, and we're bringing it back in v6. Taking the code in the previous example one step further, we can hoist all `` elements into a single route config: ```js // This is a React Router v6 app @@ -413,28 +357,17 @@ function Users() { } ``` -This step is optional of course, but it's really nice for small to medium sized -apps that don't have thousands of routes. +This step is optional of course, but it's really nice for small to medium sized apps that don't have thousands of routes. -Notice how `` elements nest naturally inside a `` element. Nested -routes build their path by adding to the parent route's path. We didn't need a -trailing `*` on `` this time because when the routes are -defined in one spot the router is able to see all your nested routes. +Notice how `` elements nest naturally inside a `` element. Nested routes build their path by adding to the parent route's path. We didn't need a trailing `*` on `` this time because when the routes are defined in one spot the router is able to see all your nested routes. -You'll only need the trailing `*` when there is another `` somewhere in -that route's descendant tree. In that case, the descendant `` will match -on the portion of the pathname that remains (see the previous example for what -this looks like in practice). +You'll only need the trailing `*` when there is another `` somewhere in that route's descendant tree. In that case, the descendant `` will match on the portion of the pathname that remains (see the previous example for what this looks like in practice). -When using a nested config, routes with `children` should render an `` -in order to render their child routes. This makes it easy to render layouts with -nested UI. +When using a nested config, routes with `children` should render an `` in order to render their child routes. This makes it easy to render layouts with nested UI. ### Note on `` patterns -React Router v6 uses a simplified path format. `` in v6 supports -only 2 kinds of placeholders: dynamic `:id`-style params and `*` wildcards. A -`*` wildcard may be used only at the end of a path, not in the middle. +React Router v6 uses a simplified path format. `` in v6 supports only 2 kinds of placeholders: dynamic `:id`-style params and `*` wildcards. A `*` wildcard may be used only at the end of a path, not in the middle. All of the following are valid route paths in v6: @@ -445,7 +378,6 @@ All of the following are valid route paths in v6: /users/:id/messages /files/* /files/:id/* -/files-* ``` The following RegExp-style route paths are **not valid** in v6: @@ -454,51 +386,26 @@ The following RegExp-style route paths are **not valid** in v6: /users/:id? /tweets/:id(\d+) /files/*/cat.jpg +/files-* ``` -We added the dependency on path-to-regexp in v4 to enable more advanced pattern -matching. In v6 we are using a simpler syntax that allows us to predictably -parse the path for ranking purposes. It also means we can stop depending on -path-to-regexp, which is nice for bundle size. - -If you were using any of path-to-regexp's more advanced syntax, you'll have to -remove it and simplify your route paths. If you were using the RegExp syntax to -do URL param validation (e.g. to ensure an id is all numeric characters) please -know that we plan to add some more advanced param validation in v6 at some -point. For now, you'll need to move that logic to the component the route -renders, and let it branch it's rendered tree after you parse the params. - -If you were using `` you should move it to its containing -`` prop. Either all routes in a `` element are -case-sensitive or they are not. - -One other thing to notice is that all path matching in v6 ignores the trailing -slash on the URL. In fact, `` has been removed and has no effect -in v6. **This does not mean that you can't use trailing slashes if you need -to.** Your app can decide to use trailing slashes or not, you just can't -render two different UIs _client-side_ at `` and -``. You can still render two different UIs at those URLs, -but you'll have to do it server-side. +We added the dependency on path-to-regexp in v4 to enable more advanced pattern matching. In v6 we are using a simpler syntax that allows us to predictably parse the path for ranking purposes. It also means we can stop depending on path-to-regexp, which is nice for bundle size. + +If you were using any of path-to-regexp's more advanced syntax, you'll have to remove it and simplify your route paths. If you were using the RegExp syntax to do URL param validation (e.g. to ensure an id is all numeric characters) please know that we plan to add some more advanced param validation in v6 at some point. For now, you'll need to move that logic to the component the route renders, and let it branch it's rendered tree after you parse the params. + +If you were using `` you should move it to its containing `` prop. Either all routes in a `` element are case-sensitive or they are not. + +One other thing to notice is that all path matching in v6 ignores the trailing slash on the URL. In fact, `` has been removed and has no effect in v6. **This does not mean that you can't use trailing slashes if you need to.** Your app can decide to use trailing slashes or not, you just can't render two different UIs _client-side_ at `` and ``. You can still render two different UIs at those URLs (though we wouldn't recommend it), but you'll have to do it server-side. ### Note on `` values -In v5, a `` value that does not begin with `/` was ambiguous; it -depends on what the current URL is. For example, if the current URL is -`/users`, a v5 `` would render a ``. However, if -the current URL has a trailing slash, like `/users/`, the same `` -would render ``. This makes it difficult to predict how -links will behave, so in v5 we recommended that you build links from the root -URL (using `match.url`) and not use relative `` values. +In v5, a `` value that does not begin with `/` was ambiguous; it depends on what the current URL is. For example, if the current URL is `/users`, a v5 `` would render a ``. However, if the current URL has a trailing slash, like `/users/`, the same `` would render ``. This makes it difficult to predict how links will behave, so in v5 we recommended that you build links from the root URL (using `match.url`) and not use relative `` values. -React Router v6 fixes this ambiguity. In v6, a `` will always -render the same ``, regardless of the current URL. +React Router v6 fixes this ambiguity. In v6, a `` will always render the same ``, regardless of the current URL. -For example, a `` that is rendered inside a `` -will always render a link to `/users/me`, regardless of whether or not the -current URL has a trailing slash. +For example, a `` that is rendered inside a `` will always render a link to `/users/me`, regardless of whether or not the current URL has a trailing slash. -When you'd like to link back "up" to parent routes, use a leading `..` segment -in your `` value, similar to what you'd do in a ``. +When you'd like to link back "up" to parent routes, use a leading `..` segment in your `` value, similar to what you'd do in a ``. ```tsx function App() { @@ -553,8 +460,7 @@ function UserProfile() { } ``` -It may help to think about the current URL as if it were a directory path on the -filesystem and `` like the `cd` command line utility. +It may help to think about the current URL as if it were a directory path on the filesystem and `` like the `cd` command line utility. ``` // If your routes look like this @@ -578,21 +484,9 @@ cd ../../stats # pwd is /stats cd ../../../stats # pwd is /stats ``` -**Note**: The decision to ignore trailing slashes while matching and creating -relative paths was not taken lightly by our team. We consulted with a number of -our friends and clients (who are also our friends!) about it. We found that most -of us don't even understand how plain HTML relative links are handled with the -trailing slash. Most people guessed it worked like `cd` on the command line (it -does not). Also, HTML relative links don't have the concept of nested routes, -they only worked on the URL, so we had to blaze our own trail here a bit. -`@reach/router` set this precendent and it has worked out well for a couple of -years. - -In addition to ignoring trailing slashes in the current URL, it is important to -note that `` will not always behave like `` when your -`` matches more than one segment of the URL. Instead of removing -just one segment of the URL, **it will resolve based upon the parent route's -path, essentially removing all path segments specified by that route**. +**Note**: The decision to ignore trailing slashes while matching and creating relative paths was not taken lightly by our team. We consulted with a number of our friends and clients (who are also our friends!) about it. We found that most of us don't even understand how plain HTML relative links are handled with the trailing slash. Most people guessed it worked like `cd` on the command line (it does not). Also, HTML relative links don't have the concept of nested routes, they only worked on the URL, so we had to blaze our own trail here a bit. `@reach/router` set this precendent and it has worked out well for a couple of years. + +In addition to ignoring trailing slashes in the current URL, it is important to note that `` will not always behave like `` when your `` matches more than one segment of the URL. Instead of removing just one segment of the URL, **it will resolve based upon the parent route's path, essentially removing all path segments specified by that route**. ```tsx function App() { @@ -612,11 +506,7 @@ function App() { } ``` -This may seem like an odd choice, to make `..` operate on routes instead of URL -segments, but it's a **huge** help when working with `*` routes where an -indeterminate number of segments may be matched by the `*`. In these scenarios, -a single `..` segment in your `` value can essentially remove anything -matched by the `*`, which lets you create more predictable links in `*` routes. +This may seem like an odd choice, to make `..` operate on routes instead of URL segments, but it's a **huge** help when working with `*` routes where an indeterminate number of segments may be matched by the `*`. In these scenarios, a single `..` segment in your `` value can essentially remove anything matched by the `*`, which lets you create more predictable links in `*` routes. ```tsx function App() { @@ -640,9 +530,7 @@ function App() { ## Use `useRoutes` instead of `react-router-config` -All of the functionality from v5's `react-router-config` package has moved into -core in v6. If you prefer/need to define your routes as JavaScript objects -instead of using React elements, you're going to love this. +All of the functionality from v5's `react-router-config` package has moved into core in v6. If you prefer/need to define your routes as JavaScript objects instead of using React elements, you're going to love this. ```js function App() { @@ -670,22 +558,15 @@ function App() { } ``` -Routes defined in this way follow all of the same semantics as ``. In -fact, `` is really just a wrapper around `useRoutes`. +Routes defined in this way follow all of the same semantics as ``. In fact, `` is really just a wrapper around `useRoutes`. -We encourage you to give both `` and `useRoutes` a shot and decide for -yourself which one you prefer to use. Honestly, we like and use them both. +We encourage you to give both `` and `useRoutes` a shot and decide for yourself which one you prefer to use. Honestly, we like and use them both. -If you had cooked up some of your own logic around data fetching and rendering -server-side, we have a low-level `matchRoutes` function available as well -similar to the one we had in react-router-config. +If you had cooked up some of your own logic around data fetching and rendering server-side, we have a low-level `matchRoutes` function available as well similar to the one we had in react-router-config. ## Use `useNavigate` instead of `history` -React Router v6 introduces a new navigation API that is synonymous with `` -and provides better compatibility with suspense-enabled apps. We include both -imperative and declarative versions of this API depending on your style and -needs. +React Router v6 introduces a new navigation API that is synonymous with `` and provides better compatibility with suspense-enabled apps. We include both imperative and declarative versions of this API depending on your style and needs. ```js // This is a React Router v5 app @@ -704,9 +585,7 @@ function App() { } ``` -In v6, this app should be rewritten to use the `navigate` API. Most of the time -this means changing `useHistory` to `useNavigate` and changing the -`history.push` or `history.replace` callsite. +In v6, this app should be rewritten to use the `navigate` API. Most of the time this means changing `useHistory` to `useNavigate` and changing the `history.push` or `history.replace` callsite. ```js // This is a React Router v6 app @@ -725,13 +604,9 @@ function App() { } ``` -If you need to replace the current location instead of push a new one onto the -history stack, use `navigate(to, { replace: true })`. If you need state, use -`navigate(to, { state })`. You can think of the first arg to `navigate` as your -`` and the other arg as the `replace` and `state` props. +If you need to replace the current location instead of push a new one onto the history stack, use `navigate(to, { replace: true })`. If you need state, use `navigate(to, { state })`. You can think of the first arg to `navigate` as your `` and the other arg as the `replace` and `state` props. -If you prefer to use a declarative API for navigation (ala v5's `Redirect` -component), v6 provides a `Navigate` component. Use it like: +If you prefer to use a declarative API for navigation (ala v5's `Redirect` component), v6 provides a `Navigate` component. Use it like: ```js import { Navigate } from "react-router-dom"; @@ -741,10 +616,7 @@ function App() { } ``` -If you're currently using `go`, `goBack` or `goForward` from `useHistory` to -navigate backwards and forwards, you should also replace these with `navigate` -with a numerical argument indicating where to move the pointer in the history -stack. For example, here is some code using v5's `useHistory` hook: +If you're currently using `go`, `goBack` or `goForward` from `useHistory` to navigate backwards and forwards, you should also replace these with `navigate` with a numerical argument indicating where to move the pointer in the history stack. For example, here is some code using v5's `useHistory` hook: ```js // This is a React Router v5 app @@ -794,25 +666,11 @@ function App() { } ``` -Again, one of the main reasons we are moving from using the `history` API -directly to the `navigate` API is to provide better compatibility with React -suspense. React Router v6 uses the `useTransition` hook at the root of your -component hierarchy. This lets us provide a smoother experience when user -interaction needs to interrupt a pending route transition, for example when they -click a link to another route while a previously-clicked link is still loading. -The `navigate` API is aware of the internal pending transition state and will -do a REPLACE instead of a PUSH onto the history stack, so the user doesn't end -up with pages in their history that never actually loaded. - -_Note: The `` element from v5 is no longer supported as part of your -route config (inside a ``). This is due to upcoming changes in React -that make it unsafe to alter the state of the router during the initial render. -If you need to redirect immediately, you can either a) do it on your server -(probably the best solution) or b) render a `` element in your route -component. However, recognize that the navigation will happen in a `useEffect`._ - -Aside from suspense compatibility, `navigate`, like `Link`, supports relative -navigation. For example: +Again, one of the main reasons we are moving from using the `history` API directly to the `navigate` API is to provide better compatibility with React suspense. React Router v6 uses the `useTransition` hook at the root of your component hierarchy. This lets us provide a smoother experience when user interaction needs to interrupt a pending route transition, for example when they click a link to another route while a previously-clicked link is still loading. The `navigate` API is aware of the internal pending transition state and will do a REPLACE instead of a PUSH onto the history stack, so the user doesn't end up with pages in their history that never actually loaded. + +_Note: The `` element from v5 is no longer supported as part of your route config (inside a ``). This is due to upcoming changes in React that make it unsafe to alter the state of the router during the initial render. If you need to redirect immediately, you can either a) do it on your server (probably the best solution) or b) render a `` element in your route component. However, recognize that the navigation will happen in a `useEffect`._ + +Aside from suspense compatibility, `navigate`, like `Link`, supports relative navigation. For example: ```jsx // assuming we are at `/stuff` @@ -838,19 +696,11 @@ function SomeForm() { ## Remove `` `component` prop -`` no longer supports the `component` prop for overriding the returned -anchor tag. There are a few reasons for this. +`` no longer supports the `component` prop for overriding the returned anchor tag. There are a few reasons for this. -First of all, a `` should pretty much always render an ``. If yours -does not, there's a good chance your app has some serious accessibility and -usability problems, and that's no good. The browsers give us a lot of nice -usability features with `` and we want your users to get those for free! +First of all, a `` should pretty much always render an ``. If yours does not, there's a good chance your app has some serious accessibility and usability problems, and that's no good. The browsers give us a lot of nice usability features with `` and we want your users to get those for free! -That being said, maybe your app uses a CSS-in-JS library, or maybe you have a -custom, fancy link component already in your design system that you'd like to -render instead. The `component` prop may have worked well enough in a world -before hooks, but now you can create your very own accessible `Link` component -with just a few of our hooks: +That being said, maybe your app uses a CSS-in-JS library, or maybe you have a custom, fancy link component already in your design system that you'd like to render instead. The `component` prop may have worked well enough in a world before hooks, but now you can create your very own accessible `Link` component with just a few of our hooks: ```tsx import { FancyPantsLink } from "@fancy-pants/design-system"; @@ -896,14 +746,11 @@ const Link = React.forwardRef( ); ``` -If you're using `react-router-native`, we provide `useLinkPressHandler` that -works basically the same way. Just call that hook's returned function in your -`Link`'s `onPress` handler and you're all set. +If you're using `react-router-native`, we provide `useLinkPressHandler` that works basically the same way. Just call that hook's returned function in your `Link`'s `onPress` handler and you're all set. ## Rename `` to `` -This is a simple renaming of a prop to better align with the common practices of -other libraries in the React ecosystem. +This is a simple renaming of a prop to better align with the common practices of other libraries in the React ecosystem. ## Remove `activeClassName` and `activeStyle` props from `` @@ -934,7 +781,7 @@ As of `v6.0.0-beta.3`, the `activeClassName` and `activeStyle` props have been r If you prefer to keep the v5 props, you can create your own `` as a wrapper component for a smoother upgrade path. ```tsx -import React from "react"; +import * as React from "react"; import { NavLink as BaseNavLink } from "react-router-dom"; const NavLink = React.forwardRef( @@ -963,8 +810,7 @@ const NavLink = React.forwardRef( ## Get `StaticRouter` from `react-router-dom/server` -The `StaticRouter` component has moved into a new bundle: -`react-router-dom/server`. +The `StaticRouter` component has moved into a new bundle: `react-router-dom/server`. ```js // change @@ -973,32 +819,10 @@ import { StaticRouter } from "react-router-dom"; import { StaticRouter } from "react-router-dom/server"; ``` -This change was made both to follow more closely the convention established by -the `react-dom` package and to help users understand better what a -`` is for and when it should be used (on the server). - -## Move `basename` from `` to `` - -This is a simple change of moving the prop. The `basename` behavior has remained the same. It is used to indicate the base URL for all locations. - -```jsx -// change - - - -// to - - - - - -``` +This change was made both to follow more closely the convention established by the `react-dom` package and to help users understand better what a `` is for and when it should be used (on the server). ## What did we miss? -Despite our best attempts at being thorough, it's very likely that we missed -something. If you follow this upgrade guide and find that to be the case, please -let us know. We are happy to help you figure out what to do with your v5 code to -be able to upgrade and take advantage of all of the cool stuff in v6. +Despite our best attempts at being thorough, it's very likely that we missed something. If you follow this upgrade guide and find that to be the case, please let us know. We are happy to help you figure out what to do with your v5 code to be able to upgrade and take advantage of all of the cool stuff in v6. Good luck 🤘