or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

hooks.mdindex.mdlocation-strategies.mdrouting-components.md
tile.json

tessl/npm-wouter

Minimalist-friendly ~1.5KB router for React

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/wouter@3.7.x

To install, run

npx @tessl/cli install tessl/npm-wouter@3.7.0

index.mddocs/

Wouter

Wouter is a minimalist routing library for modern React and Preact applications that provides a comprehensive yet lightweight alternative to React Router at only ~2.1KB gzipped. It embraces React Hooks and offers both component-based routing through familiar Route, Link, Switch, and Redirect components, as well as hook-based APIs for granular control over routing behavior.

Package Information

  • Package Name: wouter
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install wouter

Core Imports

import { Route, Link, Switch, Redirect, Router } from "wouter";
import { useLocation, useRoute, useRouter, useParams, useSearch, useSearchParams, matchRoute } from "wouter";

For CommonJS:

const { Route, Link, Switch, Redirect, Router } = require("wouter");
const { useLocation, useRoute, useRouter, useParams, useSearch, useSearchParams, matchRoute } = require("wouter");

Additional location strategies:

import { useBrowserLocation } from "wouter/use-browser-location";
import { useHashLocation } from "wouter/use-hash-location"; 
import { memoryLocation } from "wouter/memory-location";

Basic Usage

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

function App() {
  return (
    <div>
      <nav>
        <Link href="/">Home</Link>
        <Link href="/users">Users</Link>
        <Link href="/about">About</Link>
      </nav>
      
      <Switch>
        <Route path="/" component={Home} />
        <Route path="/users/:id">
          {(params) => <User id={params.id} />}
        </Route>
        <Route path="/about" component={About} />
        <Route>404: Not Found</Route>
      </Switch>
    </div>
  );
}

Architecture

Wouter is built around several key components:

  • Components: Declarative routing components (Route, Link, Switch, Redirect, Router) for building navigation interfaces
  • Hooks: Programmatic hooks (useLocation, useRoute, useRouter, useParams) for accessing and controlling routing state
  • Location Strategies: Pluggable location hooks for different routing approaches (browser history, hash routing, memory routing)
  • Pattern Matching: Advanced route pattern matching with parameter extraction and nested routing support
  • SSR Support: Server-side rendering capabilities with static path support and context tracking

Capabilities

Routing Components

Core declarative components for building navigation interfaces and defining route structure. Includes Route for path matching, Link for navigation, Switch for exclusive routing, and Redirect for programmatic navigation.

function Route<T, RoutePath extends PathPattern>(
  props: RouteProps<T, RoutePath>
): ReturnType<FunctionComponent>;

function Link<H extends BaseLocationHook = BrowserLocationHook>(
  props: LinkProps<H>
): ReturnType<FunctionComponent>;

function Switch(props: SwitchProps): ReturnType<FunctionComponent>;

function Redirect<H extends BaseLocationHook = BrowserLocationHook>(
  props: RedirectProps<H>
): null;

function Router(props: RouterProps): ReturnType<FunctionComponent>;

Routing Components

Hooks

Programmatic hooks for accessing and controlling routing state, including location management, route matching, parameter extraction, and router configuration access.

function useLocation<H extends BaseLocationHook = BrowserLocationHook>(): HookReturnValue<H>;

function useRoute<T, RoutePath extends PathPattern>(
  pattern: RoutePath
): Match<T>;

function useRouter(): RouterObject;

function useParams<T = undefined>(): T extends string ? StringRouteParams<T> : T extends undefined ? DefaultParams : T;

function useSearch<H extends BaseSearchHook = BrowserSearchHook>(): ReturnType<H>;

function useSearchParams(): [URLSearchParams, SetSearchParams];

function matchRoute<T extends DefaultParams | undefined = undefined, RoutePath extends PathPattern = PathPattern>(
  parser: Parser,
  pattern: RoutePath,
  path: string,
  loose?: boolean
): Match<T extends DefaultParams ? T : RoutePath extends string ? StringRouteParams<RoutePath> : RegexRouteParams>;

Hooks

Location Strategies

Different location hook implementations for various routing strategies including browser history, hash-based routing, and memory-based routing for testing and SSR.

function useBrowserLocation(options?: { ssrPath?: Path }): [Path, typeof navigate];

function useHashLocation(options?: { ssrPath?: Path }): [Path, typeof navigate];

function memoryLocation(options?: {
  path?: Path;
  searchPath?: SearchString;
  static?: boolean;
  record?: boolean;
}): HookReturnValue;

Location Strategies

Types

type Path = string;
type PathPattern = string | RegExp;
type SearchString = string;

interface DefaultParams {
  readonly [paramName: string | number]: string | undefined;
}

type Params<T extends DefaultParams = DefaultParams> = T;

type Match<T extends DefaultParams = DefaultParams> = 
  | [true, Params<T>] 
  | [false, null];

interface RouterObject {
  readonly hook: BaseLocationHook;
  readonly searchHook: BaseSearchHook;
  readonly base: Path;
  readonly ownBase: Path;
  readonly parser: Parser;
  readonly ssrPath?: Path;
  readonly ssrSearch?: SearchString;
  readonly hrefs: HrefsFormatter;
}

type BaseLocationHook = (
  ...args: any[]
) => [Path, (path: Path, ...args: any[]) => any];

type BaseSearchHook = (...args: any[]) => SearchString;

type Parser = (route: Path, loose?: boolean) => { pattern: RegExp; keys: string[] };

type HrefsFormatter = (href: string, router: RouterObject) => string;

type SsrContext = {
  redirectTo?: Path;
};

type Primitive = string | number | bigint | boolean | null | undefined | symbol;

type HookReturnValue<H extends BaseLocationHook> = ReturnType<H>;

type HookNavigationOptions<H extends BaseLocationHook> = 
  EmptyInterfaceWhenAnyOrNever<
    NonNullable<Parameters<HookReturnValue<H>[1]>[1]>
  >;

type EmptyInterfaceWhenAnyOrNever<T> = 0 extends 1 & T
  ? {}
  : [T] extends [never]
  ? {}
  : T;

type URLSearchParamsInit = ConstructorParameters<typeof URLSearchParams>[0];

type SetSearchParams = (
  nextInit:
    | URLSearchParamsInit
    | ((prev: URLSearchParams) => URLSearchParamsInit),
  options?: { replace?: boolean; state?: any }
) => void;

// Route parameter types - these are parameterized based on route patterns
type StringRouteParams<T extends string> = Record<string, string | undefined> & {
  [param: number]: string | undefined;
};

type RegexRouteParams = { 
  [key: string | number]: string | undefined 
};