wouter

<div align="center"> <img src="assets/logo.svg" width="80" alt="Wouter — a super-tiny React router (logo by Katya Simacheva)" /> </div> <br /> <div align="center"> <a href="https://npmjs.org/package/wouter"><img alt="npm" src="https://img.shields.io/npm/v/wouter.svg?color=black&labelColor=888" /></a> <a href="https://travis-ci.org/molefrog/wouter"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/molefrog/wouter/size.yml?color=black&labelColor=888&label=2.5KB+limit" /></a> <a href="https://codecov.io/gh/molefrog/wouter"><img alt="Coverage" src="https://img.shields.io/codecov/c/github/molefrog/wouter.svg?color=black&labelColor=888" /></a> <a href="https://www.npmjs.com/package/wouter"><img alt="Coverage" src="https://img.shields.io/npm/dm/wouter.svg?color=black&labelColor=888" /></a> <a href="https://pr.new/molefrog/wouter"><img alt="Edit in StackBlitz IDE" src="https://img.shields.io/badge/StackBlitz-New%20PR-black?labelColor=888" /></a> </div> <div align="center"> <b>wouter</b> is a tiny router for modern React and Preact apps that relies on Hooks. <br /> A router you wanted so bad in your project!<br> </div>

Features

⚠️ These docs are for wouter v3 only. Please find the documentation for wouter@2.12.0 here

<img src="assets/wouter.svg" align="right" width="250" alt="by Katya Simacheva" />

• Minimum dependencies, only 2.1 KB gzipped vs 18.7KB React Router.
• Supports both React and Preact! Read "Preact support" section for more details.
• No top-level <Router /> component, it is fully optional.
• Mimics React Router's best practices by providing familiar Route, Link, Switch and Redirect components.
• Has hook-based API for more granular control over routing (like animations): useLocation, useRoute and useRouter.

developers :sparkling_heart: wouter

... I love Wouter. It’s tiny, fully embraces hooks, and has an intuitive and barebones API. I can accomplish everything I could with react-router with Wouter, and it just feels more minimalist while not being inconvenient.

Matt Miller, An exhaustive React ecosystem for 2020

Wouter provides a simple API that many developers and library authors appreciate. Some notable projects that use wouter: Ultra, React-three-fiber, Sunmao UI, Million and many more.

Table of Contents

• Getting Started

  • Browser Support

• Wouter API

  • The list of methods available

• Hooks API

  • useRoute: route matching and parameters
  • useLocation: working with the history
    • Additional navigation parameters
    • Customizing the location hook
  • useParams: extracting matched parameters
  • useSearch: query strings
  • useRouter: accessing the router object

• Component API

  • <Route path={pattern} />
    • Route nesting
  • <Link href={path} />
  • <Switch />
  • <Redirect to={path} />
  • <Router hook={hook} parser={fn} base={basepath} />

• FAQ and Code Recipes

  • I deploy my app to the subfolder. Can I specify a base path?
  • How do I make a default route?
  • How do I make a link active for the current route?
  • Are strict routes supported?
  • Are relative routes and links supported?
  • Can I initiate navigation from outside a component?
  • Can I use wouter in my TypeScript project?
  • How can add animated route transitions?
  • Preact support?
  • Server-side Rendering support (SSR)?
  • How do I configure the router to render a specific route in tests?
  • 1KB is too much, I can't afford it!

• Acknowledgements

Getting Started

First, add wouter to your project.

npm i wouter

Or, if you're using Preact the use the following command npm i wouter-preact.

Check out this simple demo app below. It doesn't cover hooks and other features such as nested routing, but it's a good starting point for those who are migrating from React Router.

import { Link, Route, Switch } from "wouter";

const App = () => (
  <>
    <Link href="/users/1">Profile</Link>

    <Route path="/about">About Us</Route>

    {/* 
      Routes below are matched exclusively -
      the first matched route gets rendered
    */}
    <Switch>
      <Route path="/inbox" component={InboxPage} />

      <Route path="/users/:name">
        {(params) => <>Hello, {params.name}!</>}
      </Route>

      {/* Default route in a switch */}
      <Route>404: No such page!</Route>
    </Switch>
  </>
);

Browser Support

This library is designed for ES2020+ compatibility. If you need to support older browsers, make sure that you transpile node_modules. Additionally, the minimum supported TypeScript version is 4.1 in order to support route parameter inference.

Wouter API

Wouter comes with three kinds of APIs: low-level standalone location hooks, hooks for routing and pattern matching and more traditional component-based API similar to React Router's one.

You are free to choose whatever works for you: use location hooks when you want to keep your app as small as possible and don't need pattern matching; use routing hooks when you want to build custom routing components; or if you're building a traditional app with pages and navigation — components might come in handy.

Check out also FAQ and Code Recipes for more advanced things like active links, default routes, server-side rendering etc.

The list of methods available

Location Hooks

These can be used separately from the main module and have an interface similar to useState. These hooks don't support nesting, base path, route matching.

• import { useBrowserLocation } from "wouter/use-browser-location" — allows to manipulate current location in the browser's address bar, a tiny wrapper around the History API.
• import { useHashLocation } from "wouter/use-hash-location" — similarly, gets location from the hash part of the address, i.e. the string after a #.
• import { memoryLocation } from "wouter/memory-location" — an in-memory location hook with history support, external navigation and immutable mode for testing. Note the module name because it is a high-order hook. See how memory location can be used in testing.

Routing Hooks

Import from wouter module.

