v5.reactrouter.com Open in urlscan Pro
2606:4700:3032::6815:1e14  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Remix
/
React Router
CoreWebNative
Announcements
The Future of React Router
Examples
BasicURL ParametersNestingRedirects (Auth)Custom LinkPreventing TransitionsNo
Match (404)Recursive PathsSidebarAnimated TransitionsRoute ConfigModal
GalleryStaticRouter ContextQuery Parameters
Guides
Quick StartPrimary ComponentsServer RenderingCode SplittingScroll
RestorationPhilosophyTestingDeep Redux IntegrationStatic Routes
API
Hooks
useHistoryuseLocationuseParamsuseRouteMatch
<BrowserRouter>
basename: stringgetUserConfirmation: funcforceRefresh: boolkeyLength:
numberchildren: node
<HashRouter>
basename: stringgetUserConfirmation: funchashType: stringchildren: node
<Link>
to: stringto: objectto: funcreplace: boolinnerRef: funcinnerRef:
RefObjectcomponent: React.Componentothers
<NavLink>
className: string | funcactiveClassName: stringstyle: object | funcactiveStyle:
objectexact: boolstrict: boolisActive: funclocation: objectaria-current: string
<Prompt>

<MemoryRouter>
initialEntries: arrayinitialIndex: numbergetUserConfirmation: funckeyLength:
numberchildren: node
<Redirect>
to: stringto: objectpush: boolfrom: stringexact: boolstrict: boolsensitive: bool
<Route>
Route render methodsRoute propscomponentrender: funcchildren: funcpath: string |
string[]exact: boolstrict: boollocation: objectsensitive: bool
<Router>
history: objectchildren: node
<StaticRouter>
basename: stringlocation: stringlocation: objectcontext: objectchildren: node
<Switch>
location: objectchildren: node
generatePath
pattern: stringparams: object
history
history is mutable
location

match
null matches
matchPath
pathnamepropsreturns
withRouter
Component.WrappedComponentwrappedComponentRef: func


HOOKS

React Router ships with a few hooks that let you access the state of the router
and perform navigation from inside your components.

Please note: You need to be using React >= 16.8 in order to use any of these
hooks!

 * useHistory
 * useLocation
 * useParams
 * useRouteMatch


USEHISTORY

The useHistory hook gives you access to the history instance that you may use to
navigate.

import { useHistory } from "react-router-dom";

function HomeButton() {
  let history = useHistory();

  function handleClick() {
    history.push("/home");
  }

  return (
    <button type="button" onClick={handleClick}>
      Go home
    </button>
  );
}



USELOCATION

The useLocation hook returns the location object that represents the current
URL. You can think about it like a useState that returns a new location whenever
the URL changes.

This could be really useful e.g. in a situation where you would like to trigger
a new “page view” event using your web analytics tool whenever a new page loads,
as in the following example:

import React from "react";
import ReactDOM from "react-dom";
import {
  BrowserRouter as Router,
  Switch,
  useLocation
} from "react-router-dom";

function usePageViews() {
  let location = useLocation();
  React.useEffect(() => {
    ga.send(["pageview", location.pathname]);
  }, [location]);
}

function App() {
  usePageViews();
  return <Switch>...</Switch>;
}

ReactDOM.render(
  <Router>
    <App />
  </Router>,
  node
);



USEPARAMS

useParams returns an object of key/value pairs of URL parameters. Use it to
access match.params of the current <Route>.

import React from "react";
import ReactDOM from "react-dom";
import {
  BrowserRouter as Router,
  Switch,
  Route,
  useParams
} from "react-router-dom";

function BlogPost() {
  let { slug } = useParams();
  return <div>Now showing post {slug}</div>;
}

ReactDOM.render(
  <Router>
    <Switch>
      <Route exact path="/">
        <HomePage />
      </Route>
      <Route path="/blog/:slug">
        <BlogPost />
      </Route>
    </Switch>
  </Router>,
  node
);



USEROUTEMATCH

The useRouteMatch hook attempts to match the current URL in the same way that a
<Route> would. It’s mostly useful for getting access to the match data without
actually rendering a <Route>.

Now, instead of

import { Route } from "react-router-dom";

function BlogPost() {
  return (
    <Route
      path="/blog/:slug"
      render={({ match }) => {
        // Do whatever you want with the match...
        return <div />;
      }}
    />
  );
}


you can just

import { useRouteMatch } from "react-router-dom";

function BlogPost() {
  let match = useRouteMatch("/blog/:slug");

  // Do whatever you want with the match...
  return <div />;
}


The useRouteMatch hook either:

 * takes no argument and returns the match object of the current <Route>
 * takes a single argument, which is identical to props argument of matchPath.
   It can be either a pathname as a string (like the example above) or an object
   with the matching props that Route accepts, like this:

const match = useRouteMatch({
  path: "/BLOG/:slug/",
  strict: true,
  sensitive: true
});



