v6.1.0

🐛 Bug fixes

• Fixed a bug that broke support for base64 encoded IDs on nested routes (#8291)

✨ Features

• <Outlet> can now receive a context prop. This value is passed to child routes and is accessible via the new useOutletContext hook. See the API docs for details. (#8461)
• <NavLink> can now receive a child function for access to its props. (#8164)

💅 Enhancements

• Improved TypeScript signature for useMatch and matchPath. For example, when you call useMatch("foo/:bar/:baz"), the path is parsed and the return type will be PathMatch<"bar" | "baz">. (#8030)
• A few error message improvements (#8202)

New Contributors

• @rwieruch made their first contribution in #8244
• @codeiotic made their first contribution in #8247
• @Sannnao made their first contribution in #8263
• @mattmazzola made their first contribution in #8255
• @ngokevin made their first contribution in #8267
• @TimisRobert made their first contribution in #8269
• @mikeldking made their first contribution in #8279
• @fishmandev made their first contribution in #8289
• @rjerue made their first contribution in #8304
• @rockingskier made their first contribution in #8314
• @arinthros made their first contribution in #8337
• @noisypigeon made their first contribution in #8361
• @elylucas made their first contribution in #8368
• @paulsmithkc made their first contribution in #8357
• @sanketshah19 made their first contribution in #8372
• @JakubDrozd made their first contribution in #8402
• @markivancho made their first contribution in #8414
• @turansky made their first contribution in #8420
• @shivamsinghchahar made their first contribution in #8423
• @petersendidit made their first contribution in #8436
• @Ajayff4 made their first contribution in #8373
• @RobHannay made their first contribution in #8455
• @kddnewton made their first contribution in #8030
• @brockross made their first contribution in #8462
• @sergiodxa made their first contribution in #8164
• @baozouai made their first contribution in #8171
• @liuhanqu made their first contribution in #8374

Full Changelog: v6.0.1...v6.1.0

v6.0.2

✨ Features

• Added the reloadDocument prop to <Link>. This allows <Link> to function like a normal anchor tag by reloading the document after navigation while maintaining the relative to resolution.

🗒️ Docs

• Fixed several issues in docblocks and the docs themselves. See the full changelog for the deets!

🤝 New Contributors

• @rwieruch made their first contribution in #8244
• @ProProgrammer2504 made their first contribution in #8247
• @Sannnao made their first contribution in #8263
• @mattmazzola made their first contribution in #8255
• @ngokevin made their first contribution in #8267
• @TimisRobert made their first contribution in #8269
• @mikeldking made their first contribution in #8279
• @fishmandev made their first contribution in #8289

Full Changelog

v6.0.1...v6.0.2

v6.0.1

🐛 Bug Fixes

• Add a default <StaticRouter location> value (#8243)
• Add invariant for using <Route> inside <Routes> to help people make the change (#8238)

v6.0.0

React Router v6 is here!

Please go read our blog post for more information on all the great stuff in v6 including notes about how to upgrade from React Router v5 and Reach Router.

v6.0.0-beta.8

Remember last week when we said

We anticipate this will be the last beta release before v6 stable next week.

Yeah, about that … 😅

We found and squashed a few high-priority bugs that needed to be addressed first. But it's coming very soon, we promise! In the mean time, here's what you'll get from our eight-est and greatest beta release:

🐛 Bug Fixes

• We fixed a few bugs in useHref that resulted in the incorrect resolved value in cases where a basename is used on the <Router /> component (See #8133 and #8142 for details).
• We also fixed a bug in our path ranking algorithm so that splat routes (routes with a * path value) are now correctly ranked ahead of layout routes.

🗒️ Docs

We've added lots of goodies to our docs and examples, and there's a lot more yet to come. Take a look and see if you find something that makes your work a little easier! We think the lazy loading and custom query parsing examples are particularly cool! 🤓

v6.0.0-beta.7

In this release we made a small but significant change to how <Link to=".."> works. This is going to help out a lot if you were trying to use links in a * route.

We have also backed out our blocking/prompt APIs for the stable v6 release. We will revisit this post 6.0 when we have a little more time to get it right.

✨ Features

The major change in this release could also be classified as a bugfix or a breaking change, depending on how you look at it. We essentialy altered the way <Link to=".."> works. See #8086 for the motivation behind this change.

You'll probably want to reread the section in the v5 => v6 migration guide about <Link to> values (it has been updated), but it basically boils down to this: any leading .. segment in a <Link to> value traverses "up" one route and builds upon that route's path instead of just removing one URL segment. This feature really completes the story of relative routes and links.

We could consider this a bugfix, since this is how it was always intended to work in the first place. Without it, you'd have a difficult time linking predictably in * routes because your <a href> would be different depending on the number of segments in the current URL.

The reason this could also be considered a breaking change is that .. now works slightly differently in <Link to> than it would in <a href>. When you have <a href=".."> it operates on the URL pathname, removing one segment of the current URL. However, since many routes really only match a single segment of the URL, there is often no difference between <Link to=".."> and <a href="..">.

💔 Breaking Changes

• We removed useBlocker(), usePrompt(), and <Prompt> for now. We will revisit these post 6.0 when we have more time to get it right. But we don't want it to block (see what I did there) the release of all the other awesome stuff we've got in v6.

🛠 Roadmap

We anticipate this will be the last beta release before v6 stable next week. Please give it a shot and let us know how it goes!

👍 Upgrading

If you're thinking about upgrading to v6, I published a few notes this past week that may help you:

• This note talks about removing <Redirect> elements from any <Switch>es you may have in your v5 app and how you can get better SEO in the process if you're currently relying on client-side redirects.
• This note talks about how to refactor your code to avoid "wrapping" <Route> elements, which won't work in v6.

Both of those posts contain steps you can take today in your v5 app without upgrading to v6.

We are also developing a backwards compat lib that should help some of you upgrade from v5 to v6. We'll post more about this when it's ready.

💻 Installing

Development for v6 has switched from dev to the main branch.

If you'd like to test it out, install from npm:

$ npm install history react-router-dom@next

v6.0.0-beta.6

No big enhancements in this release, just squashing bugs and writing lots of tests! Also, we are hard at work on cranking out examples for v6. See the end of this post for an update on our roadmap between here and v6 stable.

🧰 Examples

We have begun creating some examples for v6 that we hope will help developers make effective use of all the new features we have. So far, we have examples for the following:

• Basic Example – A basic client-side app for v6 showing how to use nested routes, layouts, links, and the new <Outlet> API
• Auth Example – Demonstrates an authentication flow including using the new useNavigate() hook, the <Navigate> element, and location.state
• Search Params Example – Demonstrates how to build a simple search form that uses the new useSearchParams() hook
• SSR Example – A server-rendered app that uses <StaticRouter> on the server and uses a <BrowserRouter> with ReactDOM.hydrate() on the client

Each example includes a button in the README that allows you to instantly launch a running instance on StackBlitz that you can play with. We hope you enjoy exploring!

🐛 Bugfixes

• Make <NavLink> match only whole URL segments instead of pieces. This means that <NavLink to="/home/users"> will still be active at /home/users, but not at /home/users2. See #7523
• Makes "layout routes" (routes with no path) never match unless one of their children do. See #8085
• Fixes a route matching regression with splat routes that was introduced in beta.5. See #8072 and #8109
• Fixes matching a nested splat route. See af7d038
• Provide all parent route params to descendant <Routes>. This reverses a decision that we made in beta.5 to remove them. See #8073

💔 Breaking Changes

• Splats in route paths (*) match only after a / in the URL. This means that <Route path="files*"> will always match as if it were <Route path="files/*">. The router will issue a warning if your route path ends with * but not /*

🛠 Roadmap

We are very close to a stable release! The last big code changes we need to make are:

• Fixing "linking up". Currently a <Link to=".."> operates on the URL pathname. However, this makes it difficult to link to the parent route when you're in a splat route. See #8086. This will be a breaking change.
• We are going to remove useBlocker() and <Prompt> in our initial v6 release, with plans to revisit them and possibly add them back at some point in the future. I still need to write up something here that explains our rationale. This will also be a breaking change.
• We are going to add some animation primitives (see #8008). The <Routes location> prop will be in v6, but it isn't ideal for animation.

💻 Installing

Development for v6 is chugging along on the dev branch.

If you'd like to test it out, install from npm:

$ npm install history react-router-dom@next

v6.0.0-beta.5

This week's release adds some much-needed polish to a few niche features of the router: splat routes (a route that uses a * path) and basenames. It also adds a renderMatches API that completes the story for those of you who may have been using react-router-config in v4 and v5.

🐛 Bugfixes

• A * in a child route path matches after a slash following its parent route path. This fixes some situations where the * was overly greedy (see #7972)
• Resolution of <Link to="."> and useResolvedPath(".") values are fixed in splat routes. Previously these resolved relative to the parent route's path. They now resolve relative to the path of the route that rendered them.

✨ Enhancements

This release makes it easier to work with apps that have multiple entry points. Using the <Router basename> prop allows React Router to be easily deployed on only a portion of a larger site by using a portion of the URL pathname (the "basename") to transparently prefix all route paths and link navigations.

For example, you can deploy one React Router app at the /inbox URL prefix, and another one at the /admin prefix. These base URLs represent two different entry points into your app, each with its own bundles. The rest of your site, including the root / URL could be rendered by something other than React Router, for example by your server framework of choice.

In the bundle for each entry point, simply initialize React Router with the basename of that entry point.

<Router basename="/inbox">
  // ...
</Router>

Then define your routes and link paths without using the /inbox URL prefix in any of them. The entire app will run relative to that prefix.

Another improvement in this release is the addition of the renderMatches API, which is the complement of matchRoutes. These APIs are both very low-level and should not normally be needed. But they are sometimes nice to use if you are doing your own data loading using the array of matches that you get back from matchRoutes.

matchRoutes and renderMatches are the equivalent of the react-router-config package we shipped in v4 and v5, just built directly into the router instead of in a separate package.

💔 Breaking Changes

• <Routes basename> has moved to <Router basename>. This prop is also available on all router variants (<BrowserRouter>, <HashRouter>, etc.).
• useLocation().pathname no longer includes the basename, if present.
• The basename argument was removed from useRoutes. This reverts the signature to useRoutes(routes, location), same as it was previous to beta.4.
• Descendant <Routes> do not get the params from their parents. This helps a set of <Routes> to be more portable by decoupling it from the params of its parents and makes it easier to know which params will be returned from useParams(). If you were relying on this behavior previously, you'll need to pass along the params manually to the elements rendered by the descendant <Routes>. See this comment for an example of how this is to be done and for a potential workaround if you really need the old behavior.
• match.pathname in a splat route now includes the portion of the pathname matched by the *. This makes the * param behave much more like other dynamic :id-style params.
• Resolution of relative <Link>s in splat routes is changed now because the entire pathname that was matched by that route is now different (see previous bullet). Instead of resolving relative to the portion of the pathname before the *, paths resolve relative to the full pathname that was matched by the route.

💻 Installing

Development for v6 is chugging along on the dev branch.

If you'd like to test it out, install from npm:

$ npm install history react-router-dom@next

v6.0.0-beta.4

Last week we released a lot of nice little bug features, but we did get a little carried away and let a little bug slip through with relative path resolution. Our bad! That nasty lil' guy is squashed in this week's beta. 🐛

And there's more! Let's dive in…

🐛 Bugfixes

• Path resolution for nested relative routes was broken in the last release and should now be fixed. Nested routes construct their pathname based on the location of their parent, not the current location. This is explained in detail under Relative Routes and Links in our advanced guides, and the issue itself in #8004

✨ Enhancements

• We made some enhancements with the Params type which is now generic, so you can add your own types if you know what to expect from functions that return query parameters. (#8019)

// before
let { valid, invalid } = useParams(); // No problems here!

let match = useMatch("profile/:userId");
let userId = match?.params.user; // wrong param, but TS doesn't know that!

// after:
let { valid, invalid } = useParams<"valid" | "key">(); // Property 'invalid' does not exist on type 'Params<"valid" | "key">'

let match = useMatch<"userId">("profile/:userId");
let userId = match?.params.user; // Property 'user' does not exist on type 'Params<"userId">'

• Absolute nested path support

There was quite a bit of discussion in #7335 from people who are using constants to define their route paths. In this style, paths are often written as absolute paths from the root / URL. These constants are then able to be used both in <Route path> definitions as well as <Link to> values. It usually looks something like this:

const USERS_PATH = "/users";
const USERS_INDEX_PATH = `${USERS_PATH}/`;
const USER_PROFILE_PATH = `${USERS_PATH}/:id`;

function UsersRoutes() {
  return (
    <Routes>
      <Route path={USERS_PATH} element={<UsersLayout />}>
        <Route path={USERS_INDEX_PATH} element={<UsersIndex />} />
        <Route path={USER_PROFILE_PATH} element={<UserProfile />} />
      </Route>
    </Routes>
  );
}

This style of use is now fully supported in v6. This is great for people who write their apps like this, but it technically could cause some breakage if you were using absolute paths (that start with /) in nested routes in previous betas. To fix this, simply remove the / from the beginning of any route paths that are meant to be relative. React Router will throw an error if you are using absolute paths that don't match their parent route paths. Hopefully this should help you find them if you are upgrading.

If you were using <Route path="/"> to indicate an index route, you can now use the new <Route index> prop to accomplish the same thing. The index prop makes it easy to scan a route config to find the index route. It also provides a guarantee that nobody will ever add children to that route.

Here's the same route config as the one above, but rewritten with relative paths and the index prop:

function UsersRoutes() {
  return (
    <Routes>
      <Route path="users" element={<UsersLayout />}>
        <Route index element={<UsersIndex />} />
        <Route path=":id" element={<UserProfile />} />
      </Route>
    </Routes>
  );
}

A lot of our work on React Router is about doing the least surprising thing for our users. Allowing absolute paths in nested routes gets us a little closer to that goal!

💔 Breaking Changes

• Removed the ability for nested route paths to begin with a / and not contain the complete path of their parent routes. This was necessary in order to introduce support for absolute paths in nested routes, described in detail above

• Removed the createRoutesFromArray utility function. You can now pass your routes directly to useRoutes or matchRoutes without passing it through createRoutesFromArray first

• Removed the PartialRouteObject type. If you were importing and using this type before, use RouteObject instead, which has been updated to make all properties optional

• The useRoutes API has changed slightly. Instead of passing a basename as the second argument, you should instead pass it as a named property in an object:

// Before
useRoutes([...routes], basename);

// After
useRoutes([...routes], { basename });

• The matchPath function now returns match.pattern instead of match.path, which is a little more descriptive about what it actually is

💻 Installing

Development for v6 is chugging along on the dev branch.

If you'd like to test it out, install from npm:

$ npm install history react-router-dom@next

v6.0.0-beta.3

Loads of goodies for you this week, as well as a few breaking changes for all of you eager beavers who are brave enough to use beta software in production! 🦫

(seriously, thank you all for helping us tighten up our APIs and fix nasty bugs)

💔 Breaking Changes!

• NavLink no longer supports the activeClassName or activeStyle props. Instead, we provide a more powerful API that allows you to pass functions to either the className or style props to conditionally apply values based on the link's active state. While a bit more verbose in some cases, this offers a nicer experience for folks who use utility class-based CSS. (#7194)

// Before
<NavLink className="link" activeClassName="active-link" />
<NavLink style={{ color: "blue" }} activeStyle={{ color: "green" }} />

// After
<NavLink
  className={({ isActive }) =>
    `link ${
      isActive
        ? "active-link"
        : // Couldn't do this before!
          "inactive-link"
    }`
  }
/>
<NavLink style={({ isActive }) => ({ color: isActive ? "green" : "blue" })} />

Note: You can always abstract over this feature in a custom NavLink if you prefer the old v5 API.

• The useRoutes API has changed slightly. Instead of passing a basename as the second argument, you should instead pass it as a named property in an object:

// Before
useRoutes([...routes], basename);

// After
useRoutes([...routes], { basename });

🐛 Bugfixes

• The basename prop on Routes is treated as case-insensitive (#7997)
• useNavigate previously used the incorrect pathname when called from parent routes when the URL matches one of its children. This fix also applies to useSearchParams (#7880)

✨ Enhancements

• Routes and useRoutes now allow you to override the location, which may be useful when building some modal interfaces and route transition animations. We are working hard to update our docs to include examples for advanced patterns where this might be useful, but in the mean time this also brings Routes closer to feature parity with v5's Switch via the location prop. (#7117)
• Provided new hooks useClickHandler and usePressHandler to make customizing Links a bit easier. (#7998)
  • Please note: with great power comes great responsibility. If you create a custom Link, be sure to render an actual HTML anchor element, otherwise your app will likely be inaccessible without a significant amount of additional work which, I assure you, you don't want to do!

💻 Installing

Development for v6 is chugging along on the dev branch.

If you'd like to test it out, install from npm:

$ npm install history react-router-dom@next

🙏 Credits

Thanks to @andrelandgraf, @dhulme, @fgatti675, @hugmanrique, @MeiKatz, @chaance and @mjackson for your contributions!