wouter

If your application is deployed to a subfolder, wrap your application with the <Router /> component and provide the base prop. This scopes all <Link /> href attributes and useLocation() return values to the base path. Nested routers will inherit and stack base paths.

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

const App = () => (
  <Router base="/app">
    {/* the link's href attribute will be "/app/users" */}
    <Link href="/users">Users</Link>

    <Route path="/users">The current path is /app/users!</Route>
  </Router>
);

For SSR, wrap your app in a top-level <Router /> and provide the ssrPath (the request path) and optionally ssrSearch (the query string). On the client, use hydrateRoot and ensure the <Router /> is present to match the server-rendered markup.

import { renderToString } from "react-dom/server";
import { Router } from "wouter";

const handleRequest = (req, res) => {
  const ssrContext = {};
  const prerendered = renderToString(
    <Router ssrPath={req.path} ssrSearch={req.search} ssrContext={ssrContext}>
      <App />
    </Router>
  );

  if (ssrContext.redirectTo) {
    res.redirect(ssrContext.redirectTo);
  } else {
    // respond with prerendered html
  }
};

You can control exactly when a view transition occurs by using the transition option. This can be done via the <Link> component or programmatically through location hooks.

To use this, your aroundNav handler must check for the transition property within the navigation options.

// Using the Link component
<Link to="/" transition>
  Home
</Link>;

// Using the useLocation hook
const [location, navigate] = useLocation();
navigate("/", { transition: true });

// Implementation of aroundNav to support opt-in
function aroundNav(navigate, to, options) {
  if (!document.startViewTransition) {
    navigate(to, options);
    return;
  }

  if (options?.transition) {
    document.startViewTransition(() => {
      flushSync(() => {
        navigate(to, options);
      });
    });
  } else {
    navigate(to, options);
  }
}

Adding the nest prop to a <Route /> creates a nesting context. Inside a nested route, the location is scoped to that route. This allows <Link /> components to use relative paths.

const App = () => (
  <Router base="/app">
    <Route path="/dashboard" nest>
      {/* the href is "/app/dashboard/users" */}
      <Link to="/users" />

      <Route path="/users">
        {/* Here `useLocation()` returns "/users"! */}
      </Route>
    </Route>
  </Router>
);

To use the View Transitions API, use the aroundNav prop on the <Router />. This allows you to wrap the navigate call within document.startViewTransition. You can trigger transitions selectively by passing { transition: true } in the navigation options.

import { flushSync } from "react-dom";
import { Router, type AroundNavHandler } from "wouter";

const aroundNav: AroundNavHandler = (navigate, to, options) => {
  if (!document.startViewTransition) {
    navigate(to, options);
    return;
  }

  document.startViewTransition(() => {
    flushSync(() => {
      navigate(to, options);
    });
  });
};

const App = () => (
  <Router aroundNav={aroundNav}>
    {/* Your routes here */}
  </Router>
);

To use wouter in a React project, install it via npm:

npm i wouter

If you are using Preact, install the dedicated Preact version instead:

npm i wouter-preact

To enable the browser's View Transitions API in wouter, you must provide an aroundNav handler to the <Router /> component. Because startViewTransition requires synchronous DOM updates, you must use flushSync from react-dom inside the transition callback to ensure the navigation occurs synchronously.

Note: This implementation requires react-dom to be installed in your project.

import { flushSync } from "react-dom";

function aroundNav(navigate, ...navArgs) {
  // Feature detection for older browsers
  if (!document.startViewTransition) {
    navigate(...navArgs);
    return;
  }

  document.startViewTransition(() => {
    flushSync(() => {
      navigate(...navArgs);
    });
  });
}

<Router aroundNav={aroundNav}>
  <App />
</Router>;

The <Link /> component accepts a function for the className prop. This function receives an active boolean which is true if the link matches the current route exactly. For more complex logic (like style or aria-current), use the useRoute hook to detect if a path is active.

// Using className function for exact matches
<Link className={(active) => (active ? "active" : "")}>Nav link</Link>

// Using useRoute for custom logic
const [isActive] = useRoute(props.href);

return (
  <Link {...props} asChild>
    <a style={isActive ? { color: "red" } : {}}>{props.children}</a>
  </Link>
);

To implement a fallback route (like a 404 page), use the <Switch /> component and place a <Route /> without a path prop as the last child. The order of children in <Switch /> matters; the default route must always be last.

import { Switch, Route } from "wouter";

<Switch>
  <Route path="/about">...</Route>
  <Route>404, Not Found!</Route>
</Switch>;

When testing, use memoryLocation from wouter/memory-location to provide a controlled location fixture. This allows you to render specific routes without a real browser environment. You can pass the returned hook and searchHook to the <Router />.

import { render } from "@testing-library/react";
import { memoryLocation } from "wouter/memory-location";

it("renders a user page", () => {
  const { hook, searchHook } = memoryLocation({ path: "/user/2", static: true });

  const { container } = render(
    <Router hook={hook} searchHook={searchHook}>
      <Route path="/user/:id">{(params) => <>User ID: {params.id}</>}</Route>
    </Router>
  );

  expect(container.innerHTML).toBe("User ID: 2");
});

By default, wouter handles routing with a specific pattern. If you need strict routing (e.g., treating /foo and /foo/ differently), provide a custom parser function to the <Router />. The parser must take a pattern string and return an object containing a pattern (RegExp) and keys (array of parsed key names).

import { pathToRegexp } from "path-to-regexp";

const strictParser = (path, loose) => {
  const keys = [];
  const pattern = pathToRegexp(path, keys, { strict: true, end: !loose });

  return {
    pattern,
    keys: keys.map((k) => k.name),
  };
};

const App = () => (
  <Router parser={strictParser}>
    <Route path="/foo">...</Route>
    <Route path="/foo/">...</Route>
  </Router>
);