<BROWSERROUTER>

A <Router> that uses the HTML5 history API (pushState, replaceState and the
popstate event) to keep your UI in sync with the URL.

<BrowserRouter
  basename={optionalString}
  forceRefresh={optionalBool}
  getUserConfirmation={optionalFunc}
  keyLength={optionalNumber}
>
  <App />
</BrowserRouter>



BASENAME: STRING

The base URL for all locations. If your app is served from a sub-directory on
your server, you’ll want to set this to the sub-directory. A properly formatted
basename should have a leading slash, but no trailing slash.

<BrowserRouter basename="/calendar">
    <Link to="/today"/> // renders <a href="/calendar/today">
    <Link to="/tomorrow"/> // renders <a href="/calendar/tomorrow">
    ...
</BrowserRouter>



GETUSERCONFIRMATION: FUNC

A function to use to confirm navigation. Defaults to using window.confirm.

<BrowserRouter
  getUserConfirmation={(message, callback) => {
    // this is the default behavior
    const allowTransition = window.confirm(message);
    callback(allowTransition);
  }}
/>



FORCEREFRESH: BOOL

If true the router will use full page refreshes on page navigation. You may want
to use this to imitate the way a traditional server-rendered app would work with
full page refreshes between page navigation.

<BrowserRouter forceRefresh={true} />



KEYLENGTH: NUMBER

The length of location.key. Defaults to 6.

<BrowserRouter keyLength={12} />



CHILDREN: NODE

The child elements to render.

Note: On React < 16 you must use a single child element since a render method
cannot return more than one element. If you need more than one element, you
might try wrapping them in an extra <div> or <React.Fragment>.


<HASHROUTER>

A <Router> that uses the hash portion of the URL (i.e. window.location.hash) to
keep your UI in sync with the URL.

IMPORTANT NOTE: Hash history does not support location.key or location.state. In
previous versions we attempted to shim the behavior but there were edge-cases we
couldn’t solve. Any code or plugin that needs this behavior won’t work. As this
technique is only intended to support legacy browsers, we encourage you to
configure your server to work with <BrowserHistory> instead.

<HashRouter
  basename={optionalString}
  getUserConfirmation={optionalFunc}
  hashType={optionalString}
>
  <App />
</HashRouter>



BASENAME: STRING

The base URL for all locations. A properly formatted basename should have a
leading slash, but no trailing slash.

<HashRouter basename="/calendar"/>
<Link to="/today"/> // renders <a href="#/calendar/today">



GETUSERCONFIRMATION: FUNC

A function to use to confirm navigation. Defaults to using window.confirm.

<HashRouter
  getUserConfirmation={(message, callback) => {
    // this is the default behavior
    const allowTransition = window.confirm(message);
    callback(allowTransition);
  }}
/>



HASHTYPE: STRING

The type of encoding to use for window.location.hash. Available values are:

 * "slash" - Creates hashes like #/ and #/sunshine/lollipops
 * "noslash" - Creates hashes like # and #sunshine/lollipops
 * "hashbang" - Creates “ajax crawlable” (deprecated by Google) hashes like #!/
   and #!/sunshine/lollipops

Defaults to "slash".


CHILDREN: NODE

A single child element to render.


<LINK>

Provides declarative, accessible navigation around your application.

<Link to="/about">About</Link>



TO: STRING

A string representation of the Link location, created by concatenating the
location’s pathname, search, and hash properties.

<Link to="/courses?sort=name" />



TO: OBJECT

An object that can have any of the following properties:

 * pathname: A string representing the path to link to.
 * search: A string representation of query parameters.
 * hash: A hash to put in the URL, e.g. #a-hash.
 * state: State to persist to the location.

<Link
  to={{
    pathname: "/courses",
    search: "?sort=name",
    hash: "#the-hash",
    state: { fromDashboard: true }
  }}
/>



TO: FUNC

A function to which current location is passed as an argument and which should
return location representation as a string or as an object

<Link to={location => ({ ...location, pathname: "/courses" })} />


<Link to={location => `${location.pathname}?sort=name`} />



REPLACE: BOOL

When true, clicking the link will replace the current entry in the history stack
instead of adding a new one.

<Link to="/courses" replace />



INNERREF: FUNC

As of React Router 5.1, if you are using React 16 you should not need this prop
because we forward the ref to the underlying <a>. Use a normal ref instead.

Allows access to the underlying ref of the component.

<Link
  to="/"
  innerRef={node => {
    // `node` refers to the mounted DOM element
    // or null when unmounted
  }}
/>



INNERREF: REFOBJECT

As of React Router 5.1, if you are using React 16 you should not need this prop
because we forward the ref to the underlying <a>. Use a normal ref instead.

Get the underlying ref of the component using React.createRef.

let anchorRef = React.createRef()

<Link to="/" innerRef={anchorRef} />



COMPONENT: REACT.COMPONENT

