web-router

A tiny, modern client-side router built on the Navigation API and URL Pattern API. Designed for web components, works with anything.

AI used for code cleanup, code review, writing some tests etc. All code is human tested and reviewed. Based on an even simpler router I built by hand that I wanted to improve

Features

~1.5 kB gzipped — minimal footprint, zero runtime dependencies
Navigation API — built on the platform
URL Pattern API — standard route matching with :param syntax
View Transitions — automatic integration for smooth page animations
Route Params — extracted and passed directly to your render function
TypeScript — fully typed with generic render output

Installation

npm install web-router

Quick Start

With Lit

import { Router, type Route } from 'web-router';
import { LitElement, html } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import type { TemplateResult } from 'lit';

const routes: Route<TemplateResult>[] = [
  {
    path: '/',
    title: 'Home',
    render: () => html`<home-page></home-page>`,
  },
  {
    path: '/user/:id',
    title: 'User Profile',
    render: (params) => html`<user-page .userId=${params.id}></user-page>`,
  },
];

const router = new Router({ routes });

@customElement('my-app')
export class MyApp extends LitElement {
  @state() private _route = router.getCurrentRoute();

  async connectedCallback() {
    super.connectedCallback();
    router.addEventListener('route-changed', this._onRouteChanged);
    await router.init();
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    router.removeEventListener('route-changed', this._onRouteChanged);
    router.destroy();
  }

  private _onRouteChanged = () => {
    this._route = router.getCurrentRoute();
    this.requestUpdate();
  };

  render() {
    return html`
      <nav>
        <a href="/">Home</a>
        <a href="/user/42">User 42</a>
      </nav>
      <main>${router.render()}</main>
    `;
  }
}

With Vanilla Web Components

import { Router, type Route } from 'web-router';

const routes: Route<HTMLElement>[] = [
  {
    path: '/',
    title: 'Home',
    render: () => document.createElement('home-page'),
  },
  {
    path: '/about',
    title: 'About',
    render: () => document.createElement('about-page'),
  },
];

const router = new Router({ routes });

router.addEventListener('route-changed', () => {
  const outlet = document.getElementById('outlet')!;
  outlet.innerHTML = '';
  const content = router.render();
  if (content) outlet.appendChild(content);
});

await router.init();

Route Params

Route paths use URL Pattern syntax. Params are extracted automatically and passed to your render function.

const routes: Route<TemplateResult>[] = [
  {
    // Static route — no params
    path: '/about',
    title: 'About',
    render: () => html`<about-page></about-page>`,
  },
  {
    // Single param
    path: '/user/:id',
    title: 'User',
    render: (params) => html`<user-page .userId=${params.id}></user-page>`,
  },
  {
    // Multiple params
    path: '/post/:postId/comment/:commentId',
    title: 'Comment',
    render: (params) => html`
      <comment-page
        .postId=${params.postId}
        .commentId=${params.commentId}
      ></comment-page>
    `,
  },
];

You can also access params programmatically:

const params = router.getCurrentParams();
console.log(params.id); // "42"

Plugins

Plugins hook into the navigation lifecycle. They can run before and after navigation, cancel navigation, or redirect.

Lazy Loading

The built-in lazy plugin loads modules on demand:

import { lazy } from 'web-router/lazy';

const routes: Route<TemplateResult>[] = [
  {
    path: '/dashboard',
    title: 'Dashboard',
    plugins: [lazy(() => import('./pages/dashboard.js'))],
    render: () => html`<dashboard-page></dashboard-page>`,
  },
];

Guards

Return false from beforeNavigation to cancel navigation:

const authGuard: RouterPlugin = {
  name: 'auth',
  beforeNavigation: async (ctx) => {
    if (ctx.route.path === '/admin' && !isAuthenticated()) {
      return false; // cancel — user stays on current page
    }
  },
};

const router = new Router({
  routes,
  plugins: [authGuard], // runs on every route
});

Redirects

Return a path string from beforeNavigation to redirect:

const redirectPlugin: RouterPlugin = {
  name: 'redirect',
  beforeNavigation: async (ctx) => {
    if (ctx.route.path === '/admin' && !isAuthenticated()) {
      return '/login'; // redirect to login page
    }
  },
};

