lit-navigation-router

A router for Lit, built on the Navigation API.

Fork of @lit-labs/router — see NOTICE.md for provenance, licence and the full list of changes. Not affiliated with or endorsed by Google or the Lit team.

npm i lit-navigation-router

Why

Upstream commits navigation with history.pushState() and reacts to popstate, but swaps the outlet only after awaiting route.enter(). The URL therefore leads and the outlet lags, so the route being left re-renders with stale params and two quick navigations can commit out of order.

navigateEvent.intercept() removes that: the browser commits the URL and holds the navigation un-finished while the handler runs, and aborts navigateEvent.signal when a newer navigation supersedes this one.

Usage

Identical to upstream:

import {Router} from 'lit-navigation-router/router.js';

class MyApp extends LitElement {
  private _router = new Router(this, [
    {path: '/', render: () => html`<h1>Home</h1>`},
    {
      path: '/item/:id',
      enter: async () => {
        await import('./item-view.js'); // awaited before the outlet swaps
        return true;
      },
      render: ({id}) => html`<item-view .id=${id}></item-view>`,
    },
  ]);

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

Two additions:

// Forwarded to navigateEvent.intercept()
this._router.interceptOptions = {scroll: 'manual', focusReset: 'manual'};

// goto() takes an abort signal; Router passes navigateEvent.signal for you
await routes.goto('/item/1', {signal});

Browser support — please read

This router requires the Navigation API. There is no legacy fallback.

The API is Baseline Newly Available (January 2026: Chrome/Edge, Safari 26.2, Firefox 147). Baseline Widely Available is not until roughly mid-2028, so older engines are still in the wild.

On an engine without it, Router renders the current route on load but does not intercept navigation — every link becomes an ordinary full page load. If your server serves the app shell on every route that is slower, not broken. If it does not, those links 404.

One case is genuinely broken, not just slow. If you navigate programmatically with history.pushState() + router.goto(), nothing listens for the resulting popstate — so Back moves the URL while the outlet stays put, which is the URL/outlet split this fork exists to eliminate. Apps using that pattern should gate on supportsNavigationApi() rather than accept the degradation.

supportsNavigationApi() is exported so you can detect this at boot:

import {supportsNavigationApi} from 'lit-navigation-router/router.js';

if (!supportsNavigationApi()) {
  showUpgradePrompt();
}

If you need real pre-2026 support, pair this with a Navigation API polyfill rather than a second router: one decision path, with compatibility isolated in a layer whose whole job is spec accuracy.

URLPattern

Route patterns are compiled with URLPattern, which this package uses from the global scope and does not polyfill — same as upstream. Every engine that has the Navigation API also has URLPattern, so if the support check above passes you need nothing. If you support older engines anyway, load urlpattern-polyfill before the router:

import {URLPattern} from 'urlpattern-polyfill';
if (!globalThis.URLPattern) {
  (globalThis as {URLPattern?: unknown}).URLPattern = URLPattern;
}

The published types do not depend on it — URLPatternRouteConfig.pattern is typed structurally, so a consumer build never needs the polyfill's types.

Develop

npm install
npm run build        # tsc → development/
npm test             # Web Test Runner (Chromium via Playwright)
npm run check-types