If you would like utilize your own navigation component, you can do so by
passing it through the component prop.

const FancyLink = React.forwardRef(({ navigate, ...props }, ref) => {
  return (
    <a ref={ref} {...props} onClick={handleClick}>💅 {props.children}</a>
  )
})

<Link to="/" component={FancyLink} />



OTHERS

You can also pass props you’d like to be on the <a> such as a title, id,
className, etc.


<NAVLINK>

A special version of the <Link> that will add styling attributes to the rendered
element when it matches the current URL.

<NavLink to="/about">About</NavLink>



CLASSNAME: STRING | FUNC

className can either be a string or a function that returns a string. If the
function className is used, the link’s active state is passed as a parameter.
This is helpful if you want to exclusively apply a className to an inactive
link.

<NavLink
  to="/faq"
  className={isActive =>
    "nav-link" + (!isActive ? " unselected" : "")
  }
>
  FAQs
</NavLink>


In React Router v6, activeClassName will be removed and you should use the
function className to apply classnames to either active or inactive NavLink
components.


ACTIVECLASSNAME: STRING

The class to give the element when it is active. The default given class is
active. This will be joined with the className prop.

<NavLink to="/faq" activeClassName="selected">
  FAQs
</NavLink>



STYLE: OBJECT | FUNC

style can either be a React.CSSProperties object or a function that returns a
style object. If the function style is used, the link’s active state is passed
as a parameter.

<NavLink
  to="/faq"
  style={isActive => ({
    color: isActive ? "green" : "blue"
  })}
>
  FAQs
</NavLink>


In React Router v6, activeStyle will be removed and you should use the function
style to apply inline styles to either active or inactive NavLink components.


ACTIVESTYLE: OBJECT

The styles to apply to the element when it is active.

<NavLink
  to="/faq"
  activeStyle={{
    fontWeight: "bold",
    color: "red"
  }}
>
  FAQs
</NavLink>



EXACT: BOOL

When true, the active class/style will only be applied if the location is
matched exactly.

<NavLink exact to="/profile">
  Profile
</NavLink>



STRICT: BOOL

When true, the trailing slash on a location’s pathname will be taken into
consideration when determining if the location matches the current URL. See the
<Route strict> documentation for more information.

<NavLink strict to="/events/">
  Events
</NavLink>



ISACTIVE: FUNC

A function to add extra logic for determining whether the link is active. This
should be used if you want to do more than verify that the link’s pathname
matches the current URL’s pathname.

<NavLink
  to="/events/123"
  isActive={(match, location) => {
    if (!match) {
      return false;
    }

    // only consider an event active if its event id is an odd number
    const eventID = parseInt(match.params.eventID);
    return !isNaN(eventID) && eventID % 2 === 1;
  }}
>
  Event 123
</NavLink>



LOCATION: OBJECT

The isActive compares the current history location (usually the current browser
URL). To compare to a different location, a location can be passed.


ARIA-CURRENT: STRING

The value of the aria-current attribute used on an active link. Available values
are:

 * "page" - used to indicate a link within a set of pagination links
 * "step" - used to indicate a link within a step indicator for a step-based
   process
 * "location" - used to indicate the image that is visually highlighted as the
   current component of a flow chart
 * "date" - used to indicate the current date within a calendar
 * "time" - used to indicate the current time within a timetable
 * "true" - used to indicate if the NavLink is active
 * "false" - used to prevent assistive technologies from reacting to a current
   link (a use case would be to prevent multiple aria-current tags on a single
   page)

Defaults to "page".

Based on WAI-ARIA 1.1 specifications


<PROMPT>

Re-exported from core Prompt


<MEMORYROUTER>

A <Router> that keeps the history of your “URL” in memory (does not read or
write to the address bar). Useful in tests and non-browser environments like
React Native.

<MemoryRouter
  initialEntries={optionalArray}
  initialIndex={optionalNumber}
  getUserConfirmation={optionalFunc}
  keyLength={optionalNumber}
>
  <App />
</MemoryRouter>



INITIALENTRIES: ARRAY

An array of locations in the history stack. These may be full-blown location
objects with { pathname, search, hash, state } or simple string URLs.

<MemoryRouter
  initialEntries={["/one", "/two", { pathname: "/three" }]}
  initialIndex={1}
>
  <App />
</MemoryRouter>



INITIALINDEX: NUMBER

The initial location’s index in the array of initialEntries.


GETUSERCONFIRMATION: FUNC

A function to use to confirm navigation. You must use this option when using
<MemoryRouter> directly with a <Prompt>.


KEYLENGTH: NUMBER

The length of location.key. Defaults to 6.

<MemoryRouter keyLength={12} />



CHILDREN: NODE

The child elements to render.

Note: On React < 16 you must use a single child element since a render method
cannot return more than one element. If you need more than one element, you
might try wrapping them in an extra <div> or <React.Fragment>.


<REDIRECT>

