Routes

What is a route?

A React Location route is just an object. The path defines the path of the route it should match. Every property of the Route type is optional but clearly recommended for varying circumstances. Here's the simplest use-case for path matching!

1 const routes = [
2   {
3     path: 'about',
4   },
5 ]

Routes Paths

A route path can be a string (regular expression support is coming soon!), and does not require a leading or trailing slash. The following are valid paths:

• /
• /about
• about/
• about
• About

Important: Route paths are not case-sensitive by default. This means that /about and /About are considered the same path. This is a good thing, since this is the way most of the web works anyway! However, if you truly want to match a path with a different case, you can set a route's caseSensitive property to true.

Leading and trailing slashes are optional because they do not affect the hierarchy of the route structure. To build hierarchy, you can use slashes inside of your route path:

• about/me
• about/me/
• about/me/you
• about/me/you/

Or, you can use the children property to define child routes:

1 const routes = [
2   {
3     path: 'about',
4     children: [
5       {
6         path: 'me', // matches /about/me
7       },
8       {
9         path: 'you', // matches /about/you
10       },
11     ],
12   },
13 ]

The Root/Index Path vs Normal Paths

A route with a path of / is considered the root or index route, which is special because it is considered an exact match. For example:

Given a location of /teams, the / route would match:

1 const routes = [
2   {
3     path: 'teams',
4     children: [
5       {
6         path: '/', // matches /teams root/index
7       },
8     ],
9   },
10 ]

However, given a location of /teams/1234, the / would NOT match:

1 const routes = [
2   {
3     path: 'teams',
4     children: [
5       {
6         path: '/', // matches /teams root/index
7       },
8       {
9         path: ':teamId', // matches /teams/:teamId
10       },
11     ],
12   },
13 ]

All other route path types that are not root/index (/) routes are fuzzy matched. This means that if they are either an exact match OR are a prefix of the current location, they will match. For example:

1 const routes = [
2   {
3     path: 'dashboard',
4     children: [
5       {
6         path: '/', // matches /dashboard exactly
7       },
8       {
9         path: 'teams', // matches /dashboard/teams/* (notice the fuzzy match)
10       },
11       {
12         path: 'users', // matches /dashboard/users/*
13       },
14     ],
15   },
16 ]

Path Params

Path params are named wildcards that can be used to match, and extract, any part of the path that they match. They can be defined by using the : character in the path. The following are valid paths:

• :postId
• :name
• :teamId
• about/:name
• team/:teamId
• blog/:postId

Again, the children property can be used to express nested routes with path params:

1 const routes = [
2   {
3     path: 'about',
4     children: [
5       {
6         path: ':name', // matches /about/:name
7       },
8     ],
9   },
10 ]

The text that matches a path param is extracted and usable in many places like loaders, importers and elements.

Because path params behave like wildcards, they will match any path that provides them with a valid value. Because of this, it is recommended to define path params last in your route hierarchy so you have the opportunity to match other non-wildcard paths before they are matched by path params:

1 const routes = [
2   {
3     path: 'teams',
4     children: [
5       {
6         path: 'new', // matches /teams/new
7       },
8       {
9         path: ':teamId', // matches /teams/:teamId
10       },
11     ],
12   },
13 ]

Wildcard Paths

Wildcard paths are defined by using the * character in the path. The following are valid paths:

• *
• about/*
• team/*
• blog/*

Again, the children property can be used to express nested routes with wildcard paths:

1 const routes = [
2   {
3     path: 'dashboard',
4     children: [
5       {
6         path: '/', // matches /dashboard exactly
7       },
8       {
9         path: 'teams', // matches /dashboard/teams/*
10       },
11       {
12         path: '*', // matches /dashboard/*
13       },
14     ],
15   },
16 ]

The text that matches a wildcard is extracted under the * key and is usable in many places like loaders, importers and elements, via useMatch.

Search Matching

Up to this point, we've only talked about path matching, but the path is only a small party of the entire URL. In React Location, the search section of the URL is actually a first-class citizen and represented as an object of key/value pairs. You can learn more about Search Params in another section, but we'll mention here that you can use the search property to match a route using search params as well!

To do this, pass a search function to the route:

1 const routes = [
2   {
3     path: 'team',
4     // This route would match the url `/team?teamId=1234`
5     search: (search) => {
6       return search.teamId === '1234'
7     },
8   },
9 ]

The search function is passed the current search object, and should return a boolean value. If the function returns true, the route will match.

Note that if you have two base routes that are only differentiated by search, you must supply a unique id to each route object.

1 const routes = [
2   {
3     id: 'teamId1234',
4     path: 'team',
5     // This route would match the url `/team?teamId=1234`
6     search: (search) => {
7       return search.teamId === '1234'
8     },
9   },
10   {
11     id: 'teamId9999',
12     path: 'team',
13     // This route would match the url `/team?teamId=9999`
14     search: (search) => {
15       return search.teamId === '9999'
16     },
17   },
18 ]

Even we are still exploring the possibilities that search matching provides, so let us know what you do with them!

Route Defaults

Routes in React Location are extremely forgiving with plenty of default behaviors:

• If a route has no path, it is considered to have path: *, so it will always be matched
• If a route has no element, it is considered to have element: <Outlet /> (or whatever you set as the Router's defaultElement prop)

Routes have so much more functionality, which we'll explore in the next few sections!