react-location v3.3.4

React-Location

⚛️ React utilities for location routing, params, queries, and hashes.

React-Location is a Router for React. It's been built with the following considerations in mind:

• Clean and clear routing syntax
• Familiar API for productivity
• Functional query params & URL parsing
• Complex Link generation
• Relative Routing + Links
• Both Colocated or Nested Route structure
• Programmatic Navigation
• Hooks for ease-of-use
• Support for URL or in-memory location sources

Get Started

1. Install react-location

yarn add react-location
# or
npm i -s react-location

2. Import and use react-location

import { React } from "react";
import { render } from "react-dom";
import { LocationProvider, Match, MatchFirst, Link } from "react-location";

render(
  <LocationProvider>
    <nav>
      <Link to="/">Home</Link>
      <Link to="dashboard">Dashboard</Link>
      <Link to="invoices">Invoices</Link>
    </nav>
    <div>
      <Match path="/">
        <div>This is Home</div>
      </Match>
      <Match path="dashboard">
        <div>This is the Dashboard</div>
      </Match>
      <MatchFirst>
        <Match path="invoices">
          <div>These are the invoices</div>
          <ul>
            <li>
              <Link to="1">Invoice 1</Link>
            </li>
            <li>
              <Link to="2">Invoice 2</Link>
            </li>
            <li>
              <Link to="3">Invoice 3</Link>
            </li>
          </ul>
        </Match>
        <Match path=":invoiceID">
          {({ params }) => (
            <div>
              <Link to="..">Back</Link>
              This is invoice #{params.invoiceID}
            </div>
          )}
        </Match>
      </MatchFirst>
    </div>
  </LocationProvider>
);

Components

LocationProvider

Required: true

The LocationProvider component is the root Provider component for react-location in your app. Render it at least once in the highest sensible location within your application. You can also use this component to preserve multiple location instances in the react tree at the same, which is useful for things like route animations or location mocking.

Example: Animated Routes

import { LocationProvider, Location, Match } from "react-location";

const AnimatedWrapper = ({ children }) => (
  <Location>
    {location => (
      // Get the current location and its key
      // Use location.key as the unique ID in your animations
      <TransitionGroup className="transition-group">
        <CSSTransition key={location.key} classNames="fade" timeout={500}>
          {/* Manually pass LocationProvider the location prop for each animation */}
          <LocationProvider location={location} />
        </CSSTransition>
      </TransitionGroup>
    )}
  </Location>
);

render(
  <LocationProvider>
    <AnimatedWrapper>
      <MatchFirst>
        <Match path="/page/:pageID">
          {({ pageID, location }) => (
            <div
              className="page"
              style={{ background: `hsl(${pageID * 75}, 60%, 60%)` }}
            >
              {pageID}
            </div>
          )}
        </Match>
      </MatchFirst>
    </AnimatedWrapper>
  </LocationProvider>
);

Match

The Match component is used to render content when its path matches the current history's location. It is generally used for routing purposes. It also provides the new relative matching path to child Match components, allowing for clean nested route definition.

Example

// Render children directly
render(<Match path="about">About me</Match>);

// Use children as a function
render(
  <Match path=":invoiceID">
    {location => <div>This is invoice #{location.params.invoiceID}</div>}
  </Match>
);

// Use a render function
render(
  <Match
    path=":invoiceID"
    render={location => <div>This is invoice #{location.params.invoiceID}</div>}
  />
);

// Use a component
const Invoice = ({ dark, location }) => (
  <div>This is invoice #{location.params.invoiceID}</div>
);

render(<Match path=":invoiceID" component={Invoice} dark />);

MatchFirst

The MatchFirst component is used to selectively render the first child component that is av valid match and/or provide fallbacks. This is useful for:

• Nesting and Relative Routes
• Matching index routes and hard-coded routes before dynamic ones
• Default / fallback routes

Example - Route Params

render(
  <Match path="invoices">
    <MatchFirst>
      <Match path="/">This route would match and display at `/invoices/`</Match>
      <Match path="new">
        This route would match and display at `/invoices/new`
      </Match>
      <Match path=":invoiceID">
        {({ params }) => (
          <div>
            This route would match for all other `/invoices/:invoiceID/` routes
          </div>
        )}
      </Match>
    </MatchFirst>
  </Match>
);

Example - Default / Fallback Route

render(
  <MatchFirst>
    <Match path="/">This route would match and display at `/`</Match>
    <Match path="about">This route would match and display at `/about`</Match>
    <div>
      This element would be rendered as the fallback when no Matches are found
    </div>
  </MatchFirst>
);

Link

The Link component allows you to generate <a href/> links for navigation, capable of updating the:

• Route path + hash
• Query parameters
• State
• Push vs. Replace

The links generated by it are designed to work perfectly with Open in new Tab + ctrl + left-click and Open in new window.... They are also capable of receiving "active" props (depending on the activeType passed) to decorate the link when the link is currently active relative to the current location.

Example: The basics

render(
  <div>
    <Link to="/home">I will navigate to `/home`</Link>
    <Link to="todos">
      I will navigate to `./todos`, relative to the current location
    </Link>
    <Link to="..">I will navigate up one level in the location hierarchy.</Link>
    <Link to="#somehash">
      I will navigate to the hash `somehash` at the current location
    </Link>
    <Link to="/search?stringQuery=yes!">I will navigate to `/search?stringQuery=yes!`</Link>
    <Link
      query={
        someParams: true,
        otherParams: 'gogogo',
        object: { nested: { list: [1, 2, 3], hello: "world" } }
      }}
    >
      I will navigate to the current location + `?someParams=true&otherParams=gogogo&object=%7B%22nested%22%3A%7B%22list%22%3A%5B1%2C2%2C3%5D%2C%22hello%22%3A%22world%22%7D%7D`
    </Link>
    <Link
      query={query => ({
        ...query,
        addThis: 'This is new!',
        removeThis: undefined
      })}
    >
      I will add `addThis='This is new!' and also remove the `removeThis` param to/from the query params on the current page
    </Link>
  </div>
);

Example: Using getActiveProps

The following link will be green with /about as the current location.

<Link
  to="/about"
  getActiveProps={location => ({
    style: { color: "green" }
  })}
>
  About
</Link>

Using activeType

As mentioned above, activeType configures when a link is considered "active", and when getActiveProps() is run and applied to the link. Below is a table demonstrating the various options and how they behave:

| full | hash

useLocation

Location

Redirect

createHistory

createMemorySource

Location API

Internnaly, there is only a single object, passed via context, that powers react-location. It contains both the current state and API for location and is the return result

navigate