Rendering a <Redirect> will navigate to a new location. The new location will
override the current location in the history stack, like server-side redirects
(HTTP 3xx) do.

<Route exact path="/">
  {loggedIn ? <Redirect to="/dashboard" /> : <PublicHomePage />}
</Route>



TO: STRING

The URL to redirect to. Any valid URL path that path-to-regexp@^1.7.0
understands. All URL parameters that are used in to must be covered by from.

<Redirect to="/somewhere/else" />



TO: OBJECT

A location to redirect to. pathname can be any valid URL path that
path-to-regexp@^1.7.0 understands.

<Redirect
  to={{
    pathname: "/login",
    search: "?utm=your+face",
    state: { referrer: currentLocation }
  }}
/>


The state object can be accessed via this.props.location.state in the
redirected-to component. This new referrer key (which is not a special name)
would then be accessed via this.props.location.state.referrer in the Login
component pointed to by the pathname '/login'


PUSH: BOOL

When true, redirecting will push a new entry onto the history instead of
replacing the current one.

<Redirect push to="/somewhere/else" />



FROM: STRING

A pathname to redirect from. Any valid URL path that path-to-regexp@^1.7.0
understands. All matched URL parameters are provided to the pattern in to. Must
contain all parameters that are used in to. Additional parameters not used by to
are ignored.

Note: This can only be used to match a location when rendering a <Redirect>
inside of a <Switch>. See <Switch children> for more details.

<Switch>
  <Redirect from="/old-path" to="/new-path" />
  <Route path="/new-path">
    <Place />
  </Route>
</Switch>

// Redirect with matched parameters
<Switch>
  <Redirect from="/users/:id" to="/users/profile/:id" />
  <Route path="/users/profile/:id">
    <Profile />
  </Route>
</Switch>



EXACT: BOOL

Match from exactly; equivalent to Route.exact.

Note: This can only be used in conjunction with from to exactly match a location
when rendering a <Redirect> inside of a <Switch>. See <Switch children> for more
details.

<Switch>
  <Redirect exact from="/" to="/home" />
  <Route path="/home">
    <Home />
  </Route>
  <Route path="/about">
    <About />
  </Route>
</Switch>



STRICT: BOOL

Match from strictly; equivalent to Route.strict.

Note: This can only be used in conjunction with from to strictly match a
location when rendering a <Redirect> inside of a <Switch>. See <Switch children>
for more details.

<Switch>
  <Redirect strict from="/one/" to="/home" />
  <Route path="/home">
    <Home />
  </Route>
  <Route path="/about">
    <About />
  </Route>
</Switch>



SENSITIVE: BOOL

Match from case sensitive; equivalent to Route.sensitive.


<ROUTE>

The Route component is perhaps the most important component in React Router to
understand and learn to use well. Its most basic responsibility is to render
some UI when its path matches the current URL.

Consider the following code:

import React from "react";
import ReactDOM from "react-dom";
import { BrowserRouter as Router, Route } from "react-router-dom";

ReactDOM.render(
  <Router>
    <div>
      <Route exact path="/">
        <Home />
      </Route>
      <Route path="/news">
        <NewsFeed />
      </Route>
    </div>
  </Router>,
  node
);


If the location of the app is / then the UI hierarchy will be something like:

<div>
  <Home />
  <!-- react-empty: 2 -->
</div>


And if the location of the app is /news then the UI hierarchy will be:

<div>
  <!-- react-empty: 1 -->
  <NewsFeed />
</div>


The “react-empty” comments are just implementation details of React’s null
rendering. But for our purposes, it is instructive. A Route is always
technically “rendered” even though it’s rendering null. When the <Route>'s path
matches the current URL, it renders its children (your component).

If the same component is used as the child of multiple <Route>s at the same
point in the component tree, React will see this as the same component instance
and the component’s state will be preserved between route changes. If this isn’t
desired, a unique key prop added to each route component will cause React to
recreate the component instance when the route changes.


ROUTE RENDER METHODS

The recommended method of rendering something with a <Route> is to use children
elements, as shown above. There are, however, a few other methods you can use to
render something with a <Route>. These are provided mostly for supporting apps
that were built with earlier versions of the router before hooks were
introduced.

 * <Route component>
 * <Route render>
 * <Route children> function

You should use only one of these props on a given <Route>. See their
explanations below to understand the differences between them.


ROUTE PROPS

All three render methods will be passed the same three route props

 * match
 * location
 * history


COMPONENT

A React component to render only when the location matches. It will be rendered
with route props.

import React from "react";
import ReactDOM from "react-dom";
import { BrowserRouter as Router, Route } from "react-router-dom";

// All route props (match, location and history) are available to User
function User(props) {
  return <h1>Hello {props.match.params.username}!</h1>;
}

ReactDOM.render(
  <Router>
    <Route path="/user/:username" component={User} />
  </Router>,
  node
);


