Added support for regular expressions in paths

README.md

@@ -218,6 +218,12 @@ 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 `"*"`:
@@ -317,6 +323,21 @@ const User = () => {
 <Route path="/user/:id" component={User}> />
 ```
 
+For regex paths, parameters are accessible as indices or through their group name.
+
+```js
+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.
@@ -421,6 +442,10 @@ If you call `useLocation()` inside the last route, it will return `/orders` and
 </Route>
 ```
 
+**Note:** The `nest` prop has no effect on regexes passed in.
+It will only determine if nested routes will match the rest of path or match against the same path.
+To make a strict path regex, use regex techniques like `[/]?$` (this matches an optional end slash and the end of the string).
+
 ### `<Link href={path} />`
 
 Link component renders an `<a />` element that, when clicked, performs a navigation.

package.json

@@ -8,7 +8,7 @@
     "packages/wouter-preact"
   ],
   "scripts": {
-    "fix:p": "prettier --write './**/*.(js|ts){x,}'",
+    "fix:p": "prettier --write \"./**/*.(js|ts){x,}\"",
     "test": "vitest",
     "size": "size-limit",
     "build": "npm run build -ws",

packages/wouter-preact/types/index.d.ts

@@ -29,11 +29,13 @@ export * from "./router.js";
 
 import { RouteParams } from "regexparam";
 
+export type RegexRouteParams = { [key: string | number]: string | undefined };
+
 /**
  * Route patterns and parameters
  */
 export interface DefaultParams {
-  readonly [paramName: string]: string | undefined;
+  readonly [paramName: string | number]: string | undefined;
 }
 
 export type Params<T extends DefaultParams = DefaultParams> = T;
@@ -57,23 +59,33 @@ export interface RouteComponentProps<T extends DefaultParams = DefaultParams> {
 
 export interface RouteProps<
   T extends DefaultParams | undefined = undefined,
-  RoutePath extends Path = Path
+  RoutePath extends Path | RegExp = Path | RegExp
 > {
   children?:
     | ((
-        params: T extends DefaultParams ? T : RouteParams<RoutePath>
+        params: T extends DefaultParams
+          ? T
+          : RoutePath extends string
+          ? RouteParams<RoutePath>
+          : RegexRouteParams
       ) => ComponentChildren)
     | ComponentChildren;
   path?: RoutePath;
   component?: ComponentType<
-    RouteComponentProps<T extends DefaultParams ? T : RouteParams<RoutePath>>
+    RouteComponentProps<
+      T extends DefaultParams
+        ? T
+        : RoutePath extends string
+        ? RouteParams<RoutePath>
+        : RegexRouteParams
+    >
   >;
   nest?: boolean;
 }
 
 export function Route<
   T extends DefaultParams | undefined = undefined,
-  RoutePath extends Path = Path
+  RoutePath extends Path | RegExp = Path | RegExp
 >(props: RouteProps<T, RoutePath>): ReturnType<FunctionComponent>;
 
 /*
@@ -143,10 +155,16 @@ export function useRouter(): RouterObject;
 
 export function useRoute<
   T extends DefaultParams | undefined = undefined,
-  RoutePath extends Path = Path
+  RoutePath extends Path | RegExp = Path | RegExp
 >(
   pattern: RoutePath
-): Match<T extends DefaultParams ? T : RouteParams<RoutePath>>;
+): Match<
+  T extends DefaultParams
+    ? T
+    : RoutePath extends string
+    ? RouteParams<RoutePath>
+    : RegexRouteParams
+>;
 
 export function useLocation<
   H extends BaseLocationHook = BrowserLocationHook

packages/wouter-preact/types/router.d.ts

@@ -5,7 +5,10 @@ import {
   BaseSearchHook,
 } from "./location-hook.js";
 
-export type Parser = (route: Path) => { pattern: RegExp; keys: string[] };
+export type Parser = (
+  route: Path,
+  loose?: boolean
+) => { pattern: RegExp; keys: string[] };
 
 export type HrefsFormatter = (href: string, router: RouterObject) => string;
 

packages/wouter/src/index.js

@@ -79,21 +79,45 @@ export const useSearch = () => {
 };
 
 const matchRoute = (parser, route, path, loose) => {
+  // if the input is a regexp, skip parsing
+  const { pattern, keys } = (() => {
+    if (route instanceof RegExp) {
+      return { keys: false, pattern: route };
+    }
+    return parser(route || "*", loose);
+  })();
+
+  // array destructuring loses keys, so this is done in two steps
+  const result = pattern.exec(path) || [];
+
   // when parser is in "loose" mode, `$base` is equal to the
   // first part of the route that matches the pattern
   // (e.g. for pattern `/a/:b` and path `/a/1/2/3` the `$base` is `a/1`)
   // we use this for route nesting
-  const { pattern, keys } = parser(route || "*", loose);
-  const [$base, ...matches] = pattern.exec(path) || [];
+  const [$base, ...matches] = result;
 
   return $base !== undefined
     ? [
         true,
 
-        // an object with parameters matched, e.g. { foo: "bar" } for "/:foo"
-        // we "zip" two arrays here to construct the object
-        // ["foo"], ["bar"] → { foo: "bar" }
-        Object.fromEntries(keys.map((key, i) => [key, matches[i]])),
+        (() => {
+          /// for regex paths, `keys` will always be false
+          if (keys !== false) {
+            // an object with parameters matched, e.g. { foo: "bar" } for "/:foo"
+            // we "zip" two arrays here to construct the object
+            // ["foo"], ["bar"] → { foo: "bar" }
+            return Object.fromEntries(keys.map((key, i) => [key, matches[i]]));
+          }
+
+          // convert the array to an instance of object
+          // this makes it easier to integrate with the existing param implementation
+          let obj = { ...matches };
+
+          // merge named capture groups with matches array
+          result.groups && Object.assign(obj, result.groups);
+
+          return obj;
+        })(),
 
         // the third value if only present when parser is in "loose" mode,
         // so that we can extract the base path for nested routes

packages/wouter/test/parser.test.tsx

@@ -7,7 +7,7 @@ import { Router, useRouter, useRoute, Parser } from "wouter";
 import { memoryLocation } from "wouter/memory-location";
 
 // Custom parser that uses `path-to-regexp` instead of `regexparam`
-const pathToRegexpParser: Parser = (route: string) => {
+const pathToRegexpParser: Parser = (route: string | RegExp) => {
   const keys: Key[] = [];
   const pattern = pathToRegexp(route, keys);
 

packages/wouter/test/route.test-d.tsx

@@ -8,9 +8,9 @@ describe("`path` prop", () => {
     assertType(<Route />);
   });
 
-  it("should be a string", () => {
+  it("should be a string or RegExp", () => {
     let a: ComponentProps<typeof Route>["path"];
-    expectTypeOf(a).toMatchTypeOf<string | undefined>();
+    expectTypeOf(a).toMatchTypeOf<string | RegExp | undefined>();
   });
 });
 

packages/wouter/test/route.test.tsx

@@ -95,3 +95,47 @@ it("supports `base` routers with relative path", () => {
 
   unmount();
 });
+
+it("supports `path` prop with regex", () => {
+  const result = testRouteRender(
+    "/foo",
+    <Route path={/[/]foo/}>
+      <h1>Hello!</h1>
+    </Route>
+  );
+
+  expect(result.findByType("h1").props.children).toBe("Hello!");
+});
+
+it("supports regex path named params", () => {
+  const result = testRouteRender(
+    "/users/alex",
+    <Route path={/[/]users[/](?<name>[a-z]+)/}>
+      {(params) => <h1>{params.name}</h1>}
+    </Route>
+  );
+
+  expect(result.findByType("h1").props.children).toBe("alex");
+});
+
+it("supports regex path anonymous params", () => {
+  const result = testRouteRender(
+    "/users/alex",
+    <Route path={/[/]users[/]([a-z]+)/}>
+      {(params) => <h1>{params[0]}</h1>}
+    </Route>
+  );
+
+  expect(result.findByType("h1").props.children).toBe("alex");
+});
+
+it("rejects when a path does not match the regex", () => {
+  const result = testRouteRender(
+    "/users/1234",
+    <Route path={/[/]users[/](?<name>[a-z]+)/}>
+      {(params) => <h1>{params.name}</h1>}
+    </Route>
+  );
+
+  expect(() => result.findByType("h1")).toThrow();
+});

packages/wouter/test/use-route.test.tsx

@@ -1,5 +1,5 @@
 import { renderHook, act } from "@testing-library/react";
-import { useRoute, Match, Router } from "wouter";
+import { useRoute, Match, Router, RegexRouteParams } from "wouter";
 import { it, expect } from "vitest";
 import { memoryLocation } from "wouter/memory-location";
 
@@ -108,6 +108,14 @@ it("ignores escaped slashes", () => {
   });
 });
 
+it("supports regex patterns", () => {
+  assertRoute(/[/]foo/, "/foo", {});
+  assertRoute(/[/]([a-z]+)/, "/bar", { 0: "bar" });
+  assertRoute(/[/]([a-z]+)/, "/123", false);
+  assertRoute(/[/](?<param>[a-z]+)/, "/bar", { 0: "bar", param: "bar" });
+  assertRoute(/[/](?<param>[a-z]+)/, "/123", false);
+});
+
 it("reacts to pattern updates", () => {
   const { result, rerender } = renderHook(
     ({ pattern }: { pattern: string }) => useRoute(pattern),
@@ -170,7 +178,7 @@ it("reacts to location updates", () => {
  */
 
 const assertRoute = (
-  pattern: string,
+  pattern: string | RegExp,
   location: string,
   rhs: false | Match | Record<string, string | undefined>
 ) => {

packages/wouter/types/index.d.ts

@@ -33,11 +33,13 @@ export * from "./router.js";
 
 import { RouteParams } from "regexparam";
 
+export type RegexRouteParams = { [key: string | number]: string | undefined };
+
 /**
  * Route patterns and parameters
  */
 export interface DefaultParams {
-  readonly [paramName: string]: string | undefined;
+  readonly [paramName: string | number]: string | undefined;
 }
 
 export type Params<T extends DefaultParams = DefaultParams> = T;
@@ -61,23 +63,33 @@ export interface RouteComponentProps<T extends DefaultParams = DefaultParams> {
 
 export interface RouteProps<
   T extends DefaultParams | undefined = undefined,
-  RoutePath extends Path = Path
+  RoutePath extends Path | RegExp = Path | RegExp
 > {
   children?:
     | ((
-        params: T extends DefaultParams ? T : RouteParams<RoutePath>
+        params: T extends DefaultParams
+          ? T
+          : RoutePath extends string
+          ? RouteParams<RoutePath>
+          : RegexRouteParams
       ) => ReactNode)
     | ReactNode;
   path?: RoutePath;
   component?: ComponentType<
-    RouteComponentProps<T extends DefaultParams ? T : RouteParams<RoutePath>>
+    RouteComponentProps<
+      T extends DefaultParams
+        ? T
+        : RoutePath extends string
+        ? RouteParams<RoutePath>
+        : RegexRouteParams
+    >
   >;
   nest?: boolean;
 }
 
 export function Route<
   T extends DefaultParams | undefined = undefined,
-  RoutePath extends Path = Path
+  RoutePath extends Path | RegExp = Path | RegExp
 >(props: RouteProps<T, RoutePath>): ReturnType<FunctionComponent>;
 
 /*
@@ -150,10 +162,16 @@ export function useRouter(): RouterObject;
 
 export function useRoute<
   T extends DefaultParams | undefined = undefined,
-  RoutePath extends Path = Path
+  RoutePath extends Path | RegExp = Path | RegExp
 >(
   pattern: RoutePath
-): Match<T extends DefaultParams ? T : RouteParams<RoutePath>>;
+): Match<
+  T extends DefaultParams
+    ? T
+    : RoutePath extends string
+    ? RouteParams<RoutePath>
+    : RegexRouteParams
+>;
 
 export function useLocation<
   H extends BaseLocationHook = BrowserLocationHook

packages/wouter/types/router.d.ts

@@ -5,7 +5,10 @@ import {
   BaseSearchHook,
 } from "./location-hook.js";
 
-export type Parser = (route: Path) => { pattern: RegExp; keys: string[] };
+export type Parser = (
+  route: Path,
+  loose?: boolean
+) => { pattern: RegExp; keys: string[] };
 
 export type HrefsFormatter = (href: string, router: RouterObject) => string;