Awesome

navigo-react

Navigo router for React.

• navigo-react
  • Quick example
  • Navigating between routes
  • Components
    • Route
      • Route lifecycle functions
      • Navigating using named routes
    • Switch
    • Base
    • NotFound
    • Redirect
  • Hooks
    • useNavigo
    • useLocation
  • Other functions
    • configureRouter
    • reset
    • getRouter
  • Examples
    • Basic example
    • Accessing URL and GET parameters
    • Redirecting
    • Get data required by a Route
    • Block opening a route
    • Handling transitions

Quick example

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

export default function App() {
  return (
    <>
      <nav>
        <a href="/" data-navigo>Home</a>
        <a href="/package" data-navigo>Package</a>
      </nav>
      <Switch>
        <Route path="/package">
          Package documentation <a href="https://github.com/krasimir/navigo-react">here</a>.
        </Route>
        <Route path="/">
          NavigoReact is a router for React applications based on Navigo
          project.
        </Route>
      </Switch>
    </>
  );
}

Live demo here https://codesandbox.io/s/navigo-react-example-w9l1d.

Navigating between routes

The navigation in Navigo happens in two ways:

• Via <a> tags. The only requirement is to add data-navigo attribute to the link. For example <a href="/users/list" data-navigo>View users</a>. For more details on the exact API check out this page.
• Via the navigate or navigateByName methods. First you have to access the router with getRouter() and then use one of these two methods. For example:

import { getRouter } from 'navigo-react';

// Somewhere in your React components
<button onClick={() => getRouter().navigate('/users/list')}>
  View users
</button>

// or if you have a named route like
<Route path="/users/:id/:action" name="user">
  ...
</Route>

// Somewhere in your React components
<button
  onClick={
    () => getRouter().navigateByName('name', { id: 'xxx', action: 'view' })
  }>
  View users
</button>

Components

Route

<Route
  path="/user/:id"
  name="my-route-name"
  before={ (cb) => {} }
  after={ (cb) => {} }
  already={ (cb) => {} }
  leave={ (cb) => {} }>
  <p>Hey</p>
</Route>

The basic building block. Shortly, it's a component that renders its children based on the path prop.

Route lifecycle functions

The before, after, already and leave are functions that execute during the route resolving. They give you the opportunity to hook some logic to each one of this moments and pause/reject some of them. Each of this functions receive an object:

Where render gives you an opportunity to render the children of the <Route> by setting data into the Navigo context. For example:

import { Route, useNavigo } from "navigo-react";

function Print() {
  const { pic } = useNavigo();

  if (pic === null) {
    return <p>Loading ...</p>;
  }
  return <img src={pic} width="200" />;
}

export default function App() {
  async function before({ render, done }) {
    render({ pic: null });
    const res = await (
      await fetch("https://api.thecatapi.com/v1/images/search")
    ).json();
    render({ pic: res[0].url });
    done();
  }
  return (
    <>
      <nav>
        <a href="/cat" data-navigo>
          Get a cat fact
        </a>
      </nav>
      <Route path="/cat" before={before}>
        <Print />
      </Route>
    </>
  );
}

Pay attention to the before function inside the <App> component. render calls trigger rendering of the <Print> component with specific context which we can access via the useNavigo hook. Finally when we are ready we call done() to indicate that the routing could be fully resolved. Which means changing the browser's URL and potentially executing after or already lifecycle methods.

We can completely block the routing to specific place by calling done(false). For example:

export default function App() {
  const [authorized, loggedIn] = useState(false);
  const before = (cb) => {
    if (!authorized) {
      cb(false);
    } else {
      cb(true);
    }
  };

  return (
    <>
      <Route path="/user" before={before}>
        <User />
      </Route>
    </>
  );
}

(Full example here)

Navigating using named routes

Sometimes we need to construct a URL based on some data. The library offers an imperative API for that:

import { getRouter, Route } from "navigo-react";

export default function App() {
  return (
    <>
      <button
        onClick={() => {
          getRouter().navigateByName("my-user", { id: "xxx" });
        }}
      >
        Click me
      </button>
      <Route path="/user/:id" name="my-user">
        I'm a user
      </Route>
    </>
  );
}

https://codesandbox.io/s/navigo-react-named-routes-0h2bh

Switch

<Switch>
  <Route path="/about">About</Route>
  <Route path="/products">Products</Route>
  <Route path="*">Home</Route>
</Switch>

It forces the router to pick only one of the routes. Without this component multiple matches are possible. Like in the example above, if there is no <Switch> the "Home" string will be rendered no mather what because * matches every route.

Base

<Base path="/my/app" />

It specifies the root of your application. If you deploy you code at specific path you have to either use this component or configureRouter to tell Navigo where to start from.

NotFound

<NotFound>I'm 404 page.</NotFound>

It renders its content in case of a no match is found.

Redirect

<Redirect path="/a/new/place" />

It indirectly calls the navigate method of the router. Checkout redirecting example below.

Hooks

useNavigo

useNavigo is a hook that gives you access to the Navigo context. The main role of the context is to pass a Match object. It gives you access to the matched URL, URL and GET parameters. For example:

import { Route, useNavigo } from "navigo-react";

function User() {
  const { match } = useNavigo();

  return (
    <p>
      {match.params.action} user with id {match.data.id}
    </p>
  );
}

export default function App() {
  return (
    <>
      <a href="/user/xxx?action=save" data-navigo>
        Click me
      </a>
      <Route path="/user/:id">
        <User />
      </Route>
    </>
  );
}

The Navigo context also gives you access to key-value paris that we send via the router lifecycle functions. Check out this example Get data required by a Route.

useLocation

useLocation gives you a Match object that represents the current URL of the browser.

const match = useLocation();

Other functions

configureRouter

configureRouter could be used outside React and its purpose is to set the base root path of the router. Same as <Base> component.

configureRouter('/my/app');

reset

Calling this function means flushing all the registered routes.

getRouter

It gives you access to the Navigo router. Mostly you'll be using navigate and navigateByName functions. For example:

getRouter().navigate('/users/list');

Examples

Basic example

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

export default function App() {
  return (
    <>
      <nav>
        <a href="/" data-navigo>Home</a>
        <a href="/package" data-navigo>Package</a>
      </nav>
      <Switch>
        <Route path="/package">
          <ul>
            <li>Size: ~15KB</li>
            <li>Dependencies: no</li>
            <li>
              Documentation: <a href="https://github.com/krasimir/navigo-react">here</a>
            </li>
          </ul>
        </Route>
        <Route path="/">
          NavigoReact is a router for React applications based on Navigo project.
        </Route>
      </Switch>
    </>
  );
}

https://codesandbox.io/s/navigo-react-example-w9l1d

Accessing URL and GET parameters

import { Route, useNavigo } from "navigo-react";

function User() {
  const { match } = useNavigo();

  return (
    <p>
      {match.params.action} user with id {match.data.id}
    </p>
  );
}

export default function App() {
  return (
    <>
      <a href="/user/xxx?action=save" data-navigo>
        Click me
      </a>
      <Route path="/user/:id">
        <User />
      </Route>
    </>
  );
}

https://codesandbox.io/s/navigo-url-and-get-parameters-5few6

Redirecting

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

export default function App() {
  return (
    <>
      <nav>
        <a href="/user" data-navigo>
          View user
        </a>
      </nav>
      <Switch>
        <Route path="/user">
          <Redirect path="/foobar" />
        </Route>
        <Route path="/foobar">Hey user!</Route>
      </Switch>
    </>
  );
}

https://codesandbox.io/s/navigo-redirecting-cxzbb

Get data required by a Route

import { Route, useNavigo } from "navigo-react";

function Print() {
  const { pic } = useNavigo();

  if (pic === null) {
    return <p>Loading ...</p>;
  }
  return <img src={pic} width="200" />;
}

export default function App() {
  async function before({ render, done }) {
    render({ pic: null });
    const res = await (
      await fetch("https://api.thecatapi.com/v1/images/search")
    ).json();
    render({ pic: res[0].url });
    done();
  }
  return (
    <>
      <nav>
        <a href="/cat" data-navigo>
          Get a cat fact
        </a>
      </nav>
      <Route path="/cat" before={before}>
        <Print />
      </Route>
    </>
  );
}

https://codesandbox.io/s/navigo-before-lifecycle-function-hgeld

Block opening a route

The user can't go to /user route.

import { Route } from "navigo-react";

export default function App() {
  const before = ({ done }) => {
    done(false);
  };

  return (
    <>
      <nav>
        <a href="/user" data-navigo>
          Access user
        </a>
      </nav>
      <Route path="/user" before={before}>
        Hey user!!!
      </Route>
    </>
  );
}

https://codesandbox.io/s/navigo-block-routing-e2qvw

Handling transitions

import { Route, Switch, useNavigo } from "navigo-react";

const delay = (time) => new Promise((done) => setTimeout(done, time));

const leaveHook = async ({ render, done }) => {
  render({ leaving: true });
  await delay(900);
  done();
};

function Card({ children, bgColor }) {
  const { leaving } = useNavigo();
  const animation = `${
    leaving ? "out" : "in"
  } 1000ms cubic-bezier(1, -0.28, 0.28, 1.49)`;

  return (
    <div
      className={`card ${leaving ? "leaving" : ""}`}
      style={{ backgroundColor: bgColor, animation }}
    >
      <p>{children}</p>
    </div>
  );
}

export default function App() {
  return (
    <>
      <Switch>
        <Route path="/card-two" leave={leaveHook}>
          <Card bgColor="#254c6a">
            Card #2.
            <br />
            <a href="/" data-navigo>
              Click here
            </a>{" "}
            to go back
          </Card>
        </Route>
        <Route path="/" leave={leaveHook}>
          <Card bgColor="#1f431f">
            Welcome to the transition example.{" "}
            <a href="/card-two" data-navigo>
              Click here
            </a>{" "}
            to open the other card.
          </Card>
        </Route>
      </Switch>
    </>
  );
}

https://codesandbox.io/s/navigo-handling-transitions-ipprc