0
# Wouter
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: wouter
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install wouter`
10

11
## Core Imports
12

13
```typescript
14
import { Route, Link, Switch, Redirect, Router } from "wouter";
15
import { useLocation, useRoute, useRouter, useParams, useSearch, useSearchParams, matchRoute } from "wouter";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { Route, Link, Switch, Redirect, Router } = require("wouter");
22
const { useLocation, useRoute, useRouter, useParams, useSearch, useSearchParams, matchRoute } = require("wouter");
23
```
24

25
Additional location strategies:
26

27
```typescript
28
import { useBrowserLocation } from "wouter/use-browser-location";
29
import { useHashLocation } from "wouter/use-hash-location"; 
30
import { memoryLocation } from "wouter/memory-location";
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { Route, Link, Switch } from "wouter";
37

38
function App() {
39
  return (
40
    <div>
41
      <nav>
42
        <Link href="/">Home</Link>
43
        <Link href="/users">Users</Link>
44
        <Link href="/about">About</Link>
45
      </nav>
46
      
47
      <Switch>
48
        <Route path="/" component={Home} />
49
        <Route path="/users/:id">
50
          {(params) => <User id={params.id} />}
51
        </Route>
52
        <Route path="/about" component={About} />
53
        <Route>404: Not Found</Route>
54
      </Switch>
55
    </div>
56
  );
57
}
58
```
59

60
## Architecture
61

62
Wouter is built around several key components:
63

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

70
## Capabilities
71

72
### Routing Components
73

74
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.
75

76
```typescript { .api }
77
function Route<T, RoutePath extends PathPattern>(
78
  props: RouteProps<T, RoutePath>
79
): ReturnType<FunctionComponent>;
80

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

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

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

91
function Router(props: RouterProps): ReturnType<FunctionComponent>;
92
```
93

94
[Routing Components](./routing-components.md)
95

96
### Hooks
97

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

100
```typescript { .api }
101
function useLocation<H extends BaseLocationHook = BrowserLocationHook>(): HookReturnValue<H>;
102

103
function useRoute<T, RoutePath extends PathPattern>(
104
  pattern: RoutePath
105
): Match<T>;
106

107
function useRouter(): RouterObject;
108

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

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

113
function useSearchParams(): [URLSearchParams, SetSearchParams];
114

115
function matchRoute<T extends DefaultParams | undefined = undefined, RoutePath extends PathPattern = PathPattern>(
116
  parser: Parser,
117
  pattern: RoutePath,
118
  path: string,
119
  loose?: boolean
120
): Match<T extends DefaultParams ? T : RoutePath extends string ? StringRouteParams<RoutePath> : RegexRouteParams>;
121
```
122

123
[Hooks](./hooks.md)
124

125
### Location Strategies
126

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

129
```typescript { .api }
130
function useBrowserLocation(options?: { ssrPath?: Path }): [Path, typeof navigate];
131

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

134
function memoryLocation(options?: {
135
  path?: Path;
136
  searchPath?: SearchString;
137
  static?: boolean;
138
  record?: boolean;
139
}): HookReturnValue;
140
```
141

142
[Location Strategies](./location-strategies.md)
143

144
## Types
145

146
```typescript { .api }
147
type Path = string;
148
type PathPattern = string | RegExp;
149
type SearchString = string;
150

151
interface DefaultParams {
152
  readonly [paramName: string | number]: string | undefined;
153
}
154

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

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

161
interface RouterObject {
162
  readonly hook: BaseLocationHook;
163
  readonly searchHook: BaseSearchHook;
164
  readonly base: Path;
165
  readonly ownBase: Path;
166
  readonly parser: Parser;
167
  readonly ssrPath?: Path;
168
  readonly ssrSearch?: SearchString;
169
  readonly hrefs: HrefsFormatter;
170
}
171

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

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

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

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

182
type SsrContext = {
183
  redirectTo?: Path;
184
};
185

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

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

190
type HookNavigationOptions<H extends BaseLocationHook> = 
191
  EmptyInterfaceWhenAnyOrNever<
192
    NonNullable<Parameters<HookReturnValue<H>[1]>[1]>
193
  >;
194

195
type EmptyInterfaceWhenAnyOrNever<T> = 0 extends 1 & T
196
  ? {}
197
  : [T] extends [never]
198
  ? {}
199
  : T;
200

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

203
type SetSearchParams = (
204
  nextInit:
205
    | URLSearchParamsInit
206
    | ((prev: URLSearchParams) => URLSearchParamsInit),
207
  options?: { replace?: boolean; state?: any }
208
) => void;
209

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

215
type RegexRouteParams = { 
216
  [key: string | number]: string | undefined 
217
};
218
```