When you use component (instead of render or children, below) the router uses
React.createElement to create a new React element from the given component. That
means if you provide an inline function to the component prop, you would create
a new component every render. This results in the existing component unmounting
and the new component mounting instead of just updating the existing component.
When using an inline function for inline rendering, use the render or the
children prop (below).


RENDER: FUNC

This allows for convenient inline rendering and wrapping without the undesired
remounting explained above.

Instead of having a new React element created for you using the component prop,
you can pass in a function to be called when the location matches. The render
prop function has access to all the same route props (match, location and
history) as the component render prop.

import React from "react";
import ReactDOM from "react-dom";
import { BrowserRouter as Router, Route } from "react-router-dom";

// convenient inline rendering
ReactDOM.render(
  <Router>
    <Route path="/home" render={() => <div>Home</div>} />
  </Router>,
  node
);

// wrapping/composing
// You can spread routeProps to make them available to your rendered Component
function FadingRoute({ component: Component, ...rest }) {
  return (
    <Route
      {...rest}
      render={routeProps => (
        <FadeIn>
          <Component {...routeProps} />
        </FadeIn>
      )}
    />
  );
}

ReactDOM.render(
  <Router>
    <FadingRoute path="/cool" component={Something} />
  </Router>,
  node
);


Warning: <Route component> takes precedence over <Route render> so don’t use
both in the same <Route>.


CHILDREN: FUNC

Sometimes you need to render whether the path matches the location or not. In
these cases, you can use the function children prop. It works exactly like
render except that it gets called whether there is a match or not.

The children render prop receives all the same route props as the component and
render methods, except when a route fails to match the URL, then match is null.
This allows you to dynamically adjust your UI based on whether or not the route
matches. Here we’re adding an active class if the route matches

import React from "react";
import ReactDOM from "react-dom";
import {
  BrowserRouter as Router,
  Link,
  Route
} from "react-router-dom";

function ListItemLink({ to, ...rest }) {
  return (
    <Route
      path={to}
      children={({ match }) => (
        <li className={match ? "active" : ""}>
          <Link to={to} {...rest} />
        </li>
      )}
    />
  );
}

ReactDOM.render(
  <Router>
    <ul>
      <ListItemLink to="/somewhere" />
      <ListItemLink to="/somewhere-else" />
    </ul>
  </Router>,
  node
);


This could also be useful for animations:

<Route
  children={({ match, ...rest }) => (
    {/* Animate will always render, so you can use lifecycles
        to animate its child in and out */}
    <Animate>
      {match && <Something {...rest}/>}
    </Animate>
  )}
/>


Warning: <Route children> takes precedence over both <Route component> and
<Route render> so don’t use more than one in the same <Route>.


PATH: STRING | STRING[]

Any valid URL path or array of paths that path-to-regexp@^1.7.0 understands.

<Route path="/users/:id">
  <User />
</Route>


<Route path={["/users/:id", "/profile/:id"]}>
  <User />
</Route>


Routes without a path always match.


EXACT: BOOL

When true, will only match if the path matches the location.pathname exactly.

<Route exact path="/one">
  <About />
</Route>


path location.pathname exact matches? /one /one/two true no /one /one/two false
yes


STRICT: BOOL

When true, a path that has a trailing slash will only match a location.pathname
with a trailing slash. This has no effect when there are additional URL segments
in the location.pathname.

<Route strict path="/one/">
  <About />
</Route>


path location.pathname matches? /one/ /one no /one/ /one/ yes /one/ /one/two yes

Warning: strict can be used to enforce that a location.pathname has no trailing
slash, but in order to do this both strict and exact must be true.

<Route exact strict path="/one">
  <About />
</Route>


path location.pathname matches? /one /one yes /one /one/ no /one /one/two no


LOCATION: OBJECT

A <Route> element tries to match its path to the current history location
(usually the current browser URL). However, a location with a different pathname
can also be passed for matching.

This is useful in cases when you need to match a <Route> to a location other
than the current history location, as shown in the Animated Transitions example.

If a <Route> element is wrapped in a <Switch> and matches the location passed to
the <Switch> (or the current history location), then the location prop passed to
<Route> will be overridden by the one used by the <Switch> (given here).


SENSITIVE: BOOL

When true, will match if the path is case sensitive.

<Route sensitive path="/one">
  <About />
</Route>


path location.pathname sensitive matches? /one /one true yes /One /one true no
/One /one false yes


<ROUTER>

The common low-level interface for all router components. Typically apps will
use one of the high-level routers instead:

 * <BrowserRouter>
 * <HashRouter>
 * <MemoryRouter>
 * <NativeRouter>
 * <StaticRouter>

The most common use-case for using the low-level <Router> is to synchronize a
custom history with a state management lib like Redux or Mobx. Note that this is
not required to use state management libs alongside React Router, it’s only for
deep integration.

import React from "react";
import ReactDOM from "react-dom";
import { Router } from "react-router";
import { createBrowserHistory } from "history";