Redirects go through the Navigation API — the browser updates the URL, manages history, and handles loop prevention natively.

Analytics

Use afterNavigation to run code after the page has rendered:

const analytics: RouterPlugin = {
  name: 'analytics',
  afterNavigation: (ctx) => {
    trackPageView(ctx.url.pathname, ctx.params);
  },
};

Plugin Context

Both beforeNavigation and afterNavigation receive a NavigationContext:

interface NavigationContext<TRender = unknown> {
  route: Route<TRender>;    // the matched route config
  params: RouteParams;       // extracted URL params
  url: URL;                  // the destination URL
}

Global vs Per-Route Plugins

Global plugins run on every navigation. Per-route plugins run only for that route. Global plugins always run first.

const router = new Router({
  routes: [
    {
      path: '/admin',
      title: 'Admin',
      plugins: [authGuard, lazy(() => import('./pages/admin.js'))],
      render: (params) => html`<admin-page></admin-page>`,
    },
  ],
  plugins: [analytics], // runs on every navigation
});

Error Handling

Plugin errors are caught and emitted as error events. If a beforeNavigation plugin throws, navigation is cancelled.

router.addEventListener('error', (event: CustomEvent) => {
  const { error, plugin, route } = event.detail;
  console.error(`Plugin "${plugin.name}" failed on ${route.path}:`, error);
});

Navigation State

Pass arbitrary state during navigation and retrieve it later:

// Navigate with state
await router.navigate('/user/123', {
  state: { user: userData, fromPage: 'search' },
});

// Retrieve state in your component
interface UserPageState {
  user: User;
  fromPage: string;
}

const state = router.getNavigationState<UserPageState>();
if (state?.user) {
  this.user = state.user; // skip the fetch
}

Query Strings and Hash

Use getURL() to access query parameters and hash:

// URL: /search?q=router&page=2#results

const urlInfo = router.getURL();
urlInfo.pathname;                  // "/search"
urlInfo.search;                    // "?q=router&page=2"
urlInfo.searchParams.get('q');     // "router"
urlInfo.searchParams.get('page');  // "2"
urlInfo.hash;                      // "#results"

Wildcard / 404 Routes

Use /* as a catch-all. Place it last — routes are matched in definition order.

const routes: Route<TemplateResult>[] = [
  { path: '/', title: 'Home', render: () => html`<home-page></home-page>` },
  { path: '/about', title: 'About', render: () => html`<about-page></about-page>` },
  // Catch-all — must be last
  { path: '/*', title: 'Not Found', render: () => html`<not-found-page></not-found-page>` },
];

View Transitions

The router automatically uses the View Transitions API when available. No configuration needed — just add CSS:

/* Crossfade (default behavior) */
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 0.25s;
}

/* Slide transition for a specific element */
.page-content {
  view-transition-name: page;
}

::view-transition-old(page) {
  animation: 0.25s ease-out slide-to-left;
}

::view-transition-new(page) {
  animation: 0.25s ease-out slide-from-right;
}

@keyframes slide-to-left {
  to { transform: translateX(-100%); }
}

@keyframes slide-from-right {
  from { transform: translateX(100%); }
}

Cleanup

Call destroy() to remove all event listeners and reset state. The router can be re-initialized after destruction.

router.destroy();

// Later, if needed:
await router.init();

API Reference

`Router<TRender>`

Extends EventTarget.

Constructor

new Router<TRender>(options: RouterOptions<TRender>)

Methods

Method	Returns	Description
`init()`	`Promise<void>`	Initialize the router, set up listeners, handle initial route
`navigate(path, options?)`	`Promise<void>`	Navigate to a path, optionally with state
`render()`	`TRender \| null`	Render the current route, or `null` if no match
`getCurrentRoute()`	`Route<TRender> \| null`	Get the current matched route config
`getCurrentParams()`	`RouteParams`	Get the current extracted URL params
`getURL()`	`{ pathname, search, hash, searchParams } \| null`	Get parsed URL info
`getNavigationState<T>()`	`T \| undefined`	Get state from the current history entry
`destroy()`	`void`	Remove listeners, clear state, allow re-init

