wouter

Minimalist-friendly ~1.5KB router for React

weekly downloads974K

versionv3.9.0

licenseUnlicense

categoryfrontend

reactpreactroutertinyroutinghooksuseLocation

Overview

wouter is a minimalist routing solution for React and Preact applications that weighs approximately 1.5KB with no external dependencies. Built entirely around React Hooks (v16.8+), it provides essential routing functionality through a clean API consisting of components like <Route> and <Link>, plus hooks like useRoute, useLocation, useParams, and useSearch. The library deliberately avoids feature bloat to maintain its tiny footprint while delivering the core 80% of routing needs most single-page applications require.

The package exists as a direct response to the growing bundle sizes of full-featured routers like React Router. Many applications don't need advanced features like code splitting, data loaders, or complex nested routing configurations, yet pay the cost in kilobytes. wouter targets developers building performance-critical applications, marketing sites, or projects where every byte counts—particularly useful for mobile-first experiences or applications served to users on slow networks.

With nearly a million weekly downloads, wouter has gained traction among teams that value simplicity and bundle size optimization. It's particularly popular in the Preact ecosystem where developers already prioritize minimal footprints. The library is released under the Unlicense, making it fully public domain and suitable for any project without licensing concerns. While it won't replace React Router in complex enterprise applications, it excels in scenarios where straightforward path matching and navigation are sufficient.

wouter supports both component-based declarative routing and imperative hook-based patterns, giving developers flexibility in how they structure navigation logic. It includes pattern matching with dynamic segments, optional parameters, regex constraints, and server-side rendering support through custom location hooks—all while maintaining its commitment to staying under 2KB gzipped.

Quick Start

typescript

import { Route, Link, Switch, useLocation, useParams } from 'wouter';
import { useState } from 'react';

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" component={UserList} />
        <Route path="/users/:id">
          {params => <UserProfile userId={params.id} />}
        </Route>
        <Route path="/about">{() => <h1>About Us</h1>}</Route>
        <Route>{() => <NotFound />}</Route>
      </Switch>
    </div>
  );
}

function Home() {
  const [location, setLocation] = useLocation();
  return (
    <div>
      <h1>Home Page</h1>
      <button onClick={() => setLocation('/users/42')}>
        Go to User 42
      </button>
    </div>
  );
}

function UserList() {
  const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>
          <Link href={`/users/${user.id}`}>{user.name}</Link>
        </li>
      ))}
    </ul>
  );
}

function UserProfile({ userId }) {
  const params = useParams();
  const [user, setUser] = useState(null);
  
  useState(() => {
    fetch(`/api/users/${userId}`)
      .then(r => r.json())
      .then(setUser);
  }, [userId]);

  return <h2>User Profile: {user?.name || userId}</h2>;
}

function NotFound() {
  return <h1>404 - Page Not Found</h1>;
}

export default App;

Use Cases

Small to medium single-page applications: Projects like marketing websites, documentation sites, or product landing pages that need multiple views but don't require nested routing, data loaders, or route guards. wouter provides clean URL management without the overhead of larger routing libraries.

Performance-critical mobile applications: Mobile-first web apps where bundle size directly impacts load times and user retention. Every kilobyte matters on 3G connections, making wouter's 1.5KB footprint attractive compared to 10KB+ alternatives.

Preact applications: Preact developers who've already chosen a lightweight React alternative naturally gravitate toward wouter to maintain consistency in their bundle optimization strategy. The library works seamlessly with Preact's smaller API surface.

Micro-frontends or embedded widgets: When building embeddable components or micro-frontend modules that need internal routing but can't afford to ship a full router in each bundle. wouter's small size minimizes conflicts and overhead when multiple instances might exist on a page.

Progressive migration from server-rendered apps: Teams modernizing traditional server-side applications can introduce client-side routing incrementally with wouter's minimal footprint and server-side rendering support through staticLocationHook, avoiding a full framework rewrite.

Pros & Cons

Pros

+Extremely small bundle size (~1.5KB gzipped) with zero dependencies, ideal for performance-sensitive applications
+Modern hook-based API provides low-level control for custom navigation logic, animations, and conditional rendering
+Works seamlessly with both React and Preact without configuration changes or adapters
+Simple mental model with no complex nested route configurations or special components to learn
+Server-side rendering support through custom location hooks enables universal applications

Cons

−No React Native support—strictly for web applications using browser history or custom location implementations
−Missing advanced features like route guards, data loaders, code splitting utilities, or nested route layouts
−No HashRouter or MemoryRouter built-in, requiring custom location hooks for non-standard history management
−Limited TypeScript support compared to newer routers built with TypeScript-first APIs
−Requires ES6+ browser support or manual Babel configuration for older environments like IE11

Alternatives

react-routerv7.13.0

Declarative routing for React

frontendreactrouter

23.6M / week

react-router-domv7.13.0

Declarative routing for React web applications

frontendreactrouter

20.5M / week

@tanstack/react-routerv1.161.1

Modern and scalable routing for React applications

meta-frameworkreactlocation

1.9M / week

Comparisons

react-router-dom vs wouter

frontend

Install

bash

npm install wouter

bash

pnpm add wouter

bash

bun add wouter

Overview

Quick Start

typescript

import { Route, Link, Switch, useLocation, useParams } from 'wouter';
import { useState } from 'react';

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" component={UserList} />
        <Route path="/users/:id">
          {params => <UserProfile userId={params.id} />}
        </Route>
        <Route path="/about">{() => <h1>About Us</h1>}</Route>
        <Route>{() => <NotFound />}</Route>
      </Switch>
    </div>
  );
}

function Home() {
  const [location, setLocation] = useLocation();
  return (
    <div>
      <h1>Home Page</h1>
      <button onClick={() => setLocation('/users/42')}>
        Go to User 42
      </button>
    </div>
  );
}

function UserList() {
  const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>
          <Link href={`/users/${user.id}`}>{user.name}</Link>
        </li>
      ))}
    </ul>
  );
}

function UserProfile({ userId }) {
  const params = useParams();
  const [user, setUser] = useState(null);
  
  useState(() => {
    fetch(`/api/users/${userId}`)
      .then(r => r.json())
      .then(setUser);
  }, [userId]);

  return <h2>User Profile: {user?.name || userId}</h2>;
}

function NotFound() {
  return <h1>404 - Page Not Found</h1>;
}

export default App;

Use Cases

Pros & Cons

Pros

+Extremely small bundle size (~1.5KB gzipped) with zero dependencies, ideal for performance-sensitive applications
+Modern hook-based API provides low-level control for custom navigation logic, animations, and conditional rendering
+Works seamlessly with both React and Preact without configuration changes or adapters
+Simple mental model with no complex nested route configurations or special components to learn
+Server-side rendering support through custom location hooks enables universal applications

Cons

−No React Native support—strictly for web applications using browser history or custom location implementations
−Missing advanced features like route guards, data loaders, code splitting utilities, or nested route layouts
−No HashRouter or MemoryRouter built-in, requiring custom location hooks for non-standard history management
−Limited TypeScript support compared to newer routers built with TypeScript-first APIs
−Requires ES6+ browser support or manual Babel configuration for older environments like IE11