Feature Request: Add `matchRoutes` Function

[brtvcl]

I’d like to request the addition of a matchRoutes function to Wouter. This function is available in react-router, and implementing it in Wouter should require minimal code.

Use Case

The matchRoutes function would allow users to find the active route based on the current location. This is particularly useful for handling layouts or route-based logic efficiently.

Example usage:

const routes = [
  { path: "/foo", component: <div>Foo</div> },
  { path: "/bar", component: <div>Bar</div>, layout: "red" },
];

const layouts = {
  default: ({ children }) => <div>{children}</div>,
  red: ({ children }) => <div style={{ backgroundColor: "red" }}>{children}</div>,
};

export default function App() {
  const [location] = useLocation();
  const activeRoute = matchRoutes(routes, location);
  const Layout = activeRoute?.layout ? layouts[activeRoute.layout] : layouts.default;

  return (
    <Layout>
      <Routes>
        {routes.map((route) => (
          <Route key={route.path} path={route.path} element={route.component} />
        ))}
      </Routes>
    </Layout>
  );
}

Example Implementation

This is the implementation I currently use in my project.
(~160 bytes, unminified)

import { parse } from "regexparam";

function matchRoutes(routes, location) {
  return routes.find((route) => {
    const regex = parse(route.path);
    return regex.pattern.test(location);
  });
}

Having this built into the library would prevent redundant loops (like in my example implementation) when matching routes, as Wouter itself already performs route matching internally.

Would love to hear your thoughts on this! Thanks for the awesome work on Wouter! 🚀

[max-mykhailenko]

Or simply, it would be ideal to have something like matchPath without array handling — no need to support a specific array format.

[molefrog]

This is the implementation I currently use in my project. (~160 bytes, unminified)

I am afraid the actual route matching in wouter is a bit more complex. However, we do export matchRoute function, could it be helpful?

import { useRouter, useLocation, matchRoute } from "wouter";

export function useMatchRoutes(routes) {
  const router = useRouter();
  const [location] = useLocation();

  // Go through each route and find the first match
  for (const route of routes) {
    const [matches, params] = matchRoute(
      router.parser,
      route.path,
      location,
      route.nest // optional, supports nested routes if needed
    );

    if (matches) {
      // Return both the matched route and the params
      return {
        route,
        params,
      };
    }
  }

  // Return null if no route matches
  return null;
}

[max-mykhailenko]

@molefrog thank you for your suggestion — it’s definitely interesting. However, it’s tied to the actual React component and can’t be executed outside of it.

What I’m looking for is a standalone function that can run in a Node.js environment before rendering the React app. Its purpose is to determine which template is currently active and provide the necessary assets accordingly.

Input: requestUrl, pathTemplate (e.g., users/:id)
Output: Boolean

[brtvcl]

I am afraid the actual route matching in wouter is a bit more complex. However, we do export matchRoute function, could it be helpful?

@molefrog It would work for my use case — but it doesn't offer any benefit to the thing I'm trying to avoid: having to loop through the routes myself to determine which one is active. If the solution is just a hook around matchRoutes, it doesn’t make much difference whether it's part of the library or implemented in my app.

What I’m looking for is a way to optimize that loop so it only happens once within the library. That way, I can simply access the active route directly and use that to drive layout or other route-specific logic. Some way to access which route path is matched internally (without calculating again) with a hook or a function would be nice.