Events

Event	Detail	Description
`route-changed`	`{ route, params }`	Fired after navigation completes and DOM updates
`error`	`{ error, plugin, route }`	Fired when a plugin throws

`Route<TRender>`

interface Route<TRender = unknown> {
  path: string;                          // URL pattern (e.g. "/user/:id")
  title: string;                         // document.title on match
  render: (params: RouteParams) => TRender;  // render function
  plugins?: RouterPlugin<TRender>[];     // per-route plugins
}

`RouterPlugin<TRender>`

interface RouterPlugin<TRender = unknown> {
  name?: string;
  beforeNavigation?: (ctx: NavigationContext<TRender>) =>
    void | boolean | string | Promise<void | boolean | string>;
  afterNavigation?: (ctx: NavigationContext<TRender>) =>
    void | Promise<void>;
}

beforeNavigation return values:

void or true — continue navigation
false — cancel navigation
string — redirect to that path

`NavigationContext<TRender>`

interface NavigationContext<TRender = unknown> {
  route: Route<TRender>;                          // matched route
  params: Record<string, string | undefined>;      // URL params
  url: URL;                                        // destination URL
}

`RouteParams`

type RouteParams = Record<string, string | undefined>;

`lazy(importFn)`

import { lazy } from 'web-router/lazy';

lazy(() => import('./pages/my-page.js')): RouterPlugin

Browser Support

Requires the Navigation API and URL Pattern API.

Browser	Version
Chrome	102+
Edge	102+
Firefox	147+
Safari	26.2+

Coming from @lit-labs/router

This router can serve as a replacement for @lit-labs/router. Key differences:

Feature	@lit-labs/router	web-router
API style	Reactive controller	Standalone class + events
Route params	Via URLPattern result	Passed directly to `render(params)`
Navigation guards	`enter()` callback returning `boolean`	Plugin `beforeNavigation` returning `false` or redirect string
Lazy loading	Manual in `enter()`	Built-in `lazy()` plugin
Outlet	`outlet()` method	`render()` method
View Transitions	Not built-in	Automatic
Lifecycle hooks	None	`beforeNavigation` + `afterNavigation`
Cleanup	Tied to component lifecycle	Explicit `destroy()`

Migration example

// @lit-labs/router
import { Router } from '@lit-labs/router';

class MyApp extends LitElement {
  private router = new Router(this, [
    { path: '/', render: () => html`<home-page></home-page>` },
    {
      path: '/user/:id',
      enter: async (params) => {
        await import('./pages/user.js');
        return true;
      },
      render: ({ id }) => html`<user-page .userId=${id}></user-page>`,
    },
  ]);

  render() {
    return html`${this.router.outlet()}`;
  }
}

// web-router
import { Router, type Route } from 'web-router';
import { lazy } from 'web-router/lazy';

const routes: Route<TemplateResult>[] = [
  { path: '/', title: 'Home', render: () => html`<home-page></home-page>` },
  {
    path: '/user/:id',
    title: 'User',
    plugins: [lazy(() => import('./pages/user.js'))],
    render: (params) => html`<user-page .userId=${params.id}></user-page>`,
  },
];

const router = new Router({ routes });

class MyApp extends LitElement {
  // ... (see Quick Start above for full example)
  render() {
    return html`${router.render()}`;
  }
}

License

GPL-2

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
WORK.md		WORK.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

web-router

Features

Installation

Quick Start

With Lit

With Vanilla Web Components

Route Params

Plugins

Lazy Loading

Guards

Redirects

Analytics

Plugin Context

Global vs Per-Route Plugins

Error Handling

Navigation State

Query Strings and Hash

Wildcard / 404 Routes

View Transitions

Cleanup

API Reference

Router<TRender>

Constructor

Methods

Events

Route<TRender>

RouterPlugin<TRender>

NavigationContext<TRender>

RouteParams

lazy(importFn)

Browser Support

Coming from @lit-labs/router

Migration example

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`Router<TRender>`

`Route<TRender>`

`RouterPlugin<TRender>`

`NavigationContext<TRender>`

`RouteParams`

`lazy(importFn)`

Packages