API.md

API @nano-router/react

• Route
• Routes
• Router
• useLink
• useLocation
• useParams
• usePrompt
• useQueryParams
• useRouteName
• useRouter

Route

See @nano-router/routes.

Routes

See @nano-router/routes.

Router

A router provider that takes a history instance.

Creating a router for the browser history:

import React, { useMemo } from "react";
import { Router } from "@nano-router/react";
import { createBrowserHistory } from "@nano-router/history";

const App = () => {
  const history = useMemo(() => createBrowserHistory(), []);

  return (
    <Router history={history} routes={routes}>
      ...
    </Router>
  );
};

Creating a router for a memory history useful for testing:

import React, { useMemo } from "react";
import { Router } from "@nano-router/react";
import { createMemoryHistory } from "@nano-router/history";

const App = () => {
  const history = useMemo(
    () => createMemoryHistory({ initialEntries: ["/posts"] }),
    []
  );

  return (
    <Router history={history} routes={routes}>
      ...
    </Router>
  );
};

Navigate

The Navigate component changes the location to the given route when rendered. It's a component wrapper around the router.navigate function and accepts the same parameters as props.

Example usage:

<Navigate route="posts/new" />

<Navigate
  route="posts/edit"
  params={{ id: 42 }}
  queryParams={{ showSettings: true }}
  hash="#settings"
/>

Note this component's intended purpose is redirecting to default routes. See example Switch on the route name

NestedRouter

The NestedRouter component provides a nested router to a component sub-tree. You usually use the component to create memory routing for a sub-tree of the application.

If the nested memory router can't find the route being navigated to, it forward the navigation to the parent router. This allows you to provide isolated navigation patterns in parts of the application, while still having access to the global navigation.

Here we create a nested memory router with a separate set of routes. When you navigate with this React sub-tree this router will be active, if the route isn't found the parent router will be used.

import React, { useMemo } from "react";
import { NestedRouter } from "@nano-router/react";
import { createBrowserHistory } from "@nano-router/history";

const NestedNavigation = () => {
  const history = useMemo(
    () => createMemoryHistory({ initialEntries: ["/"] }),
    []
  );

  return (
    <NestedRouter history={history} routes={nestedRoutes}>
      ...
    </NestedRouter>
  );
};

useLink

A hook for getting link props for a given route.

Parameters:

• route: route name
• params: route parameters
• queryParams: URL query parameters
• hash: URL fragment

If only a string is given, it will be used as the route name.

Notice that all of these parameters are optional and will use the value from the current route.

import { useLink } from "@nano-router/react";

const PostList = () => {
  const showNewPost = useLink("posts/new");

  return <a {...showNewPost}>Create</a>;
};

You can get more control over the destination by providing an object:

const PostList = () => {
  const showEditPost = useLink({
    route: "posts/edit",
    params: { id: 42 },
    queryParams: { showSettings: true },
  });

  return <a {...showEditPost}>Create</a>;
};

Alternatively you can just supply the a url:

const PostList = () => {
  const showPost = useLink({
    url: "https://www.example.com/blog/42",
    target: "_blank",
  });

  return <a {...showPost}>Create</a>;
};

useLocation

A hook for getting the current history location:

const RouteLocation = () => {
  const { pathname, hash, search, state } = useLocation();

  const url = pathname + search + hash;

  return (
    <span>
      {url} - {state || "no state"}
    </span>
  );
};

useParams

A hook for getting the current route parameters:

const RouteParams = () => {
  const { id } = useParams();

  return <span>{id}</span>;
};

usePrompt

A hook that gives you a confirmation prompt when navigation is blocked.

This is useful to block navigation if you have dirty state that you would otherwise just loose.

The given parameter decides if the prompt is active.

Here we block navigation if the form has dirty state.

const Confirm = ({ confirmation }) => (
  <div class="modal">
    You have unsaved changes, do you want continue?
    <button onClick={confirmation.reject}>Cancel</button>
    <button onClick={confirmation.approve}>Continue</button>
  </div>
);

const Form = () => {
  const [name, setName] = useState("");
  const isDirty = name !== "";
  const confirmation = usePrompt(isDirty);

  const onChange = (e) => {
    setName(e.target.value);
  };

  const onSave = () => {
    router.navigate({
      route: "posts",
      state: { skipPrompt: true }, // Skipping all prompts
    });
  };

  return (
    <form>
      <input value={name} onChange={onChange} />
      <button onClick={onSave}>Save</button>
      {confirmation.isVisible && <Confirm confirmation={confirmation} />}
    </form>
  );
};

If you want to skip any prompts when navigating after a save:

router.navigate({
  route: "posts",
  state: { skipPrompt: true }, // Skipping all prompts
});

useQueryParams

A hook for getting the current query parameters:

const RouteQueryParams = () => {
  const { message } = useQueryParams();

  return <span>{message}</span>;
};

useRouteName

A hook for getting the current route name:

const RouteName = () => {
  const routeName = useRouteName();

  return <span>{routeName}</span>;
};

useRouter

A hook for getting the router instance:

const Location = () => {
  const router = useRouter();

  return <span>{router.location.pathname}</span>;
};

Notice getting the router doesn't subscribe to changes to the router, so your view wont get re-rendered when the route changes. You usually use the router to navigate from an event handler.