const history = createBrowserHistory();

ReactDOM.render(
  <Router history={history}>
    <App />
  </Router>,
  node
);



HISTORY: OBJECT

A history object to use for navigation.

import React from "react";
import ReactDOM from "react-dom";
import { createBrowserHistory } from "history";

const customHistory = createBrowserHistory();

ReactDOM.render(<Router history={customHistory} />, node);



CHILDREN: NODE

A child element to render.

<Router>
  <App />
</Router>



<STATICROUTER>

A <Router> that never changes location.

This can be useful in server-side rendering scenarios when the user isn’t
actually clicking around, so the location never actually changes. Hence, the
name: static. It’s also useful in simple tests when you just need to plug in a
location and make assertions on the render output.

Here’s an example node server that sends a 302 status code for <Redirect>s and
regular HTML for other requests:

import http from "http";
import React from "react";
import ReactDOMServer from "react-dom/server";
import { StaticRouter } from "react-router";

http
  .createServer((req, res) => {
    // This context object contains the results of the render
    const context = {};

    const html = ReactDOMServer.renderToString(
      <StaticRouter location={req.url} context={context}>
        <App />
      </StaticRouter>
    );

    // context.url will contain the URL to redirect to if a <Redirect> was used
    if (context.url) {
      res.writeHead(302, {
        Location: context.url
      });
      res.end();
    } else {
      res.write(html);
      res.end();
    }
  })
  .listen(3000);



BASENAME: STRING

The base URL for all locations. A properly formatted basename should have a
leading slash, but no trailing slash.

<StaticRouter basename="/calendar">
  <Link to="/today"/> // renders <a href="/calendar/today">
</StaticRouter>



LOCATION: STRING

The URL the server received, probably req.url on a node server.

<StaticRouter location={req.url}>
  <App />
</StaticRouter>



LOCATION: OBJECT

A location object shaped like { pathname, search, hash, state }

<StaticRouter location={{ pathname: "/bubblegum" }}>
  <App />
</StaticRouter>



CONTEXT: OBJECT

A plain JavaScript object. During the render, components can add properties to
the object to store information about the render.

const context = {}
<StaticRouter context={context}>
  <App />
</StaticRouter>


When a <Route> matches, it will pass the context object to the component it
renders as the staticContext prop. Check out the Server Rendering guide for more
information on how to do this yourself.

After the render, these properties can be used to to configure the server’s
response.

if (context.status === "404") {
  // ...
}



CHILDREN: NODE

The child elements to render.

Note: On React < 16 you must use a single child element since a render method
cannot return more than one element. If you need more than one element, you
might try wrapping them in an extra <div> or <React.Fragment>.


<SWITCH>

Renders the first child <Route> or <Redirect> that matches the location.

How is this different than just using a bunch of <Route>s?

<Switch> is unique in that it renders a route exclusively. In contrast, every
<Route> that matches the location renders inclusively. Consider these routes:

import { Route } from "react-router";

let routes = (
  <div>
    <Route path="/about">
      <About />
    </Route>
    <Route path="/:user">
      <User />
    </Route>
    <Route>
      <NoMatch />
    </Route>
  </div>
);


If the URL is /about, then <About>, <User>, and <NoMatch> will all render
because they all match the path. This is by design, allowing us to compose
<Route>s into our apps in many ways, like sidebars and breadcrumbs, bootstrap
tabs, etc.

Occasionally, however, we want to pick only one <Route> to render. If we’re at
/about we don’t want to also match /:user (or show our “404” page). Here’s how
to do it with Switch:

import { Route, Switch } from "react-router";

let routes = (
  <Switch>
    <Route exact path="/">
      <Home />
    </Route>
    <Route path="/about">
      <About />
    </Route>
    <Route path="/:user">
      <User />
    </Route>
    <Route>
      <NoMatch />
    </Route>
  </Switch>
);


Now, if we’re at /about, <Switch> will start looking for a matching <Route>.
<Route path="/about"/> will match and <Switch> will stop looking for matches and
render <About>. Similarly, if we’re at /michael then <User> will render.

This is also useful for animated transitions since the matched <Route> is
rendered in the same position as the previous one.

let routes = (
  <Fade>
    <Switch>
      {/* there will only ever be one child here */}
      <Route />
      <Route />
    </Switch>
  </Fade>
);

let routes = (
  <Fade>
    {/* there will always be two children here,
        one might render null though, making transitions
        a bit more cumbersome to work out */}
    <Route />
    <Route />
  </Fade>
);



LOCATION: OBJECT

A location object to be used for matching children elements instead of the
current history location (usually the current browser URL).


CHILDREN: NODE

All children of a <Switch> should be <Route> or <Redirect> elements. Only the
first child to match the current location will be rendered.

<Route> elements are matched using their path prop and <Redirect> elements are
matched using their from prop. A <Route> with no path prop or a <Redirect> with
no from prop will always match the current location.

