Wouter — Minimalist 2KB Router for React and Preact

Introduction

Wouter is a minimalist routing library for React and Preact weighing only 2.2KB. It provides a hooks-first API inspired by React Router but with a much smaller footprint and zero dependencies. It handles nested routes, wildcard patterns, hash-based routing, and server-side rendering.

What Wouter Does

• Matches URL paths to components using a declarative Route API
• Provides hooks like useRoute, useLocation, and useParams for programmatic routing
• Supports nested routing and base path configuration for sub-applications
• Handles wildcard and named parameter patterns in route paths
• Works with hash-based URLs and custom location hooks for memory routing

Architecture Overview

Wouter uses a single location hook (useLocation) as its source of truth, subscribing to the browser History API. Route matching uses a path-to-regexp style pattern compiler. Components re-render only when their specific route match changes, avoiding unnecessary updates. The library ships no context providers by default; the Router wrapper is only needed for base paths or custom location hooks.

Self-Hosting & Configuration

• Install via npm: npm install wouter
• Import Route, Link, Switch, and hooks directly from 'wouter'
• For Preact, import from 'wouter-preact' instead
• Configure base paths with <Router base="/app"> for sub-applications
• Use memoryLocation for testing or non-browser environments

Key Features

• Only 2.2KB gzipped with zero dependencies
• Hooks-first design with useRoute, useLocation, useParams, and useSearch
• Full TypeScript support with typed route parameters
• Works with React 16.8+, React 18, and Preact
• SSR-compatible with server-side location hooks

Comparison with Similar Tools

• React Router — full-featured router with loaders and actions; much larger bundle at 13KB+
• TanStack Router — type-safe with built-in search params; heavier, more opinionated
• Next.js App Router — file-system based routing; tied to the Next.js framework
• @reach/router — accessible-first router; merged into React Router v6
• navigo — vanilla JS router; no React integration

FAQ

Q: Can Wouter replace React Router in an existing project? A: For most use cases, yes. Wouter covers Route, Link, Switch, Redirect, and common hooks. Advanced features like loaders or data fetching are not included.

Q: Does Wouter support lazy-loaded routes? A: Yes. Wrap your route components with React.lazy and Suspense as you would with any React component.

Q: How do I access query parameters? A: Use the useSearch hook, which returns the raw search string. Parse it with URLSearchParams.

Q: Is Wouter compatible with React Server Components? A: Wouter hooks use client-side state, so route components using hooks need the "use client" directive in RSC environments.

Sources

• https://github.com/molefrog/wouter
• https://www.npmjs.com/package/wouter