• useRoute — shows whether or not current page matches the pattern provided.
• useLocation — allows to manipulate current router's location, by default subscribes to browser location. Note: this isn't the same as useBrowserLocation, read below.
• useParams — returns an object with parameters matched from the closest route.
• useSearch — returns a search string – everything that goes after the ?.
• useRouter — returns a global router object that holds the configuration. Only use it if you want to customize the routing.

Components

Import from wouter module.

• <Route /> — conditionally renders a component based on a pattern.
• <Link /> — wraps <a>, allows to perfom a navigation.
• <Switch /> — exclusive routing, only renders the first matched route.
• <Redirect /> — when rendered, performs an immediate navigation.
• <Router /> — an optional top-level component for advanced routing configuration.

Hooks API

useRoute: route matching and parameters

Checks if the current location matches the pattern provided and returns an object with parameters. This is powered by a wonderful regexparam library, so all its pattern syntax is fully supported.

You can use useRoute to perform manual routing or implement custom logic, such as route transitions, etc.

import { useRoute } from "wouter";

const Users = () => {
  // `match` is a boolean
  const [match, params] = useRoute("/users/:name");

  if (match) {
    return <>Hello, {params.name}!</>;
  } else {
    return null;
  }
};

A quick cheatsheet of what types of segments are supported:

useRoute("/app/:page");
useRoute("/app/:page/:section");

// optional parameter, matches "/en/home" and "/home"
useRoute("/:locale?/home");

// suffixes
useRoute("/movies/:title.(mp4|mov)");

// wildcards, matches "/app", "/app-1", "/app/home"
useRoute("/app*");

// optional wildcards, matches "/orders", "/orders/"
// and "/orders/completed/list"
useRoute("/orders/*?");

// regex for matching complex patterns,
// matches "/hello:123"
useRoute(/^[/]([a-z]+):([0-9]+)[/]?$/);
// and with named capture groups
useRoute(/^[/](?<word>[a-z]+):(?<num>[0-9]+)[/]?$/);

The second item in the pair params is an object with parameters or null if there was no match. For wildcard segments the parameter name is "*":

// wildcards, matches "/app", "/app-1", "/app/home"
const [match, params] = useRoute("/app*");

if (match) {
  // "/home" for "/app/home"
  const page = params["*"];
}

useLocation: working with the history

To get the current path and navigate between pages, call the useLocation hook. Similarly to useState, it returns a value and a setter: the component will re-render when the location changes and by calling navigate you can update this value and perform navigation.

By default, it uses useBrowserLocation under the hood, though you can configure this in a top-level Router component (for example, if you decide at some point to switch to a hash-based routing). useLocation will also return scoped path when used within nested routes or with base path setting.

import { useLocation } from "wouter";

const CurrentLocation = () => {
  const [location, setLocation] = useLocation();

  return (
    <div>
      {`The current page is: ${location}`}
      <a onClick={() => setLocation("/somewhere")}>Click to update</a>
    </div>
  );
};

All the components internally call the useLocation hook.

Additional navigation parameters

The setter method of useLocation can also accept an optional object with parameters to control how the navigation update will happen.

When browser location is used (default), useLocation hook accepts replace flag to tell the hook to modify the current history entry instead of adding a new one. It is the same as calling replaceState.

const [location, navigate] = useLocation();

navigate("/jobs"); // `pushState` is used
navigate("/home", { replace: true }); // `replaceState` is used

Additionally, you can provide a state option to update history.state while navigating:

navigate("/home", { state: { modal: "promo" } });

history.state; // { modal: "promo" }

Customizing the location hook

By default, wouter uses useLocation hook that reacts to pushState and replaceState navigation via useBrowserLocation.

To customize this, wrap your app in a Router component:

import { Router, Route } from "wouter";
import { useHashLocation } from "wouter/use-hash-location";

const App = () => (
  <Router hook={useHashLocation}>
    <Route path="/about" component={About} />
    ...
  </Router>
);

Because these hooks have return values similar to useState, it is easy and fun to build your own location hooks: useCrossTabLocation, useLocalStorage, useMicroFrontendLocation and whatever routing logic you want to support in the app. Give it a try!

useParams: extracting matched parameters

This hook allows you to access the parameters exposed through matching dynamic segments. Internally, we simply wrap your components in a context provider allowing you to access this data anywhere within the Route component.

This allows you to avoid "prop drilling" when dealing with deeply nested components within the route. Note: useParams will only extract parameters from the closest parent route.

import { Route, useParams } from "wouter";

const User = () => {
  const params = useParams();

  params.id; // "1"

  // alternatively, use the index to access the prop
  params[0]; // "1"
};

<Route path="/user/:id" component={User}> />

It is the same for regex paths. Capture groups can be accessed by their index, or if there is a named capture group, that can be used instead.

import { Route, useParams } from "wouter";

const User = () => {
  const params = useParams();

  params.id; // "1"
  params[0]; // "1"
};

<Route path={/^[/]user[/](?<id>[0-9]+)[/]?$/} component={User}> />

useSearch: query strings

Use this hook to get the current search (query) string value. It will cause your component to re-render only when the string itself and not the full location updates. The search string returned does not contain a ? character.

import { useSearch } from "wouter";

// returns "tab=settings&id=1"
// the hook for extracting search parameters is coming soon!
const searchString = useSearch();

For the SSR, use ssrSearch prop passed to the router.

<Router ssrSearch={request.search}>{/* SSR! */}</Router>

Refer to Server-Side Rendering for more info on rendering and hydration.

useRouter: accessing the router object

If you're building advanced integration, for example custom location hook, you might want to get access to the global router object. Router is a simple object that holds routing options that you configure in the Router component.

import { useRouter } from "wouter";

const Custom = () => {
  const