lit-ui-router

A UI-Router implementation for Lit.

Quick Start

import { UIRouterLit, LitStateDeclaration } from 'lit-ui-router';
import { hashLocationPlugin } from '@uirouter/core';
import { html } from 'lit';

const router = new UIRouterLit();
router.plugin(hashLocationPlugin);

const states: LitStateDeclaration[] = [
  { name: 'home', url: '/', component: () => html`<h1>Home</h1>` },
  { name: 'about', url: '/about', component: () => html`<h1>About</h1>` },
];
states.forEach((state) => router.stateRegistry.register(state));

router.start();

Entry Points

| Import | Effect | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | import { ... } from 'lit-ui-router' | Full API. Any value import registers the <ui-router>/<ui-view> custom elements as a side effect. | | import { ... } from 'lit-ui-router/pure' | The same full API — element classes included — with no registration and no HTMLElementTagNameMap globals. | | import 'lit-ui-router/register' | Registration only: defines <ui-router>/<ui-view> and carries their HTMLElementTagNameMap entries. | | import 'lit-ui-router/ui-view.register' | Single-element registration: defines just that element with its tag-map entry (ui-router.register ditto). | | import type { ... } from 'lit-ui-router' | Types are erased at compile time — always free, from any entry. |

The root entry is exactly pure + register: reach for lit-ui-router/pure when you need the APIs (or the element classes themselves, e.g. for scoped registries or custom tag names) without touching the global registry, and pair it with lit-ui-router/register — or a single *.register entry — to opt into registration explicitly.

Component Styles

| Style | Best For | Example | | ------------------- | ----------------------------- | -------------------------- | | Template function | Simple views, prototyping | () => html`...` | | Template with props | Views needing params/resolves | (props) => html`...` | | LitElement class | Complex views with lifecycle | MyComponent |

Reacting to Transitions

Any element (routed or not) can stay synchronized with the router using the TransitionController reactive controller. It registers transition hooks when the host connects, calls host.requestUpdate() on matching transitions, and deregisters everything when the host disconnects — no manual requestUpdate() plumbing or leaked hooks.

import { TransitionController } from 'lit-ui-router';

class NavHeader extends LitElement {
  private transitions = new TransitionController(this);

  render() {
    // Re-evaluated after every successful transition
    return html`Current state: ${this.transitions.current?.name}`;
  }
}

Scope it to specific states or react to parameter changes with a callback:

class UserDetail extends LitElement {
  private transitions = new TransitionController(this, {
    criteria: { to: 'users.detail' },
    callback: () => this.loadUser(this.transitions.params.userId),
  });
}

Documentation

Visit lit-ui-router.dev for full documentation, tutorials, and API reference.