When you include a <Redirect> in a <Switch>, it can use any of the <Route>'s
location matching props: path, exact, and strict. from is just an alias for the
path prop.

If a location prop is given to the <Switch>, it will override the location prop
on the matching child element.

import { Redirect, Route, Switch } from "react-router";

let routes = (
  <Switch>
    <Route exact path="/">
      <Home />
    </Route>

    <Route path="/users">
      <Users />
    </Route>
    <Redirect from="/accounts" to="/users" />

    <Route>
      <NoMatch />
    </Route>
  </Switch>
);



GENERATEPATH

The generatePath function can be used to generate URLs to the routes. Internally
the path-to-regexp library is used.

import { generatePath } from "react-router";

generatePath("/user/:id/:entity(posts|comments)", {
  id: 1,
  entity: "posts"
});
// Will return /user/1/posts


Results of compiling paths into regular expressions are cached, so there is no
overhead on generating multiple paths with the same pattern.


PATTERN: STRING

generatePath takes 2 arguments. The first one is a pattern provided as a path
attribute to the Route component.


PARAMS: OBJECT

The second argument is an object with corresponding params for the pattern to
use.

If provided params and path don’t match, an error will be thrown:

generatePath("/user/:id/:entity(posts|comments)", { id: 1 });
// TypeError: Expected "entity" to be defined



HISTORY

The term “history” and "history object" in this documentation refers to the
history package, which is one of only 2 major dependencies of React Router
(besides React itself), and which provides several different implementations for
managing session history in JavaScript in various environments.

The following terms are also used:

 * “browser history” - A DOM-specific implementation, useful in web browsers
   that support the HTML5 history API
 * “hash history” - A DOM-specific implementation for legacy web browsers
 * “memory history” - An in-memory history implementation, useful in testing and
   non-DOM environments like React Native

history objects typically have the following properties and methods:

 * length - (number) The number of entries in the history stack
 * action - (string) The current action (PUSH, REPLACE, or POP)
 * location - (object) The current location. May have the following properties:
   * pathname - (string) The path of the URL
   * search - (string) The URL query string
   * hash - (string) The URL hash fragment
   * state - (object) location-specific state that was provided to e.g.
     push(path, state) when this location was pushed onto the stack. Only
     available in browser and memory history.
 * push(path, [state]) - (function) Pushes a new entry onto the history stack
 * replace(path, [state]) - (function) Replaces the current entry on the history
   stack
 * go(n) - (function) Moves the pointer in the history stack by n entries
 * goBack() - (function) Equivalent to go(-1)
 * goForward() - (function) Equivalent to go(1)
 * block(prompt) - (function) Prevents navigation (see the history docs


HISTORY IS MUTABLE

The history object is mutable. Therefore it is recommended to access the
location from the render props of <Route>, not from history.location. This
ensures your assumptions about React are correct in lifecycle hooks. For
example:

class Comp extends React.Component {
  componentDidUpdate(prevProps) {
    // will be true
    const locationChanged =
      this.props.location !== prevProps.location;

    // INCORRECT, will *always* be false because history is mutable.
    const locationChanged =
      this.props.history.location !== prevProps.history.location;
  }
}

<Route component={Comp} />;


Additional properties may also be present depending on the implementation you’re
using. Please refer to the history documentation for more details.


LOCATION

Locations represent where the app is now, where you want it to go, or even where
it was. It looks like this:

{
  key: 'ac3df4', // not with HashHistory!
  pathname: '/somewhere',
  search: '?some=search-string',
  hash: '#howdy',
  state: {
    [userDefined]: true
  }
}


The router will provide you with a location object in a few places:

 * Route component as this.props.location
 * Route render as ({ location }) => ()
 * Route children as ({ location }) => ()
 * withRouter as this.props.location

It is also found on history.location but you shouldn’t use that because it’s
mutable. You can read more about that in the history doc.

A location object is never mutated so you can use it in the lifecycle hooks to
determine when navigation happens, this is really useful for data fetching and
animation.

componentWillReceiveProps(nextProps) {
  if (nextProps.location !== this.props.location) {
    // navigated!
  }
}


You can provide locations instead of strings to the various places that
navigate:

 * Web Link to
 * Native Link to
 * Redirect to
 * history.push
 * history.replace

Normally you just use a string, but if you need to add some “location state”
that will be available whenever the app returns to that specific location, you
can use a location object instead. This is useful if you want to branch UI based
on navigation history instead of just paths (like modals).

// usually all you need
<Link to="/somewhere"/>

// but you can use a location instead
const location = {
  pathname: '/somewhere',
  state: { fromDashboard: true }
}

<Link to={location}/>
<Redirect to={location}/>
history.push(location)
history.replace(location)


Finally, you can pass a location to the following components:

 * Route
 * Switch

This will prevent them from using the actual location in the router’s state.
This is useful for animation and pending navigation, or any time you want to
trick a component into rendering at a different location than the real one.


MATCH

A match object contains information about how a <Route path> matched the URL.
match objects contain the following properties:

 * params - (object) Key/value pairs parsed from the URL corresponding to the
   dynamic segments of the path
 * isExact - (boolean) true if the entire URL was matched (no trailing
   characters)
 * path - (string) The path pattern used to match. Useful for building nested
   <Route>s
 * url - (string) The matched portion of the URL. Useful for building nested
   <Link>s

You’ll have access to match objects in various places:

 * Route component as this.props.match
 * Route render as ({ match }) => ()
 * Route children as ({ match }) => ()
 * withRouter as this.props.match
 * matchPath as the return value
 * useRouteMatch as the return value

If a Route does not have a path, and therefore always matches, you’ll get the
closest parent match. Same goes for withRouter.


NULL MATCHES

A <Route> that uses the children prop will call its children function even when
the route’s path does not match the current location. When this is the case, the
match will be null. Being able to render a <Route>'s contents when it does match
can be useful, but certain challenges arise from this situation.

The default way to “resolve” URLs is to join the match.url string to the
“relative” path.

let path = `${match.url}/relative-path`;


If you attempt to do this when the match is null, you will end up with a
TypeError. This means that it is considered unsafe to attempt to join “relative”
paths inside of a <Route> when using the children prop.

A similar, but more subtle situation occurs when you use a pathless <Route>
inside of a <Route> that generates a null match object.

// location.pathname = '/matches'
<Route path="/does-not-match"
  children={({ match }) => (
    // match === null
    <Route
      render={({ match: pathlessMatch }) => (
        // pathlessMatch === ???
      )}
    />
  )}
/>


Pathless <Route>s inherit their match object from their parent. If their parent
match is null, then their match will also be null. This means that a) any child
routes/links will have to be absolute because there is no parent to resolve with
and b) a pathless route whose parent match can be null will need to use the
children prop to render.


MATCHPATH

This lets you use the same matching code that <Route> uses except outside of the
normal render cycle, like gathering up data dependencies before rendering on the
server.

import { matchPath } from "react-router";

const match = matchPath("/users/123", {
  path: "/users/:id",
  exact: true,
  strict: false
});



PATHNAME

The first argument is the pathname you want to match. If you’re using this on
the server with Node.js, it would be req.path.


PROPS

The second argument are the props to match against, they are identical to the
matching props Route accepts. It could also be a string or an array of strings
as shortcut for { path }:

{
  path, // like /users/:id; either a single string or an array of strings
  strict, // optional, defaults to false
  exact, // optional, defaults to false
}



RETURNS

It returns an object when provided pathname does match path prop.

matchPath("/users/2", {
  path: "/users/:id",
  exact: true,
  strict: true
});

//  {
//    isExact: true
//    params: {
//        id: "2"
//    }
//    path: "/users/:id"
//    url: "/users/2"
//  }


It returns null when provided pathname does not match path prop.

matchPath("/users", {
  path: "/users/:id",
  exact: true,
  strict: true
});

//  null



WITHROUTER

You can get access to the history object’s properties and the closest <Route>'s
match via the withRouter higher-order component. withRouter will pass updated
match, location, and history props to the wrapped component whenever it renders.

import React from "react";
import PropTypes from "prop-types";
import { withRouter } from "react-router";

// A simple component that shows the pathname of the current location
class ShowTheLocation extends React.Component {
  static propTypes = {
    match: PropTypes.object.isRequired,
    location: PropTypes.object.isRequired,
    history: PropTypes.object.isRequired
  };

  render() {
    const { match, location, history } = this.props;

    return <div>You are now at {location.pathname}</div>;
  }
}

// Create a new component that is "connected" (to borrow redux
// terminology) to the router.
const ShowTheLocationWithRouter = withRouter(ShowTheLocation);


IMPORTANT NOTE

withRouter does not subscribe to location changes like React Redux’s connect
does for state changes. Instead, re-renders after location changes propagate out
from the <Router> component. This means that withRouter does not re-render on
route transitions unless its parent component re-renders.

STATIC METHODS AND PROPERTIES

All non-react specific static methods and properties of the wrapped component
are automatically copied to the "connected" component.


COMPONENT.WRAPPEDCOMPONENT

The wrapped component is exposed as the static property WrappedComponent on the
returned component, which can be used for testing the component in isolation,
among other things.

// MyComponent.js
export default withRouter(MyComponent)

// MyComponent.test.js
import MyComponent from './MyComponent'
render(<MyComponent.WrappedComponent location={{...}} ... />)



WRAPPEDCOMPONENTREF: FUNC

A function that will be passed as the ref prop to the wrapped component.

class Container extends React.Component {
  componentDidMount() {
    this.component.doSomething();
  }

  render() {
    return (
      <MyComponent wrappedComponentRef={c => (this.component = c)} />
    );
  }
}